--- group: title: 通用组件 order: 2 title: StandardFilter order: 1 toc: content --- # StandardFilter 筛选工具栏 > 用在表格上方的筛选工具栏 ## 代码演示 ### 基础用法 ### 按钮组配置 ### 排版模式 表单控件排列使用`layout`配置，表单与按钮组使用 最终呈现的栅格数：`itemGroupConfig.columnCount`优先级高于``itemGroupConfig.size`` ### 可折叠与展开 仅在`layout='horizontal'`上有效，启用配置`collapseable={true}` 如遇表单控件需要额外占用更多的空间时，可对其表单项进行配置`colSpan` * 其中`colSpan`必须是其栅格数的倍数（例如4列的情况，只能是 6、12、18; 3列的情况，只能是8、16；尽量不要配置24，排列会有问题） * 再适当配置对应的`display` , display: { labelCol: {span: 4}, wrapperCol: {span: 20} } * 视情况调整表单项的排列顺序，保证筛选按钮能够在最右侧显示 * 具体查看"操作时间"的配置值说明 可能报错的排版（v4.1.11已修复） * 如在4列的情况下，当中有一个`colSpan=12`,且前面有三个默认的表单项`(span=6)`时，按钮位置可能报错（组件内calculateHideCount计算不需要-1就会正常） * 如在4列的情况下，`colSpan=12`后面跟着一个默认的表单项`(span=6)`时，（出现两行这种情况），按钮位置可能报错 * 如在3列的情况下，当中有一个`colSpan=16`,且前面有两个默认的表单项`(span=6)`时，按钮位置可能报错（组件内calculateHideCount计算不需要-1就会正常） ### 格式转换 如果提交的表单用于地址栏（或保存提交时）时，可能存在使用的字段不是数组而是单个对象 *例如:* 1. `transform()`将 `creatTime=[date1, date2]`需要转换`startTim`跟`endTime`使用,并且需要将日期格式化成字符串。 2. `parseTransform()`将则将`startTim`跟`endTime`的字符串转换成时间格式并合并成数组 `creatTime=[dayjs('xx'), dayjs('xx')]` > description="如果有报错（特别是日期类的控件），可配合`forceListener=false`使用(此条忽略， `v4.1.47`forceListener已弃用） > > 如有问题提出再进行修复 ### 全局配置 ## API | 参数字段 | 说明 | 类型 | 必选项 | 默认值/参考值 | |---------------------------------|-----------------------------------------------------------------------------------------------|:------------------------------------|:-----|:----------------------------------------------------------------------------| | formItemGroup | 表单组 | Array or ReactNode | 是 | Array字段查看 [formItemGroup API](#formitemgroup-api) | | itemGroupConfig | 表单组配置项 | Object | 是 | Array字段查看 [itemGroup API](/components/item-group#api) | | filterButtonColSpan | `formLayout='horizontal'`下，"查询重置按钮"占用栅格数（主要用于自定义了表单控件布局导致计算剩余空间错误情况下使用） | Number | - | 最大不超过24 | | filterButtonConfig | `formLayout='horizontal'`下，"查询重置按钮"扩展配置，里面的`colSpan`优先级大于`filterButtonColSpan` | Object | - | [配置项 API](/components/item-group#itemgroup-api) | | buttonGroup | 按钮组 | Array or ReactNode | 否 | Array值查看 [buttongroup API](#buttongroup-api) | | ❗️buttonGroupConfig | 按钮组扩展配置【❗作用范围变化，下拉菜单配置则用`buttonGroupConfig.dropdownConfig`】~~按钮组下拉菜单配置~~ | Object | 否 | [buttongroupConfig API](/components/button-group#api) ~~参考官网的Dropdown API~~ | | buttonGroupPlacement | `formLayout='horizontal'`下，按钮组放置位置 | | 否 | `left(默认)` \ `right` | | min | 按钮展示最少数量（最小不能小于2） | `Number` | - | 3 | | onFilterSearch | 点击查询搜索条件 | `Function(fields)` | 是 | - | | onFilterReset | 点击重置搜索条件，不配置则不显示重置按钮 | `Function(fields)` | 否 | - | | onFilterChange(`v4.1.18`) | 配置直接筛选触发(不与查询、重置一起使用） | `Function(fieldValues, fieldValue)` | | ‼️注意，列表上不建议配置输入框做实时搜索，可能会有问题 | | initialValues | 表单控件默认值，只有初始化以及重置时生效 | `object` | - | [‼️注意事项️](#initialvalues注意事项) | | getFormFields(尽量少用) | 获取表单字段值及表单实例 | `Function(fields,form)` | - | | | codes | 功能权限数据 | `Array` | - | - | | permissionCodes | 当前有权限的按钮code值组合 | `Array` | - | `["codeBtnDetail", "codeBtnDetail"]` | | confirmText | 确认按钮显示文本 | `String` | 否 | '查询' | | confirmButtonProps | 查询按钮配置 | `Object` | `否 | 参数官方Button配置 | | cancelText | 取消按钮显示文本 | `String` | 否 | '重置' | | cancelButtonProps | 重置按钮组配置 | `Object` | 否 | 参数官方Button配置 | | gridLayout | 表单与按钮组件排列 | `String` | 否 | `inline`/`horizontal` | | formLayout | 表单控件排列方式 | `String` | 否 | `inline`/`horizontal`/`vertical` | | colon | 是否显示 label 后面的冒号 | `Boolean` | true | - | | filterFormStyle | 配置表单组的扩展样式 | `Object` | - | - | | filterBtnsStyle | 配置按钮组的扩展样式 | `Object` | - | - | | dateFormatter | 设置为`string`时，表示赋值与搜索提交时，值都是string格式（内部会转换成dayjs） | `String` | - | `dayjs`/ `string` | | collapseable | 是否启用展开收缩功能 | `Boolean` | - | `false` | | parseTransform | 筛选提交的参数转换后进行重新组件，例如 creatTime转换成了startTime跟endTime,然后提交的时候把creatTime删除了，所以如果需要再反过来赋值则需要重新转换回来 | `(values)=>values`) | 否 | | | ~~forceListener~~( `v4.1.47`弃用) | 是否启动实时监听initialValues来重置表单值 | `Boolean` | 否 | `true` | | actionsOrder(v4.1.10) | 配置确认与取消按钮顺序 | `Array` | 否 | ['cancel', 'confirm', 'collapse'] | > `forceListener=false`时，如需要表单更新则自行使用 ref获取表单相关实例进行处理（`resetFields`等,且最好不使用getFormFields获取实例，而是用ref）。在 ``中默认将禁用,如需要触发更新，则使用实例`filterFormRef.current.resetFields` ### formItemGroup API | 参数字段 | 说明 | 类型 | 必选项 | 参考值 | |----------------------|-----------------------------------------------------------------|-------------------------------------|-----|-------------------------------------------------------------------------------------------------------------------| | label | 标签名称/条件名称 | String | 是 | - | | type | 控件类型 | String | 是 | 可以选择 `input`/`select`/`custom`等，参考[可选值](/components/item-group#type-可选值) | | filedName | 控件名称,配置到Form.Item的`name`属性 | String | 是 | 参考 | | ~~filedOptions~~(弃用) | 控件配置项 | String | 否 | 参考 [getFieldDecorator(id, options) 参数](https://ant.design/components/form-cn/#getFieldDecorator(id,-options)-参数) | | selectOptions | 选项列表 | Array | 否 | select/radio/checkbox等使用 ,选项值：{'label': 'xxx', value: 'xxx'} | | rules(新增) | 校验规则，设置字段的校验逻辑。 | Array | 否 | [官网API](https://ant.design/components/form-cn/#Rule) | | protoFormItem | Form.Item 原始参数 | Array | 否 | [官网API](https://ant.design/components/form-cn/#Form.Item) | | isHide | 是否隐藏当前配置的组件(需要结合`protoFormItem.shouldUpdate`使用) | Boolean/Function(fieldValues, form) | 否 | fieldValues指当前配置表单内部的所有控件值，form指当前弹窗内部的表单实例 | | transform | 提交值格式转换 | `(values)=> {}` | 否 | `transform: (value) => { return { startTime: value[0],endTime: value[1],};}` | | 其他 | 其他配置项目可查看 [itemGroup API](/components/item-group#itemgroup-api) | - | - | - | ### buttonGroup API | 参数字段 | 说明 | 类型 | 必选项 | |----------------|--------------------------------------------------------|------------------|--------------| | name | 按钮文本 | String | 是 | | exName | 当设置code时，会优先使用exName作为按钮上的文本显示值 | String | 否 | | code | 权限code，可决定name即按钮上的显示值，覆盖name值 | String | 否 | | isHide | 隐藏当前按钮 | Boolean | 否 | | icon | 图标类名 | String/ReactNode | 否 | | type | 按钮类型 | String | 否 | | fn | 按钮点击事件 | Function | 否 | | disabled | 禁用当前按钮 | Boolean | 否 | | dropdownConfig | 当前下拉菜单配置 | Object | 参考官网Dropdown | | 其他配置 | 参考[button-group](/components/button-group#options-api) | - | - | ### initialValues注意事项 **赋值情况1（`v4.1.47`可忽略查看下面“赋值情况4”）**：如果`initialValues={query}`,赋值是使用了query（url上的search参数） 1. 若`forceListener=true`时，不可与`getFormField`同时使用； - 因为如果在`getFormField(fields,form)`方法内使用了`useState()`实时取fields或form时，将会同时触发监听`query`，就导致了组件内部监听`initialValues`发生溢出 2. 若`forceListener=false`时，可与`getFormField`同时使用;但如果在其他地方需要触发表单更新值则需要使用`ref`获取表单相关实例进行处理（form.setFieldsValue()） **赋值情况2（`v4.1.47`可忽略查看下面“赋值情况4”）**：如果`initialValues={fieValues}`,赋值使用其他变量( `const [fieValues, setFieValues] = useState({})`) 3. 若`forceListener=true`时，可与`getFormFields`同时使用 - 但是getFormFields内不能去更新`fieValues`(如`getFormFields={(field)=> {setFieValues(field)}}`，是不允许使用)，如果非要更新，则需要配置`forceListener=false` **赋值情况3（`v4.1.47`）**： 支持传`{}`，内部已做了容易错处理，并已修复重复更新溢出问题 **赋值情况4（`v4.1.47`）**： 如果`initialValues={query}`,赋值是使用了query（url上的search参数） - 1. 使用 `getFormFields`时,不要用`useState`，而是使用`useRef`获取表单相关实例 - 2. 如果非要获取表单实例，建议优先使用`ref`，少用`getFormFields` ```javascript import { useLocation } from 'umi' export const StandardFilterFields = () => { const location = useLocation() const query = parse(location.search, { ignoreQueryPrefix: true, }); const filterRef = useRef() // 优先使用ref获取表单实例 // const [filterFields, setFilterFields] = useState({}) // 不要使用 // const [filterForm, setFilterForm] = useState({}) // 不要使用 const filterFormRef = useRef() // 建议使用 const filterFieldsRef = useRef() // 建议使用 useEffect(() => { // 监听表单值变化 }, [filterFieldsRef?.current]); return { console.log('filter-form', form) // setFilterFields(fields); // 不要使用 // setFilterForm(form); // 不要使用 filterFormRef.current = form; // 建议使用 filterFieldsRef.current = fields; // 建议使用 } } /> } ```