@kne/react-filter 1.0.4 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +283 -227
  2. package/dist/index.js +66 -9
  3. package/dist/index.js.map +1 -1
  4. package/dist/index.modern.js +64 -10
  5. package/dist/index.modern.js.map +1 -1
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -562,6 +562,50 @@ render(<BusinessSelectExample />);
562
562
 
563
563
  ```
564
564
 
565
+ - 搜索输入
566
+ - 使用 SearchInput 实现顶部关键词搜索，输入停止 500ms 后自动提交筛选值，输入法组合输入完成后才开始触发搜索
567
+ - _ReactFilter(@kne/current-lib_react-filter)[import * as _ReactFilter from "@kne/react-filter"],(@kne/current-lib_react-filter/dist/index.css),antd(antd)
568
+
569
+ ```jsx
570
+ const { SearchInput, FilterProvider, getFilterValue } = _ReactFilter;
571
+ const { Flex, Button, Typography, message } = antd;
572
+ const { useState } = React;
573
+
574
+ const SearchInputExample = () => {
575
+ const [filterValue, setFilterValue] = useState([]);
576
+
577
+ const handleSearch = () => {
578
+ const params = getFilterValue(filterValue);
579
+ message.info(&#96;搜索参数: ${JSON.stringify(params)}&#96;);
580
+ console.log('搜索参数:', params);
581
+ };
582
+
583
+ return (
584
+ <Flex vertical gap={16}>
585
+ <Typography.Title level={4}>SearchInput 搜索输入</Typography.Title>
586
+ <Typography.Paragraph style={{ margin: 0 }}>
587
+ 输入停止 500ms 后自动写入筛选值并触发搜索；中文等输入法组合输入期间不会触发搜索，确认文本后才开始计时。按回车或点击搜索按钮会立即提交。 清空后也会在 500ms 后移除该筛选条件。
588
+ </Typography.Paragraph>
589
+ <FilterProvider value={filterValue} onChange={setFilterValue}>
590
+ <Flex gap={8} align="center">
591
+ <SearchInput name="keyword" label="关键词" placeholder="请输入关键词" style={{ width: 320 }} allowClear />
592
+ <Button type="primary" onClick={handleSearch}>
593
+ 查看搜索参数
594
+ </Button>
595
+ </Flex>
596
+ </FilterProvider>
597
+ <Flex gap={8}>
598
+ <span>当前筛选值:</span>
599
+ <pre style={{ margin: 0, background: '#f5f5f5', padding: 8, borderRadius: 4, flex: 1 }}>{JSON.stringify(filterValue, null, 2)}</pre>
600
+ </Flex>
601
+ </Flex>
602
+ );
603
+ };
604
+
605
+ render(<SearchInputExample />);
606
+
607
+ ```
608
+
565
609
  - 已选值展示
566
610
  - 使用 FilterValueDisplay 组件展示已选择的筛选条件，支持单独删除和清空全部
567
611
  - _ReactFilter(@kne/current-lib_react-filter)[import * as _ReactFilter from "@kne/react-filter"],(@kne/current-lib_react-filter/dist/index.css),antd(antd)
@@ -759,36 +803,36 @@ render(<PopoverItemExample />);
759
803
 
760
804
  #### 属性
761
805
 
762
- | 属性 | 类型 | 默认值 | 说明 |
763
- |--------------|------------------------------------------------------|--------|-----------------|
764
- | value | `Array<{ name: string, label: string, value: any }>` | - | 筛选值数组 |
765
- | defaultValue | `Array<{ name: string, label: string, value: any }>` | `[]` | 默认筛选值 |
766
- | onChange | `(value: Array) => void` | - | 筛选值变化回调 |
767
- | list | `Array<Array>` | `[]` | 筛选项配置数组，支持多行 |
768
- | displayLine | `number` | `1` | 默认展示的行数，超出部分折叠 |
769
- | label | `string` | `'筛选'` | 筛选区域标题 |
770
- | extra | `ReactNode` | - | 额外操作区域，通常放置搜索按钮 |
771
- | extraExpand | `ReactNode` | - | 已选区域额外内容 |
772
- | className | `string` | - | 自定义类名 |
806
+ | 属性 | 类型 | 默认值 | 说明 |
807
+ | ------------ | ---------------------------------------------------- | -------- | ------------------------------ |
808
+ | value | `Array<{ name: string, label: string, value: any }>` | - | 筛选值数组 |
809
+ | defaultValue | `Array<{ name: string, label: string, value: any }>` | `[]` | 默认筛选值 |
810
+ | onChange | `(value: Array) => void` | - | 筛选值变化回调 |
811
+ | list | `Array<Array>` | `[]` | 筛选项配置数组，支持多行 |
812
+ | displayLine | `number` | `1` | 默认展示的行数，超出部分折叠 |
813
+ | label | `string` | `'筛选'` | 筛选区域标题 |
814
+ | extra | `ReactNode` | - | 额外操作区域，通常放置搜索按钮 |
815
+ | extraExpand | `ReactNode` | - | 已选区域额外内容 |
816
+ | className | `string` | - | 自定义类名 |
773
817
 
774
818
  #### 静态方法
775
819
 
776
- | 方法 | 说明 |
777
- |-------------------------------------------------|-----------------------------------------------------------------------|
778
- | `Filter.getFilterValue(filterValue)` | 将筛选值数组转换为参数对象，如 `{ name: value }` |
779
- | `Filter.useFilter()` | 获取 Filter Context，返回 `{ value, onChange }` |
780
- | `Filter.pickSelectValues(value)` | 从筛选值中提取原始值数组，支持 `{ value }`、`{ id }` 格式 |
781
- | `Filter.createFilterValueMapper(fieldMappers)` | 声明式创建 mapFilterValue 函数，按字段映射转换规则 |
782
- | `Filter.filterToUrlParams(filterValue, options)`| 将筛选值数组序列化为 URLSearchParams，保留 label 信息 |
783
- | `Filter.parseFilterEntry(str)` | 解析 URL 参数中的单个筛选值项为 `{ label, value }` |
784
- | `Filter.takeFilterEntry(searchParams, key, options)` | 从 URL 参数中读取筛选值项，支持单选/多选 |
785
- | `Filter.createUrlFilterReader(searchParams)` | 创建 URL 筛选参数读取器，自动追踪已消费的参数 key |
786
- | `Filter.useUrlFilter(options)` | 从 URL 参数初始化 Filter 状态的 hook（React Router 环境） |
787
- | `Filter.useUrlFilterValue(mapping)` | useUrlFilter 的简化版，基于 filterParams[key] 格式自动解析 URL 参数 |
788
- | `Filter.createUrlParamsReader(searchParams)` | 创建通用 URL 参数读取器，自动追踪已消费的参数 key |
789
- | `Filter.stripConsumedUrlParams(searchParams, consumedKeys)` | 从 URL 参数中移除已消费的 key，返回新的 URLSearchParams 或 null |
790
- | `Filter.filterInterceptors.single` | 单选拦截器：`{id, name}` ↔ `{label, value}` 数据格式转换 |
791
- | `Filter.filterInterceptors.multi` | 多选拦截器：`[{id, name}]` ↔ `[{label, value}]` 数据格式转换 |
820
+ | 方法 | 说明 |
821
+ | ----------------------------------------------------------- | ------------------------------------------------------------------- |
822
+ | `Filter.getFilterValue(filterValue)` | 将筛选值数组转换为参数对象，如 `{ name: value }` |
823
+ | `Filter.useFilter()` | 获取 Filter Context，返回 `{ value, onChange }` |
824
+ | `Filter.pickSelectValues(value)` | 从筛选值中提取原始值数组，支持 `{ value }`、`{ id }` 格式 |
825
+ | `Filter.createFilterValueMapper(fieldMappers)` | 声明式创建 mapFilterValue 函数，按字段映射转换规则 |
826
+ | `Filter.filterToUrlParams(filterValue, options)` | 将筛选值数组序列化为 URLSearchParams，保留 label 信息 |
827
+ | `Filter.parseFilterEntry(str)` | 解析 URL 参数中的单个筛选值项为 `{ label, value }` |
828
+ | `Filter.takeFilterEntry(searchParams, key, options)` | 从 URL 参数中读取筛选值项，支持单选/多选 |
829
+ | `Filter.createUrlFilterReader(searchParams)` | 创建 URL 筛选参数读取器，自动追踪已消费的参数 key |
830
+ | `Filter.useUrlFilter(options)` | 从 URL 参数初始化 Filter 状态的 hook（React Router 环境） |
831
+ | `Filter.useUrlFilterValue(mapping)` | useUrlFilter 的简化版，基于 filterParams[key] 格式自动解析 URL 参数 |
832
+ | `Filter.createUrlParamsReader(searchParams)` | 创建通用 URL 参数读取器，自动追踪已消费的参数 key |
833
+ | `Filter.stripConsumedUrlParams(searchParams, consumedKeys)` | 从 URL 参数中移除已消费的 key，返回新的 URLSearchParams 或 null |
834
+ | `Filter.filterInterceptors.single` | 单选拦截器：`{id, name}` ↔ `{label, value}` 数据格式转换 |
835
+ | `Filter.filterInterceptors.multi` | 多选拦截器：`[{id, name}]` ↔ `[{label, value}]` 数据格式转换 |
792
836
 
793
837
  #### 使用示例
794
838
 
@@ -808,7 +852,7 @@ const { InputFilterItem, NumberRangeFilterItem } = fields;
808
852
  ]}
809
853
  displayLine={1}
810
854
  extra={<Button type="primary">搜索</Button>}
811
- />
855
+ />;
812
856
  ```
813
857
 
814
858
  ---
@@ -819,29 +863,21 @@ const { InputFilterItem, NumberRangeFilterItem } = fields;
819
863
 
820
864
  #### 属性
821
865
 
822
- | 属性 | 类型 | 默认值 | 说明 |
823
- |--------------|------------------------------------------------------|------|----------|
824
- | value | `Array<{ name: string, label: string, value: any }>` | - | 筛选值数组 |
825
- | defaultValue | `Array<{ name: string, label: string, value: any }>` | `[]` | 默认筛选值 |
826
- | onChange | `(value: Array) => void` | - | 筛选值变化回调 |
827
- | list | `Array<Array>` | `[]` | 筛选项配置数组 |
828
- | more | `Array` | - | 额外折叠的筛选项 |
829
- | className | `string` | - | 自定义类名 |
866
+ | 属性 | 类型 | 默认值 | 说明 |
867
+ | ------------ | ---------------------------------------------------- | ------ | ---------------- |
868
+ | value | `Array<{ name: string, label: string, value: any }>` | - | 筛选值数组 |
869
+ | defaultValue | `Array<{ name: string, label: string, value: any }>` | `[]` | 默认筛选值 |
870
+ | onChange | `(value: Array) => void` | - | 筛选值变化回调 |
871
+ | list | `Array<Array>` | `[]` | 筛选项配置数组 |
872
+ | more | `Array` | - | 额外折叠的筛选项 |
873
+ | className | `string` | - | 自定义类名 |
830
874
 
831
875
  #### 使用示例
832
876
 
833
877
  ```javascript
834
878
  import { AdvancedFilter, fields } from '@kne/react-filter';
835
879
 
836
- <AdvancedFilter
837
- value={filterValue}
838
- onChange={setFilterValue}
839
- list={[
840
- [
841
- { type: InputFilterItem, props: { name: 'name', label: '姓名' } }
842
- ]
843
- ]}
844
- />
880
+ <AdvancedFilter value={filterValue} onChange={setFilterValue} list={[[{ type: InputFilterItem, props: { name: 'name', label: '姓名' } }]]} />;
845
881
  ```
846
882
 
847
883
  ---
@@ -852,11 +888,11 @@ import { AdvancedFilter, fields } from '@kne/react-filter';
852
888
 
853
889
  #### 属性
854
890
 
855
- | 属性 | 类型 | 默认值 | 说明 |
856
- |-------------|------------------------------------------------------|-----|---------|
857
- | value | `Array<{ name: string, label: string, value: any }>` | - | 筛选值数组 |
858
- | onChange | `(value: Array) => void` | - | 筛选值变化回调 |
859
- | extraExpand | `ReactNode` | - | 额外展示内容 |
891
+ | 属性 | 类型 | 默认值 | 说明 |
892
+ | ----------- | ---------------------------------------------------- | ------ | -------------- |
893
+ | value | `Array<{ name: string, label: string, value: any }>` | - | 筛选值数组 |
894
+ | onChange | `(value: Array) => void` | - | 筛选值变化回调 |
895
+ | extraExpand | `ReactNode` | - | 额外展示内容 |
860
896
 
861
897
  ---
862
898
 
@@ -866,34 +902,25 @@ import { AdvancedFilter, fields } from '@kne/react-filter';
866
902
 
867
903
  #### 属性
868
904
 
869
- | 属性 | 类型 | 默认值 | 说明 |
870
- |------------------|---------------------------------------------|----------------|-----------|
871
- | label | `string` | - | 筛选项标签 |
872
- | value | `{ label: string, value: any }` | - | 当前值 |
873
- | onChange | `(value: object) => void` | - | 值变化回调 |
874
- | onValidate | `(value: object) => boolean` | - | 确认按钮校验函数 |
905
+ | 属性 | 类型 | 默认值 | 说明 |
906
+ | ---------------- | ------------------------------------------- | -------------- | ------------------ |
907
+ | label | `string` | - | 筛选项标签 |
908
+ | value | `{ label: string, value: any }` | - | 当前值 |
909
+ | onChange | `(value: object) => void` | - | 值变化回调 |
910
+ | onValidate | `(value: object) => boolean` | - | 确认按钮校验函数 |
875
911
  | onOpenChange | `(open: boolean) => void` | - | 弹出层状态变化回调 |
876
- | placement | `string` | `'bottomLeft'` | 弹出层位置 |
877
- | overlayClassName | `string` | - | 弹出层自定义类名 |
878
- | children | `(props: { value, onChange }) => ReactNode` | - | 内容渲染函数 |
912
+ | placement | `string` | `'bottomLeft'` | 弹出层位置 |
913
+ | overlayClassName | `string` | - | 弹出层自定义类名 |
914
+ | children | `(props: { value, onChange }) => ReactNode` | - | 内容渲染函数 |
879
915
 
880
916
  #### 使用示例
881
917
 
882
918
  ```javascript
883
919
  import { PopoverItem } from '@kne/react-filter';
884
920
 
885
- <PopoverItem
886
- label="文本输入"
887
- value={inputValue}
888
- onChange={setInputValue}
889
- >
890
- {({ value, onChange }) => (
891
- <Input
892
- value={value?.value}
893
- onChange={(e) => onChange({ label: e.target.value, value: e.target.value })}
894
- />
895
- )}
896
- </PopoverItem>
921
+ <PopoverItem label="文本输入" value={inputValue} onChange={setInputValue}>
922
+ {({ value, onChange }) => <Input value={value?.value} onChange={e => onChange({ label: e.target.value, value: e.target.value })} />}
923
+ </PopoverItem>;
897
924
  ```
898
925
 
899
926
  ---
@@ -904,12 +931,12 @@ import { PopoverItem } from '@kne/react-filter';
904
931
 
905
932
  #### 属性
906
933
 
907
- | 属性 | 类型 | 默认值 | 说明 |
908
- |----------|-------------|-----|------------|
909
- | label | `string` | - | 筛选项标签 |
910
- | open | `boolean` | - | 是否展开状态 |
911
- | active | `boolean` | - | 是否激活状态（有值） |
912
- | children | `ReactNode` | - | 子元素 |
934
+ | 属性 | 类型 | 默认值 | 说明 |
935
+ | -------- | ----------- | ------ | -------------------- |
936
+ | label | `string` | - | 筛选项标签 |
937
+ | open | `boolean` | - | 是否展开状态 |
938
+ | active | `boolean` | - | 是否激活状态（有值） |
939
+ | children | `ReactNode` | - | 子元素 |
913
940
 
914
941
  ---
915
942
 
@@ -919,13 +946,13 @@ import { PopoverItem } from '@kne/react-filter';
919
946
 
920
947
  #### 属性
921
948
 
922
- | 属性 | 类型 | 默认值 | 说明 |
923
- |-------------|----------------|--------|---------|
924
- | list | `Array<Array>` | `[]` | 筛选项配置数组 |
925
- | displayLine | `number` | `1` | 默认展示行数 |
926
- | label | `string` | `'筛选'` | 标题 |
927
- | extra | `ReactNode` | - | 额外操作区域 |
928
- | className | `string` | - | 自定义类名 |
949
+ | 属性 | 类型 | 默认值 | 说明 |
950
+ | ----------- | -------------- | -------- | -------------- |
951
+ | list | `Array<Array>` | `[]` | 筛选项配置数组 |
952
+ | displayLine | `number` | `1` | 默认展示行数 |
953
+ | label | `string` | `'筛选'` | 标题 |
954
+ | extra | `ReactNode` | - | 额外操作区域 |
955
+ | className | `string` | - | 自定义类名 |
929
956
 
930
957
  ---
931
958
 
@@ -935,12 +962,12 @@ Filter 状态管理组件，用于自定义 Filter 结构。
935
962
 
936
963
  #### 属性
937
964
 
938
- | 属性 | 类型 | 默认值 | 说明 |
939
- |--------------|---------------------------------------|------|----------|
940
- | value | `Array` | - | 筛选值数组 |
941
- | defaultValue | `Array` | `[]` | 默认筛选值 |
942
- | onChange | `(value: Array) => void` | - | 筛选值变化回调 |
943
- | children | `ReactNode \| (context) => ReactNode` | - | 子元素或渲染函数 |
965
+ | 属性 | 类型 | 默认值 | 说明 |
966
+ | ------------ | ------------------------------------- | ------ | ---------------- |
967
+ | value | `Array` | - | 筛选值数组 |
968
+ | defaultValue | `Array` | `[]` | 默认筛选值 |
969
+ | onChange | `(value: Array) => void` | - | 筛选值变化回调 |
970
+ | children | `ReactNode \| (context) => ReactNode` | - | 子元素或渲染函数 |
944
971
 
945
972
  ---
946
973
 
@@ -954,7 +981,7 @@ Filter 状态管理组件，用于自定义 Filter 结构。
954
981
  import { withFilterValue } from '@kne/react-filter';
955
982
 
956
983
  const MyFilterItem = withFilterValue(({ name, label, value, onChange, ...props }) => {
957
- return <Component value={value} onChange={onChange}/>;
984
+ return <Component value={value} onChange={onChange} />;
958
985
  });
959
986
  ```
960
987
 
@@ -976,45 +1003,45 @@ const MyFieldItem = withFieldItem(MyComponent);
976
1003
 
977
1004
  弹出层形式的输入框筛选组件。
978
1005
 
979
- | 属性 | 类型 | 默认值 | 说明 |
980
- |-------------|----------------------|-----|--------|
981
- | name | `string` | - | 字段名称 |
982
- | label | `string` | - | 标签 |
983
- | placeholder | `string` | - | 占位符 |
984
- | onValidate | `(value) => boolean` | - | 确认校验函数 |
1006
+ | 属性 | 类型 | 默认值 | 说明 |
1007
+ | ----------- | -------------------- | ------ | ------------ |
1008
+ | name | `string` | - | 字段名称 |
1009
+ | label | `string` | - | 标签 |
1010
+ | placeholder | `string` | - | 占位符 |
1011
+ | onValidate | `(value) => boolean` | - | 确认校验函数 |
985
1012
 
986
1013
  #### NumberRangeFilterItem 数字区间筛选
987
1014
 
988
1015
  数字区间输入筛选组件。
989
1016
 
990
- | 属性 | 类型 | 默认值 | 说明 |
991
- |-------------|----------|-----|------|
992
- | name | `string` | - | 字段名称 |
993
- | label | `string` | - | 标签 |
994
- | unit | `string` | - | 单位 |
995
- | min | `number` | - | 最小值 |
996
- | max | `number` | - | 最大值 |
997
- | placeholder | `string` | - | 占位符 |
1017
+ | 属性 | 类型 | 默认值 | 说明 |
1018
+ | ----------- | -------- | ------ | -------- |
1019
+ | name | `string` | - | 字段名称 |
1020
+ | label | `string` | - | 标签 |
1021
+ | unit | `string` | - | 单位 |
1022
+ | min | `number` | - | 最小值 |
1023
+ | max | `number` | - | 最大值 |
1024
+ | placeholder | `string` | - | 占位符 |
998
1025
 
999
1026
  #### DatePickerFilterItem 日期筛选
1000
1027
 
1001
1028
  日期选择筛选组件。
1002
1029
 
1003
- | 属性 | 类型 | 默认值 | 说明 |
1004
- |--------|------------------------------------------------------|----------------|-------|
1005
- | name | `string` | - | 字段名称 |
1006
- | label | `string` | - | 标签 |
1030
+ | 属性 | 类型 | 默认值 | 说明 |
1031
+ | ------ | ---------------------------------------------------- | -------------- | ---------- |
1032
+ | name | `string` | - | 字段名称 |
1033
+ | label | `string` | - | 标签 |
1007
1034
  | picker | `'date' \| 'week' \| 'month' \| 'quarter' \| 'year'` | `'date'` | 选择器类型 |
1008
- | format | `string` | `'YYYY-MM-DD'` | 日期格式 |
1035
+ | format | `string` | `'YYYY-MM-DD'` | 日期格式 |
1009
1036
 
1010
1037
  #### DateRangePickerFilterItem 日期范围筛选
1011
1038
 
1012
1039
  日期范围选择筛选组件。
1013
1040
 
1014
- | 属性 | 类型 | 默认值 | 说明 |
1015
- |--------|-------------------------------------|----------------|------|
1041
+ | 属性 | 类型 | 默认值 | 说明 |
1042
+ | ------ | ----------------------------------- | -------------- | -------- |
1016
1043
  | name | `string` | - | 字段名称 |
1017
- | label | `string` | - | 标签 |
1044
+ | label | `string` | - | 标签 |
1018
1045
  | format | `string` | `'YYYY-MM-DD'` | 日期格式 |
1019
1046
  | header | `ReactNode \| (props) => ReactNode` | - | 头部内容 |
1020
1047
 
@@ -1022,24 +1049,24 @@ const MyFieldItem = withFieldItem(MyComponent);
1022
1049
 
1023
1050
  支持按日/周/月切换的日期范围选择筛选组件。
1024
1051
 
1025
- | 属性 | 类型 | 默认值 | 说明 |
1026
- |--------|----------|----------------|------|
1052
+ | 属性 | 类型 | 默认值 | 说明 |
1053
+ | ------ | -------- | -------------- | -------- |
1027
1054
  | name | `string` | - | 字段名称 |
1028
- | label | `string` | - | 标签 |
1055
+ | label | `string` | - | 标签 |
1029
1056
  | format | `string` | `'YYYY-MM-DD'` | 日期格式 |
1030
1057
 
1031
1058
  #### SuperSelectFilterItem 通用选择器筛选
1032
1059
 
1033
1060
  基于 `@kne/super-select` 的通用选择器筛选项，支持单选/多选、搜索、全选等功能。
1034
1061
 
1035
- | 属性 | 类型 | 默认值 | 说明 |
1036
- |------------------|-----------------------------|---------|----------|
1037
- | name | `string` | - | 字段名称 |
1038
- | label | `string` | - | 标签 |
1039
- | options | `Array<{ value, label }>` | - | 选项数据 |
1040
- | single | `boolean` | `false` | 是否单选 |
1041
- | allowSelectedAll | `boolean` | `false` | 是否支持全选 |
1042
- | maxLength | `number` | - | 最多可选数量 |
1062
+ | 属性 | 类型 | 默认值 | 说明 |
1063
+ | ---------------- | ------------------------- | ------- | ------------ |
1064
+ | name | `string` | - | 字段名称 |
1065
+ | label | `string` | - | 标签 |
1066
+ | options | `Array<{ value, label }>` | - | 选项数据 |
1067
+ | single | `boolean` | `false` | 是否单选 |
1068
+ | allowSelectedAll | `boolean` | `false` | 是否支持全选 |
1069
+ | maxLength | `number` | - | 最多可选数量 |
1043
1070
 
1044
1071
  **使用示例：**
1045
1072
 
@@ -1072,12 +1099,12 @@ import { SuperSelectFilterItem } from '@kne/react-filter';
1072
1099
 
1073
1100
  基于 `@kne/super-select-plus` 的职能选择器筛选项，支持多级职能数据选择、拼音搜索。
1074
1101
 
1075
- | 属性 | 类型 | 默认值 | 说明 |
1076
- |-----------|-----------|---------|----------|
1102
+ | 属性 | 类型 | 默认值 | 说明 |
1103
+ | --------- | --------- | ------- | ------------ |
1077
1104
  | name | `string` | - | 字段名称 |
1078
- | label | `string` | - | 标签 |
1105
+ | label | `string` | - | 标签 |
1079
1106
  | single | `boolean` | `false` | 是否单选 |
1080
- | maxLength | `number` | - | 最多可选数量 |
1107
+ | maxLength | `number` | - | 最多可选数量 |
1081
1108
 
1082
1109
  > 注意：需要安装 `@kne/super-select-plus` 依赖。
1083
1110
 
@@ -1085,12 +1112,12 @@ import { SuperSelectFilterItem } from '@kne/react-filter';
1085
1112
 
1086
1113
  基于 `@kne/super-select-plus` 的行业选择器筛选项，支持多级行业数据选择、拼音搜索。
1087
1114
 
1088
- | 属性 | 类型 | 默认值 | 说明 |
1089
- |-----------|-----------|---------|----------|
1115
+ | 属性 | 类型 | 默认值 | 说明 |
1116
+ | --------- | --------- | ------- | ------------ |
1090
1117
  | name | `string` | - | 字段名称 |
1091
- | label | `string` | - | 标签 |
1118
+ | label | `string` | - | 标签 |
1092
1119
  | single | `boolean` | `false` | 是否单选 |
1093
- | maxLength | `number` | - | 最多可选数量 |
1120
+ | maxLength | `number` | - | 最多可选数量 |
1094
1121
 
1095
1122
  > 注意：需要安装 `@kne/super-select-plus` 依赖。
1096
1123
 
@@ -1098,12 +1125,12 @@ import { SuperSelectFilterItem } from '@kne/react-filter';
1098
1125
 
1099
1126
  基于 `@kne/super-select-plus` 的城市选择器筛选项，支持国内外城市搜索选择。
1100
1127
 
1101
- | 属性 | 类型 | 默认值 | 说明 |
1102
- |-----------|-----------|---------|----------|
1128
+ | 属性 | 类型 | 默认值 | 说明 |
1129
+ | --------- | --------- | ------- | ------------ |
1103
1130
  | name | `string` | - | 字段名称 |
1104
- | label | `string` | - | 标签 |
1131
+ | label | `string` | - | 标签 |
1105
1132
  | single | `boolean` | `false` | 是否单选 |
1106
- | maxLength | `number` | - | 最多可选数量 |
1133
+ | maxLength | `number` | - | 最多可选数量 |
1107
1134
 
1108
1135
  > 注意：需要安装 `@kne/super-select-plus` 依赖。
1109
1136
 
@@ -1111,10 +1138,10 @@ import { SuperSelectFilterItem } from '@kne/react-filter';
1111
1138
 
1112
1139
  城市选择器的高级筛选版本，用于 `AdvancedFilter` 组件的 `list` 配置中。展示热门城市标签，支持搜索选择其他城市。
1113
1140
 
1114
- | 属性 | 类型 | 默认值 | 说明 |
1115
- |-----------|-----------|---------|------------|
1116
- | single | `boolean` | `false` | 是否单选 |
1117
- | maxLength | `number` | `5` | 最多可选数量 |
1141
+ | 属性 | 类型 | 默认值 | 说明 |
1142
+ | --------- | --------- | ------- | ------------ |
1143
+ | single | `boolean` | `false` | 是否单选 |
1144
+ | maxLength | `number` | `5` | 最多可选数量 |
1118
1145
 
1119
1146
  **在高级筛选中使用：**
1120
1147
 
@@ -1122,11 +1149,7 @@ import { SuperSelectFilterItem } from '@kne/react-filter';
1122
1149
  import { AdvancedFilter } from '@kne/react-filter';
1123
1150
  import { CityFilterItem } from './AdvancedFilter/fields';
1124
1151
 
1125
- <AdvancedFilter
1126
- list={[
1127
- [{ type: CityFilterItem, props: { label: '城市', single: true } }]
1128
- ]}
1129
- />
1152
+ <AdvancedFilter list={[[{ type: CityFilterItem, props: { label: '城市', single: true } }]]} />;
1130
1153
  ```
1131
1154
 
1132
1155
  ---
@@ -1135,20 +1158,20 @@ import { CityFilterItem } from './AdvancedFilter/fields';
1135
1158
 
1136
1159
  支持按日/周/月切换的日期范围选择器基础组件。
1137
1160
 
1138
- | 属性 | 类型 | 默认值 | 说明 |
1139
- |-----------------|------------------------------------------------------------|---------------------------------|----------|
1140
- | value | `{ type: string, value: [Date, Date] }` | - | 当前值 |
1141
- | defaultValue | `{ type: string, value: [Date, Date] }` | `{ type: 'date', value: null }` | 默认值 |
1142
- | onChange | `(value: object) => void` | - | 值变化回调 |
1161
+ | 属性 | 类型 | 默认值 | 说明 |
1162
+ | --------------- | ---------------------------------------------------------- | ------------------------------- | ---------------- |
1163
+ | value | `{ type: string, value: [Date, Date] }` | - | 当前值 |
1164
+ | defaultValue | `{ type: string, value: [Date, Date] }` | `{ type: 'date', value: null }` | 默认值 |
1165
+ | onChange | `(value: object) => void` | - | 值变化回调 |
1143
1166
  | shortcuts | `boolean` | `true` | 是否显示快捷选项 |
1144
- | shortcutOptions | `Array<{ label: string, getValue: () => [Dayjs, Dayjs] }>` | - | 自定义快捷选项 |
1167
+ | shortcutOptions | `Array<{ label: string, getValue: () => [Dayjs, Dayjs] }>` | - | 自定义快捷选项 |
1145
1168
 
1146
1169
  **value 结构：**
1147
1170
 
1148
1171
  ```typescript
1149
1172
  interface TypeDateRangeValue {
1150
- type: 'date' | 'week' | 'month'; // 日期类型
1151
- value: [Date, Date] | null; // 日期范围 [开始时间, 结束时间]
1173
+ type: 'date' | 'week' | 'month'; // 日期类型
1174
+ value: [Date, Date] | null; // 日期范围 [开始时间, 结束时间]
1152
1175
  }
1153
1176
  ```
1154
1177
 
@@ -1176,20 +1199,38 @@ import { TypeDateRangePickerField } from '@kne/react-filter';
1176
1199
  getValue: () => [dayjs().subtract(1, 'month').startOf('day'), dayjs().endOf('day')]
1177
1200
  }
1178
1201
  ]}
1179
- />
1202
+ />;
1180
1203
  ```
1181
1204
 
1182
1205
  ---
1183
1206
 
1184
1207
  ### SearchInput 搜索输入
1185
1208
 
1186
- 搜索输入组件。
1209
+ 搜索输入组件，适合放在列表顶部做关键词搜索。输入过程中维护本地输入值，停止输入 500ms 后自动提交筛选值；中文等输入法组合输入期间不会触发搜索，确认文本后才开始计时。按回车或点击搜索按钮会立即提交。清空后搜索会提交 `null`，用于移除该筛选条件。
1210
+
1211
+ | 属性 | 类型 | 默认值 | 说明 |
1212
+ | ----------- | ---------------------------------- | ------ | ------------------------------------ |
1213
+ | name | `string` | - | 字段名称，用于写入筛选值 |
1214
+ | label | `string` | - | 标签，用于展示已选筛选条件 |
1215
+ | value | `{ label: string, value: string }` | - | 当前搜索值 |
1216
+ | onChange | `(value: object \| null) => void` | - | 搜索提交回调，清空搜索时返回 `null` |
1217
+ | placeholder | `string` | - | 占位符 |
1218
+ | searchDelay | `number` | `500` | 自动提交搜索的防抖等待时间，单位毫秒 |
1187
1219
 
1188
- | 属性 | 类型 | 默认值 | 说明 |
1189
- |-------------|----------|-----|------|
1190
- | name | `string` | - | 字段名称 |
1191
- | label | `string` | - | 标签 |
1192
- | placeholder | `string` | - | 占位符 |
1220
+ #### 使用示例
1221
+
1222
+ ```javascript
1223
+ import { SearchInput, FilterProvider, getFilterValue } from '@kne/react-filter';
1224
+
1225
+ const [filterValue, setFilterValue] = useState([]);
1226
+
1227
+ <FilterProvider value={filterValue} onChange={setFilterValue}>
1228
+ <SearchInput name="keyword" label="关键词" placeholder="请输入关键词" searchDelay={500} allowClear />
1229
+ </FilterProvider>;
1230
+
1231
+ const params = getFilterValue(filterValue);
1232
+ // { keyword: 'React' }
1233
+ ```
1193
1234
 
1194
1235
  ---
1195
1236
 
@@ -1219,15 +1260,20 @@ const params = getFilterValue(filterValue);
1219
1260
 
1220
1261
  ```typescript
1221
1262
  interface FilterValueItem {
1222
- name: string; // 字段名称
1223
- label: string; // 字段标签（用于展示）
1224
- value: { // 单个值
1225
- label: string; // 显示文本
1226
- value: any; // 实际值
1227
- } | Array<{ // 或多个值
1228
- label: string;
1229
- value: any;
1230
- }> | null; // 或空值
1263
+ name: string; // 字段名称
1264
+ label: string; // 字段标签（用于展示）
1265
+ value:
1266
+ | {
1267
+ // 单个值
1268
+ label: string; // 显示文本
1269
+ value: any; // 实际值
1270
+ }
1271
+ | Array<{
1272
+ // 或多个值
1273
+ label: string;
1274
+ value: any;
1275
+ }>
1276
+ | null; // 或空值
1231
1277
  }
1232
1278
  ```
1233
1279
 
@@ -1239,12 +1285,13 @@ interface FilterValueItem {
1239
1285
 
1240
1286
  将筛选值数组序列化为 URLSearchParams，保留 label 信息以便反序列化还原完整筛选状态。
1241
1287
 
1242
- | 参数 | 类型 | 默认值 | 说明 |
1243
- |----------------|----------------|-----------------|--------------------------|
1244
- | filterValue | `Array` | - | 筛选值数组 |
1245
- | options.prefix | `string` | `'filterParams'` | URL 参数前缀，设为空字符串则不加前缀 |
1288
+ | 参数 | 类型 | 默认值 | 说明 |
1289
+ | -------------- | -------- | ---------------- | ------------------------------------ |
1290
+ | filterValue | `Array` | - | 筛选值数组 |
1291
+ | options.prefix | `string` | `'filterParams'` | URL 参数前缀，设为空字符串则不加前缀 |
1246
1292
 
1247
1293
  **序列化格式**：
1294
+
1248
1295
  - 单值且 `label === value`：`prefix[name]=value`（如输入框）
1249
1296
  - 单值且 `label !== value`：`prefix[name]=label:value`
1250
1297
  - 多值：`prefix[name]=label1:value1,label2:value2`
@@ -1256,7 +1303,14 @@ import { filterToUrlParams } from '@kne/react-filter';
1256
1303
 
1257
1304
  const params = filterToUrlParams([
1258
1305
  { name: 'keyword', label: '关键词', value: { label: '测试', value: '测试' } },
1259
- { name: 'city', label: '城市', value: [{ label: '上海', value: '010' }, { label: '北京', value: '020' }] },
1306
+ {
1307
+ name: 'city',
1308
+ label: '城市',
1309
+ value: [
1310
+ { label: '上海', value: '010' },
1311
+ { label: '北京', value: '020' }
1312
+ ]
1313
+ }
1260
1314
  ]);
1261
1315
  // params.toString() => 'filterParams[keyword]=测试&filterParams[city]=上海:010,北京:020'
1262
1316
 
@@ -1275,11 +1329,12 @@ filterToUrlParams(filterValue, { prefix: '' });
1275
1329
 
1276
1330
  解析 URL 参数中的单个筛选值项，反序列化为 `{ label, value }` 对象。
1277
1331
 
1278
- | 参数 | 类型 | 说明 |
1279
- |-----|----------|---------------|
1280
- | str | `string` | URL 参数中的原始字符串 |
1332
+ | 参数 | 类型 | 说明 |
1333
+ | ---- | -------- | ---------------------- |
1334
+ | str | `string` | URL 参数中的原始字符串 |
1281
1335
 
1282
1336
  **解析规则**：
1337
+
1283
1338
  - 无冒号：label 和 value 相同，如 `"测试"` → `{ label: '测试', value: '测试' }`
1284
1339
  - 有冒号：冒号前为 label，冒号后为 value，如 `"启用:active"` → `{ label: '启用', value: 'active' }`
1285
1340
 
@@ -1299,12 +1354,12 @@ parseFilterEntry('启用:active');
1299
1354
 
1300
1355
  从 URL 参数中读取筛选值项，返回单选 `{ label, value }` 或多选数组。
1301
1356
 
1302
- | 参数 | 类型 | 默认值 | 说明 |
1303
- |-----------------|-------------------|-----------------|------------------|
1304
- | searchParams | `URLSearchParams` | - | URL 参数对象 |
1305
- | key | `string` | - | 参数名（不含前缀） |
1306
- | options.multi | `boolean` | `false` | 是否多选 |
1307
- | options.prefix | `string` | `'filterParams'` | URL 参数前缀 |
1357
+ | 参数 | 类型 | 默认值 | 说明 |
1358
+ | -------------- | ----------------- | ---------------- | ------------------ |
1359
+ | searchParams | `URLSearchParams` | - | URL 参数对象 |
1360
+ | key | `string` | - | 参数名（不含前缀） |
1361
+ | options.multi | `boolean` | `false` | 是否多选 |
1362
+ | options.prefix | `string` | `'filterParams'` | URL 参数前缀 |
1308
1363
 
1309
1364
  ```javascript
1310
1365
  import { takeFilterEntry } from '@kne/react-filter';
@@ -1323,10 +1378,10 @@ takeFilterEntry(searchParams, 'keyword', { prefix: '' });
1323
1378
 
1324
1379
  创建 URL 筛选参数读取器，自动追踪已消费的参数 key。配合 `useUrlFilter` 使用，readUrlParams 返回的 consumedKeys 可被自动清除。
1325
1380
 
1326
- | 参数 | 类型 | 默认值 | 说明 |
1327
- |-----------------|-------------------|-----------------|----------|
1328
- | searchParams | `URLSearchParams` | - | URL 参数对象 |
1329
- | options.prefix | `string` | `'filterParams'` | URL 参数前缀 |
1381
+ | 参数 | 类型 | 默认值 | 说明 |
1382
+ | -------------- | ----------------- | ---------------- | ------------ |
1383
+ | searchParams | `URLSearchParams` | - | URL 参数对象 |
1384
+ | options.prefix | `string` | `'filterParams'` | URL 参数前缀 |
1330
1385
 
1331
1386
  **返回值**：`{ takeFilterEntry, getConsumedKeys }`
1332
1387
 
@@ -1347,10 +1402,10 @@ const city = takeFilterEntry('city', { multi: true });
1347
1402
 
1348
1403
  > 需要 React Router 环境支持 `useSearchParams`。
1349
1404
 
1350
- | 参数 | 类型 | 说明 |
1351
- |---------------------|------------|----------------------------------------------|
1405
+ | 参数 | 类型 | 说明 |
1406
+ | --------------------- | ---------- | --------------------------------------------------------- |
1352
1407
  | options.readUrlParams | `Function` | 读取 URL 参数并返回 `{ consumedKeys: string[], ...data }` |
1353
- | options.buildFilter | `Function` | 接收 readUrlParams 的返回值，构建初始 filter 数组 |
1408
+ | options.buildFilter | `Function` | 接收 readUrlParams 的返回值，构建初始 filter 数组 |
1354
1409
 
1355
1410
  **返回值**：`[filter, setFilter]`
1356
1411
 
@@ -1358,15 +1413,12 @@ const city = takeFilterEntry('city', { multi: true });
1358
1413
  import { useUrlFilter, createUrlParamsReader } from '@kne/react-filter';
1359
1414
 
1360
1415
  const [filter, setFilter] = useUrlFilter({
1361
- readUrlParams: (searchParams) => {
1416
+ readUrlParams: searchParams => {
1362
1417
  const { take, getConsumedKeys } = createUrlParamsReader(searchParams);
1363
1418
  const orgId = take('tenantOrgId');
1364
1419
  return { consumedKeys: getConsumedKeys(), orgId };
1365
1420
  },
1366
- buildFilter: ({ orgId }) => [
1367
- { name: 'status', value: { label: '开启', value: 'open' } },
1368
- ...(orgId ? [{ name: 'tenantOrgId', value: { label: orgId, value: orgId } }] : [])
1369
- ]
1421
+ buildFilter: ({ orgId }) => [{ name: 'status', value: { label: '开启', value: 'open' } }, ...(orgId ? [{ name: 'tenantOrgId', value: { label: orgId, value: orgId } }] : [])]
1370
1422
  });
1371
1423
  ```
1372
1424
 
@@ -1376,11 +1428,12 @@ const [filter, setFilter] = useUrlFilter({
1376
1428
 
1377
1429
  `useUrlFilter` 的简化版，基于 `filterParams[key]` 格式自动解析 URL 参数，支持单选和多选。
1378
1430
 
1379
- | 参数 | 类型 | 说明 |
1380
- |---------|------------------------|--------------------------------|
1381
- | mapping | `string[] \| Object` | URL 参数映射，支持数组、对象两种格式 |
1431
+ | 参数 | 类型 | 说明 |
1432
+ | ------- | -------------------- | ------------------------------------ |
1433
+ | mapping | `string[] \| Object` | URL 参数映射，支持数组、对象两种格式 |
1382
1434
 
1383
1435
  **数组形式（默认单选）：**
1436
+
1384
1437
  ```javascript
1385
1438
  import { useUrlFilterValue } from '@kne/react-filter';
1386
1439
 
@@ -1393,11 +1446,13 @@ const [filter, setFilter] = useUrlFilterValue(['keyword', 'status']);
1393
1446
  ```
1394
1447
 
1395
1448
  **对象形式（多选 + 自定义）：**
1449
+
1396
1450
  ```javascript
1397
1451
  const [filter, setFilter] = useUrlFilterValue({
1398
- keyword: true, // 单选
1399
- city: { multi: true }, // 多选
1400
- status: (parsed) => { // 自定义转换
1452
+ keyword: true, // 单选
1453
+ city: { multi: true }, // 多选
1454
+ status: parsed => {
1455
+ // 自定义转换
1401
1456
  return parsed ? { name: 'status', value: parsed } : null;
1402
1457
  }
1403
1458
  });
@@ -1410,11 +1465,12 @@ const [filter, setFilter] = useUrlFilterValue({
1410
1465
 
1411
1466
  创建通用 URL 参数读取器，自动追踪已消费的参数 key。
1412
1467
 
1413
- | 参数 | 类型 | 说明 |
1414
- |--------------|-------------------|----------|
1468
+ | 参数 | 类型 | 说明 |
1469
+ | ------------ | ----------------- | ------------ |
1415
1470
  | searchParams | `URLSearchParams` | URL 参数对象 |
1416
1471
 
1417
1472
  **返回值**：`{ take, getConsumedKeys }`
1473
+
1418
1474
  - `take(key)` - 读取参数值，记录已消费
1419
1475
  - `getConsumedKeys()` - 返回已消费的 key 列表
1420
1476
 
@@ -1433,10 +1489,10 @@ const orgName = take('orgName');
1433
1489
 
1434
1490
  从 URL 参数中移除已消费的 key，返回新的 URLSearchParams 或 null（无变化时）。
1435
1491
 
1436
- | 参数 | 类型 | 说明 |
1437
- |--------------|-------------------|-------------------|
1438
- | searchParams | `URLSearchParams` | 当前 URL 参数 |
1439
- | consumedKeys | `string[]` | 需要移除的 key 列表 |
1492
+ | 参数 | 类型 | 说明 |
1493
+ | ------------ | ----------------- | ------------------- |
1494
+ | searchParams | `URLSearchParams` | 当前 URL 参数 |
1495
+ | consumedKeys | `string[]` | 需要移除的 key 列表 |
1440
1496
 
1441
1497
  **返回值**：`URLSearchParams | null`
1442
1498
 
@@ -1459,19 +1515,19 @@ if (nextParams) {
1459
1515
 
1460
1516
  单选拦截器：`{id, name}` ↔ `{label, value}`。
1461
1517
 
1462
- | 属性 | 类型 | 说明 |
1463
- |---------|------------|---------------------------------------|
1464
- | input | `Function` | `{id, name}` → `{label, value}` 的转换 |
1465
- | output | `Function` | `{label, value}` → `{id, name}` 的转换 |
1518
+ | 属性 | 类型 | 说明 |
1519
+ | ------ | ---------- | -------------------------------------- |
1520
+ | input | `Function` | `{id, name}` → `{label, value}` 的转换 |
1521
+ | output | `Function` | `{label, value}` → `{id, name}` 的转换 |
1466
1522
 
1467
1523
  #### multiSelectInterceptor
1468
1524
 
1469
1525
  多选拦截器：`[{id, name}]` ↔ `[{label, value}]`。
1470
1526
 
1471
- | 属性 | 类型 | 说明 |
1472
- |---------|------------|-------------------------------------------|
1473
- | input | `Function` | `[{id, name}]` → `[{label, value}]` 的转换 |
1474
- | output | `Function` | `[{label, value}]` → `[{id, name}]` 的转换 |
1527
+ | 属性 | 类型 | 说明 |
1528
+ | ------ | ---------- | ------------------------------------------ |
1529
+ | input | `Function` | `[{id, name}]` → `[{label, value}]` 的转换 |
1530
+ | output | `Function` | `[{label, value}]` → `[{id, name}]` 的转换 |
1475
1531
 
1476
1532
  #### filterInterceptors
1477
1533
 
@@ -1482,7 +1538,7 @@ import { filterInterceptors, singleSelectInterceptor, multiSelectInterceptor } f
1482
1538
 
1483
1539
  // 两种引用方式等价
1484
1540
  filterInterceptors.single === singleSelectInterceptor; // true
1485
- filterInterceptors.multi === multiSelectInterceptor; // true
1541
+ filterInterceptors.multi === multiSelectInterceptor; // true
1486
1542
  ```
1487
1543
 
1488
1544
  **使用示例：**
@@ -1515,8 +1571,8 @@ import { filterInterceptors } from '@kne/react-filter';
1515
1571
 
1516
1572
  从筛选值中提取原始值数组。支持原始值、`{ value }` 对象、`{ id }` 对象以及它们的数组。
1517
1573
 
1518
- | 参数 | 类型 | 说明 |
1519
- |-------|-------|-------------|
1574
+ | 参数 | 类型 | 说明 |
1575
+ | ----- | ----- | -------------------- |
1520
1576
  | value | `any` | 筛选值，支持多种格式 |
1521
1577
 
1522
1578
  ```javascript
@@ -1536,17 +1592,17 @@ pickSelectValues(null);
1536
1592
 
1537
1593
  声明式创建 mapFilterValue 函数。`Filter.getFilterValue` 默认只读取 `{ value }`，而 SuperSelectFilterItem 等组件使用 `{ id, name }` 格式，需要额外处理。此工具通过声明字段映射规则，自动生成转换函数。
1538
1594
 
1539
- | 参数 | 类型 | 说明 |
1540
- |--------------|----------|-------------------|
1541
- | fieldMappers | `Object` | 字段名到映射规则的映射 |
1595
+ | 参数 | 类型 | 说明 |
1596
+ | ------------ | -------- | ---------------------- |
1597
+ | fieldMappers | `Object` | 字段名到映射规则的映射 |
1542
1598
 
1543
1599
  **映射规则类型：**
1544
1600
 
1545
- | 规则 | 说明 |
1546
- |-----------|----------------------------------------|
1547
- | `'string'` | 确保值为字符串类型 |
1548
- | `'multi'` | 多选，从 filter entry 提取值数组 |
1549
- | `'single'` | 单选，从 filter entry 提取第一个值 |
1601
+ | 规则 | 说明 |
1602
+ | ---------- | ------------------------------------------------------- |
1603
+ | `'string'` | 确保值为字符串类型 |
1604
+ | `'multi'` | 多选，从 filter entry 提取值数组 |
1605
+ | `'single'` | 单选，从 filter entry 提取第一个值 |
1550
1606
  | `Function` | 自定义转换，接收 `(rawValue, { entry, filter, value })` |
1551
1607
 
1552
1608
  ```javascript
@@ -1556,7 +1612,7 @@ const mapFilterValue = createFilterValueMapper({
1556
1612
  id: 'string',
1557
1613
  roles: 'multi',
1558
1614
  tenantOrgId: 'single',
1559
- status: (rawValue) => normalizeStatus(rawValue)
1615
+ status: rawValue => normalizeStatus(rawValue)
1560
1616
  });
1561
1617
 
1562
1618
  const filterValue = mapFilterValue(filter, Filter.getFilterValue);