@kne/react-filter 0.1.28 → 1.0.0

package/README.md

@@ -1,11 +1,8 @@
-
 # react-filter
 
-
 ### 描述
 
-筛选器
-
+A React filter component library
 
 ### 安装
 
@@ -13,375 +10,1554 @@
 npm i --save @kne/react-filter
 ```
 
-
 ### 概述
 
-用户列表数据的筛选
+### React Filter
+
+一个功能强大的 React 筛选组件库，支持多种筛选字段类型、灵活的布局方式，以及完善的 URL 参数双向同步能力。
+
+### 主要特性
+
+- **多种筛选字段类型**：支持输入框、数字区间、日期选择、日期范围、下拉选择等常用筛选类型，以及职能、行业、城市等业务选择器
+- **灵活布局**：支持普通筛选（横向布局）和高级筛选（垂直布局）两种模式
+- **展开收起**：筛选行支持展开收起功能，优化页面空间利用
+- **已选值展示**：自动展示已选筛选条件，支持单独删除和清空全部
+- **弹出层交互**：支持弹出层形式的筛选交互，确认后才生效
+- **URL 参数同步**：支持筛选值与 URL 参数的双向序列化/反序列化，自动清除已消费参数
+- **数据格式拦截器**：内置 `{id, name}` ↔ `{label, value}` 格式转换拦截器，适配 SuperSelect 场景
+- **声明式值映射**：提供 `createFilterValueMapper` 按字段声明转换规则，简化 `getFilterValue` 结果处理
+- **国际化支持**：内置中英文语言包，支持多语言切换
+- **高阶组件**：提供 `withFilterValue` 和 `withFieldItem` 高阶组件，便于扩展自定义字段
+
+### 适用场景
+
+- 数据列表页面的筛选功能
+- 复杂表单的筛选条件配置
+- 多条件组合查询场景
+- 需要展示已选筛选条件的场景
+- 需要筛选状态与 URL 参数同步保持的页面
+
+### 快速开始
+
+```javascript
+import Filter, { fields } from '@kne/react-filter';
+import '@kne/react-filter/dist/index.css';
+
+const { InputFilterItem, NumberRangeFilterItem, DatePickerFilterItem } = fields;
+
+function MyComponent() {
+  const [filterValue, setFilterValue] = useState([]);
+
+  const handleSearch = () => {
+    const params = Filter.getFilterValue(filterValue);
+    console.log('筛选参数:', params);
+  };
+
+  return (
+    <Filter
+      value={filterValue}
+      onChange={setFilterValue}
+      list={[
+        [
+          { type: InputFilterItem, props: { name: 'keyword', label: '关键词' } },
+          { type: NumberRangeFilterItem, props: { name: 'amount', label: '金额' } }
+        ],
+        [
+          { type: DatePickerFilterItem, props: { name: 'date', label: '日期' } }
+        ]
+      ]}
+      displayLine={1}
+      extra={<Button type="primary" onClick={handleSearch}>搜索</Button>}
+    />
+  );
+}
+```
+
+### 核心组件
+
+| 组件 | 说明 |
+|------|------|
+| `Filter` | 主筛选组件，横向布局，支持展开收起 |
+| `AdvancedFilter` | 高级筛选组件，垂直布局 |
+| `FilterValueDisplay` | 已选值展示组件 |
+| `PopoverItem` | 弹出层筛选项组件 |
+| `FilterItem` | 筛选项容器组件 |
+| `FilterLines` | 筛选行组件 |
+| `FilterProvider` | 状态管理组件 |
+
+### 筛选字段
 
-* 默认提供了常见的几种筛选项
+| 字段组件 | 说明 |
+|----------|------|
+| `InputFilterItem` | 输入框筛选 |
+| `NumberRangeFilterItem` | 数字区间筛选 |
+| `DatePickerFilterItem` | 日期选择筛选 |
+| `DateRangePickerFilterItem` | 日期范围筛选 |
+| `TypeDateRangePickerFilterItem` | 类型日期范围筛选（日/周/月切换） |
+| `SuperSelectFilterItem` | 通用选择器筛选（单选/多选/搜索/全选） |
+| `SelectFunctionFilterItem` | 职能筛选（多级数据、拼音搜索） |
+| `SelectIndustryFilterItem` | 行业筛选（多级数据、拼音搜索） |
+| `SelectAddressFilterItem` | 城市筛选（国内外城市搜索） |
 
-* 支持自定义筛选项类型扩展
+### URL 参数工具
 
+| 工具 | 说明 |
+|------|------|
+| `useUrlFilter` | 从 URL 参数初始化筛选状态的 hook |
+| `useUrlFilterValue` | 简化版 URL 筛选 hook，自动解析 filterParams[key] 格式 |
+| `filterToUrlParams` | 将筛选值序列化为 URL 参数 |
+| `parseFilterEntry` | 解析 URL 参数中的单个筛选值项 |
+| `takeFilterEntry` | 从 URL 参数中读取筛选值项 |
+| `createUrlFilterReader` | 创建 URL 筛选参数读取器 |
+| `createUrlParamsReader` | 创建通用 URL 参数读取器 |
+| `stripConsumedUrlParams` | 移除已消费的 URL 参数 |
 
-### 示例(全屏)
+### 其他工具
+
+| 工具 | 说明 |
+|------|------|
+| `pickSelectValues` | 从筛选值中提取原始值数组 |
+| `createFilterValueMapper` | 声明式创建 mapFilterValue 函数 |
+| `filterInterceptors` | `{single, multi}` 拦截器集合 |
+| `singleSelectInterceptor` | 单选格式转换拦截器 |
+| `multiSelectInterceptor` | 多选格式转换拦截器 |
+
+
+### 示例
 
 #### 示例代码
 
-- 基础示例
-- 展示一个筛选器的普通模式
-- reactFilter(@kne/react-filter),(@kne/react-filter/dist/index.css),message(antd/lib/message),_(lodash)
+- 基础筛选
+- 使用 Filter 主组件，展示关键词、金额、日期、部门等多种筛选字段的组合使用
+- _ReactFilter(@kne/current-lib_react-filter)[import * as _ReactFilter from "@kne/react-filter"],(@kne/current-lib_react-filter/dist/index.css),antd(antd)
 
 ```jsx
-const {useState} = React;
-const {default: Filter, createExtraButton} = reactFilter;
-const {default: antdMessage} = message;
+const { default: Filter, fields } = _ReactFilter;
+const {
+  InputFilterItem, NumberRangeFilterItem, DatePickerFilterItem,
+  DateRangePickerFilterItem, TypeDateRangePickerFilterItem,
+  SuperSelectFilterItem, SelectFunctionFilterItem,
+  SelectIndustryFilterItem, SelectAddressFilterItem
+} = fields;
+const { Flex, Button, message } = antd;
+const { useState } = React;
 
-const {City, List, Range, Text, Selector, Check, DateTime} = Filter.type;
-
-const {isNumber} = _;
+const departmentOptions = [
+  { value: 'tech', label: '技术研发部' },
+  { value: 'product', label: '产品设计部' },
+  { value: 'operation', label: '运营管理部' },
+  { value: 'hr', label: '人力资源部' },
+  { value: 'finance', label: '财务部' },
+  { value: 'marketing', label: '市场营销部' }
+];
 
 const BaseExample = () => {
-    const [value, setValue] = useState({});
-    console.log(value);
-    return <Filter value={value} onChange={(value) => {
-        setValue(value);
-    }} more={[
-        <Text label="测试字段" name="test1"/>,
-        <Text label="测试字段2" name="test2" onBeforeSearch={(value) => {
-            antdMessage.error(`提交被拦截，输入值${value}`);
-            return false;
-        }}/>,
-        <Text.Number label="测试字段7" name="test7"/>,
-        <Range label="测试字段3" name="test3"/>,
-        <Selector label="测试字段4" name="test4"
-                  options={[{
-                      label: "英语", value: "en"
-                  }, {
-                      label: "日语", value: "jap"
-                  }, {
-                      label: "法语", value: "fac"
-                  }]}/>,
-        <DateTime label="测试字段5" name="test5" showTime/>,
-        <DateTime.Range label="测试字段6" name="test6"/>
-    ]} list={[[<City label="目前城市" name="currentCity" size={5}/>], [<List label="学历" name="degree" size={2}>
-        <List.Item value="0" label="初中"/>
-        <List.Item value="1" label="高中"/>
-        <List.Item value="2" label="大学专科"/>
-        <List.Item value="3" label="大学本科"/>
-    </List>], [<List label="求职意向" name="yixiang" size={1}
-                     options={[{label: "暂时不找工作", value: 0}, {label: "在职看机会", value: 1}, {
-                         label: "离职正在找工作", value: 2
-                     }]}/>], [<Range label="年龄" name="age" template={(value) => {
-        if (!value || value.length === 0) {
-            return "";
-        }
-        if (!isNumber(value[0]) && isNumber(value[1])) {
-            return `${value[1]}岁以下`;
-        }
-        if (!isNumber(value[1]) && isNumber(value[0])) {
-            return `${value[0]}岁以上`;
-        }
-        return `${value[0]}-${value[1]}岁`;
-    }}/>, <Text label="行业" name="inter"/>, <Selector label="语言" name="lang"
-                                                     options={[{
-                                                         label: "英语", value: "en"
-                                                     }, {
-                                                         label: "日语", value: "jap"
-                                                     }, {
-                                                         label: "法语", value: "fac"
-                                                     }]}/>], [<List size={1}
-                                                                    label="薪资范围"
-                                                                    name="sarl"
-                                                                    options={[{
-                                                                        label: "10k以下", value: [null, 10]
-                                                                    }, {
-                                                                        label: "10k-20k", value: [10, 20]
-                                                                    }, {
-                                                                        label: "20k以上", value: [20, null]
-                                                                    }]}
-                                                                    more={createExtraButton({
-                                                                        type: "range", template: (value) => {
-                                                                            if (!value || value.length === 0) {
-                                                                                return "";
-                                                                            }
-                                                                            if (!isNumber(value[0]) && isNumber(value[1])) {
-                                                                                return `${value[1]}k以下`;
-                                                                            }
-                                                                            if (!isNumber(value[1]) && isNumber(value[0])) {
-                                                                                return `${value[0]}k以上`;
-                                                                            }
-                                                                            return `${value[0]}k-${value[1]}k`;
-                                                                        }
-                                                                    })}/>, <Check label="海外经历" name="out"/>]]}/>;
+  const [filterValue, setFilterValue] = useState([]);
+
+  const handleSearch = () => {
+    const params = Filter.getFilterValue(filterValue);
+    message.info(&#96;搜索参数: ${JSON.stringify(params, null, 2)}&#96;);
+    console.log('筛选参数:', params);
+  };
+
+  return (
+    <Flex vertical gap={16}>
+      <Filter
+        value={filterValue}
+        onChange={setFilterValue}
+        list={[
+          [
+            {
+              type: InputFilterItem,
+              props: { name: 'keyword', label: '关键词', placeholder: '请输入关键词搜索' }
+            },
+            {
+              type: NumberRangeFilterItem,
+              props: { name: 'amount', label: '金额', unit: '元', min: 0, max: 999999 }
+            },
+            {
+              type: DatePickerFilterItem,
+              props: { name: 'createTime', label: '创建时间', format: 'YYYY-MM-DD' }
+            },
+            {
+              type: DateRangePickerFilterItem,
+              props: { name: 'dateRange', label: '日期范围', format: 'YYYY-MM-DD' }
+            },
+            {
+              type: TypeDateRangePickerFilterItem,
+              props: { name: 'typeDateRange', label: '快捷日期' }
+            }
+          ],
+          [
+            {
+              type: SuperSelectFilterItem,
+              props: { name: 'department', label: '部门', options: departmentOptions }
+            },
+            {
+              type: SelectFunctionFilterItem,
+              props: { name: 'function', label: '职能' }
+            },
+            {
+              type: SelectIndustryFilterItem,
+              props: { name: 'industry', label: '行业' }
+            },
+            {
+              type: SelectAddressFilterItem,
+              props: { name: 'city', label: '城市' }
+            }
+          ]
+        ]}
+        displayLine={1}
+      />
+      <Flex gap={8}>
+        <span>当前筛选值:</span>
+        <pre style={{ margin: 0, background: '#f5f5f5', padding: 8, borderRadius: 4, flex: 1 }}>{JSON.stringify(filterValue, null, 2)}</pre>
+      </Flex>
+    </Flex>
+  );
 };
 
-render(<BaseExample/>);
+render(<BaseExample />);
 
 ```
 
-- 简单示例
-- 展示一个简单的筛选项，一般放在列表页title extra位置
-- reactFilter(@kne/react-filter),(@kne/react-filter/dist/index.css),space(antd/lib/space)
+- 高级筛选
+- 使用 AdvancedFilter 组件实现更复杂的筛选布局
+- _ReactFilter(@kne/current-lib_react-filter)[import * as _ReactFilter from "@kne/react-filter"],(@kne/current-lib_react-filter/dist/index.css),antd(antd)
 
 ```jsx
-const {useState} = React;
-const {default: Filter} = reactFilter;
-const {default: Space} = space;
-
-const {RadioList, Selector, Text, CheckboxList} = Filter.type;
-
-const Example = () => {
-    const [value, setValue] = useState([]);
-    const [radioValue, setRadioValue] = useState({});
-    const [checkboxValue, setCheckboxValue] = useState({});
-    console.log(value, radioValue, checkboxValue);
-    return <Space direction="vertical">
-        <Filter value={value} onChange={setValue} labelHidden itemLabelHidden list={[[
-            <Text name="positionName" label="职位名称"/>,
-            <Selector name="type" options={[
-                {
-                    label: '全职',
-                    value: 1
-                }, {
-                    label: '兼职',
-                    value: 2
-                }
-            ]} label="职位类型"/>
-        ]]}/>
-        <Filter value={radioValue} onChange={setRadioValue} labelHidden list={[[
-            <RadioList name="state" label="客户状态" options={[
-                {
-                    label: "全部状态",
-                    value: 0
-                }, {
-                    label: "待开发",
-                    value: 1
-                }, {
-                    label: "开发中",
-                    value: 2
-                }, {
-                    label: "已签约",
-                    value: 3
-                }, {
-                    label: "已终止",
-                    value: 4
-                }
-            ]}/>
-        ]]}/>
-        <Filter value={checkboxValue} onChange={setCheckboxValue} labelHidden list={[[
-            <CheckboxList name="state" label="客户状态" options={[
-                {
-                    label: "全部状态",
-                    value: 0
-                }, {
-                    label: "待开发",
-                    value: 1
-                }, {
-                    label: "开发中",
-                    value: 2
-                }, {
-                    label: "已签约",
-                    value: 3
-                }, {
-                    label: "已终止",
-                    value: 4
-                }
-            ]}/>
-        ]]}/>
-    </Space>
+const { AdvancedFilter } = _ReactFilter;
+const { InputFilterItem, ListFilterItem, CityFilterItem } = AdvancedFilter.fields;
+const { Flex, Button, message } = antd;
+const { useState } = React;
+
+const AdvancedFilterExample = () => {
+  const [filterValue, setFilterValue] = useState([]);
+
+  const handleSearch = () => {
+    const params = {};
+    filterValue.forEach(item => {
+      params[item.name] = Array.isArray(item.value)
+        ? item.value.map(v => v.value)
+        : item.value?.value;
+    });
+    message.info(&#96;搜索参数: ${JSON.stringify(params, null, 2)}&#96;);
+    console.log('筛选参数:', params);
+  };
+
+  return (
+    <Flex vertical gap={16}>
+      <AdvancedFilter
+        value={filterValue}
+        onChange={setFilterValue}
+        list={[
+          [
+            {
+              type: InputFilterItem,
+              props: {
+                name: 'name',
+                label: '姓名'
+              }
+            },
+            {
+              type: InputFilterItem,
+              props: {
+                name: 'phone',
+                label: '手机号'
+              }
+            }
+          ],
+          [
+            {
+              type: ListFilterItem,
+              props: {
+                name: 'status',
+                label: '状态',
+                single: true,
+                items: [
+                  { label: '待处理', value: 'pending' },
+                  { label: '处理中', value: 'processing' },
+                  { label: '已完成', value: 'completed' },
+                  { label: '已取消', value: 'cancelled' }
+                ]
+              }
+            }
+          ],
+          [
+            {
+              type: ListFilterItem,
+              props: {
+                name: 'tags',
+                label: '标签',
+                single: false,
+                maxLength: 3,
+                items: [
+                  { label: '前端', value: 'frontend' },
+                  { label: '后端', value: 'backend' },
+                  { label: '全栈', value: 'fullstack' },
+                  { label: 'UI设计', value: 'ui' },
+                  { label: '产品', value: 'product' }
+                ]
+              }
+            }
+          ],
+          [
+            {
+              type: CityFilterItem,
+              props: {
+                name: 'city',
+                label: '城市',
+                maxLength: 3
+              }
+            }
+          ]
+        ]}
+      />
+      <Flex justify="end">
+        <Button type="primary" onClick={handleSearch}>
+          查询
+        </Button>
+      </Flex>
+      <Flex gap={8}>
+        <span>当前筛选值:</span>
+        <pre style={{ margin: 0, background: '#f5f5f5', padding: 8, borderRadius: 4, flex: 1 }}>
+          {JSON.stringify(filterValue, null, 2)}
+        </pre>
+      </Flex>
+    </Flex>
+  );
 };
 
-render(<Example/>);
+render(<AdvancedFilterExample />);
 
 ```
 
-- 扩展示例
-- 展示扩展筛选项，自定义筛选项
-- reactFilter(@kne/react-filter),modal(antd/lib/modal),input(antd/lib/input),space(antd/lib/space),datePicker(antd/lib/date-picker),monment(moment),_(lodash),(@kne/react-filter/dist/index.css)
+- 筛选字段组件
+- 展示所有筛选字段组件类型，包括输入筛选、数字区间、日期选择、下拉选择以及 SuperSelect 业务选择器（职能/行业/城市）
+- _ReactFilter(@kne/current-lib_react-filter)[import * as _ReactFilter from "@kne/react-filter"],(@kne/current-lib_react-filter/dist/index.css),antd(antd)
 
 ```jsx
-const {default: ReactFilter, useFilterContext, FilterItem, withFilterItem, SearchButton} = reactFilter;
-const {default: Modal} = modal;
-const {default: Input} = input;
-const {default: Space} = space;
-const {default: DatePicker} = datePicker;
-const {useRef, useState} = React;
-const {get} = _;
-
-const MyFilter = (props) => {
-    const ref = useRef();
-    const {value, onChange} = useFilterContext();
-    return <FilterItem {...props} onClick={() => {
-        Modal.confirm({
-            icon: null,
-            content: <Input ref={ref} defaultValue={get(value[props.name], 'value')}/>,
-            onOk: () => {
-                const value = ref.current.input.value;
-                onChange(props.name, {
-                    label: value,
-                    value
-                });
-            }
-        });
-        console.log(value);
-    }}/>;
+const { fields, PopoverItem } = _ReactFilter;
+const {
+  InputFilterItem, NumberRangeFilterItem, DatePickerFilterItem,
+  DateRangePickerFilterItem, TypeDateRangePickerFilterItem,
+  SuperSelectFilterItem, SelectFunctionFilterItem,
+  SelectIndustryFilterItem, SelectAddressFilterItem
+} = fields;
+const { Input, InputNumber, Space, Flex, Select, Divider, Tag } = antd;
+const { useState } = React;
+
+// 自定义下拉选择筛选项
+const SelectFilterItem = ({ label, value, onChange, options = [] }) => {
+  return (
+    <PopoverItem
+      label={label}
+      value={value}
+      onChange={onChange}
+    >
+      {({ value, onChange }) => (
+        <Select
+          style={{ width: 200 }}
+          placeholder={&#96;请选择${label}&#96;}
+          value={value?.value}
+          onChange={(val, option) => {
+            onChange({
+              value: val,
+              label: option?.label || val
+            });
+          }}
+          options={options}
+        />
+      )}
+    </PopoverItem>
+  );
 };
 
-const DateRange = withFilterItem(({
-                                      name,
-                                      size,
-                                      isMore,
-                                      defaultActive,
-                                      onBlur,
-                                      onSearch,
-                                      onBeforeSearch,
-                                      startProps,
-                                      endProps,
-                                      placeholder
-                                  }) => {
-    const ref = useRef();
-
-    const sort = (a, b) => {
-        if (a && b) {
-            return new Date(a) - new Date(b);
-        }
-        return 0;
-    };
+const FilterFieldsExample = () => {
+  const [values, setValues] = useState({});
 
-    return <SearchButton size={size} template={(value) => {
-        if (!value[0] && value[1]) {
-            return `${value[1]}之前`;
-        }
-        if (!value[1] && value[0]) {
-            return `${value[0]}之后`;
-        }
-        return value.join('~');
-    }} isMore={isMore} onBlur={onBlur} defaultActive={defaultActive}
-                         name={name}
-                         onSearch={onSearch}
-                         onBeforeSearch={onBeforeSearch}>
-        {({value, setValue, setActive}) => {
-            return <div ref={ref}>
-                <Space>
-                    <DatePicker size="small" {...startProps} getPopupContainer={() => ref.current}
-                                value={get(value, 0) && monment(get(value, 0))}
-                                onChange={(inputValue) => {
-                                    const target = [inputValue && inputValue.format('YYYY-MM-DD HH:mm:ss'), get(value, 1)];
-                                    setValue(target.sort(sort));
-                                }} onFocus={() => {
-                        setActive(true);
-                    }} placeholder={Array.isArray(placeholder) ? placeholder[0] : (placeholder || "请输入")}/>
-                    ~
-                    <DatePicker size="small" {...endProps} getPopupContainer={() => ref.current}
-                                value={get(value, 1) && monment(get(value, 1))}
-                                onChange={(inputValue) => {
-                                    const target = [get(value, 0), inputValue && inputValue.format('YYYY-MM-DD HH:mm:ss')];
-                                    setValue(target.sort(sort));
-                                }} onFocus={() => {
-                        setActive(true);
-                    }} placeholder={Array.isArray(placeholder) ? placeholder[0] : (placeholder || "请输入")}/>
-                </Space>
-            </div>
-        }}
-    </SearchButton>
-});
+  const fieldConfigs = [
+    {
+      name: 'input',
+      label: '输入筛选',
+      component: InputFilterItem,
+      props: {}
+    },
+    {
+      name: 'numberRange',
+      label: '数字区间',
+      component: NumberRangeFilterItem,
+      props: { unit: '万', min: 0 }
+    },
+    {
+      name: 'date',
+      label: '日期选择',
+      component: DatePickerFilterItem,
+      props: { picker: 'date' }
+    },
+    {
+      name: 'month',
+      label: '月份选择',
+      component: DatePickerFilterItem,
+      props: { picker: 'month' }
+    },
+    {
+      name: 'dateRange',
+      label: '日期范围',
+      component: DateRangePickerFilterItem,
+      props: {}
+    },
+    {
+      name: 'typeDateRange',
+      label: '类型日期范围',
+      component: TypeDateRangePickerFilterItem,
+      props: {}
+    },
+    {
+      name: 'select',
+      label: '下拉选择',
+      component: SelectFilterItem,
+      props: {
+        options: [
+          { value: 'pending', label: '待处理' },
+          { value: 'processing', label: '处理中' },
+          { value: 'completed', label: '已完成' },
+          { value: 'cancelled', label: '已取消' }
+        ]
+      }
+    }
+  ];
 
-const Example = () => {
-    const [value, setValue] = useState({});
-    return <ReactFilter value={value} onChange={setValue} moreTrigger="click"
-                        more={[<MyFilter name="test1" label="测试"/>, <DateRange name="test2" label="测试2"/>]}/>
+  return (
+    <Flex vertical gap={24}>
+      <h4>筛选字段组件展示</h4>
+      <Flex wrap gap={16}>
+        {fieldConfigs.map(({ name, label, component: Component, props }) => (
+          <Component
+            key={name}
+            label={label}
+            value={values[name]}
+            onChange={(val) => setValues(prev => ({ ...prev, [name]: val }))}
+            {...props}
+          />
+        ))}
+      </Flex>
+      <Flex gap={8}>
+        <span>当前值:</span>
+        <pre style={{ margin: 0, background: '#f5f5f5', padding: 8, borderRadius: 4, flex: 1 }}>
+          {JSON.stringify(values, null, 2)}
+        </pre>
+      </Flex>
+    </Flex>
+  );
 };
 
-render(<Example/>);
+// SuperSelect 业务选择器示例
+const departmentOptions = [
+  { value: 'tech', label: '技术研发部' },
+  { value: 'product', label: '产品设计部' },
+  { value: 'operation', label: '运营管理部' },
+  { value: 'hr', label: '人力资源部' },
+  { value: 'finance', label: '财务部' },
+  { value: 'marketing', label: '市场营销部' }
+];
+
+const SuperSelectExample = () => {
+  const [values, setValues] = useState({});
+
+  return (
+    <Flex vertical gap={24}>
+      <Flex align="center" gap={8}>
+        <h4 style={{ margin: 0 }}>SuperSelect 业务选择器</h4>
+        <Tag color="blue">单选/多选</Tag>
+        <Tag color="blue">搜索</Tag>
+        <Tag color="blue">全选</Tag>
+      </Flex>
+      <p style={{ margin: 0, color: '#666', fontSize: 12 }}>
+        基于 @kne/super-select 的通用选择器筛选项，支持单选/多选、搜索、全选等功能
+      </p>
+      <Flex wrap gap={16}>
+        <SuperSelectFilterItem
+          label="部门（多选）"
+          value={values.dept}
+          onChange={(val) => setValues(prev => ({ ...prev, dept: val }))}
+          options={departmentOptions}
+        />
+        <SuperSelectFilterItem
+          label="状态（单选）"
+          single
+          value={values.status}
+          onChange={(val) => setValues(prev => ({ ...prev, status: val }))}
+          options={[
+            { value: 'active', label: '启用' },
+            { value: 'inactive', label: '停用' }
+          ]}
+        />
+        <SuperSelectFilterItem
+          label="角色（全选）"
+          value={values.role}
+          onChange={(val) => setValues(prev => ({ ...prev, role: val }))}
+          options={[
+            { value: 'admin', label: '管理员' },
+            { value: 'editor', label: '编辑者' },
+            { value: 'viewer', label: '查看者' }
+          ]}
+          allowSelectedAll
+        />
+      </Flex>
+      <pre style={{ margin: 0, background: '#f5f5f5', padding: 8, borderRadius: 4 }}>
+        {JSON.stringify(values, null, 2)}
+      </pre>
+    </Flex>
+  );
+};
+
+// 业务选择器示例（职能/行业/城市）
+const BusinessSelectExample = () => {
+  const [values, setValues] = useState({});
+
+  return (
+    <Flex vertical gap={24}>
+      <Flex align="center" gap={8}>
+        <h4 style={{ margin: 0 }}>业务选择器筛选项</h4>
+        <Tag color="blue">多级数据</Tag>
+        <Tag color="blue">拼音搜索</Tag>
+        <Tag color="blue">国际化</Tag>
+      </Flex>
+      <p style={{ margin: 0, color: '#666', fontSize: 12 }}>
+        基于 @kne/super-select-plus 的职能、行业、城市选择器，支持多级数据、拼音搜索、国际化
+      </p>
+      <Flex wrap gap={16}>
+        <SelectFunctionFilterItem
+          label="职能"
+          value={values.function}
+          onChange={(val) => setValues(prev => ({ ...prev, function: val }))}
+        />
+        <SelectIndustryFilterItem
+          label="行业"
+          value={values.industry}
+          onChange={(val) => setValues(prev => ({ ...prev, industry: val }))}
+        />
+        <SelectAddressFilterItem
+          label="城市（多选）"
+          value={values.city}
+          onChange={(val) => setValues(prev => ({ ...prev, city: val }))}
+        />
+        <SelectAddressFilterItem
+          label="城市（单选）"
+          single
+          value={values.singleCity}
+          onChange={(val) => setValues(prev => ({ ...prev, singleCity: val }))}
+        />
+      </Flex>
+    </Flex>
+  );
+};
+
+render(<FilterFieldsExample />);
+render(<Divider />);
+render(<SuperSelectExample />);
+render(<Divider />);
+render(<BusinessSelectExample />);
 
 ```
 
+- 已选值展示
+- 使用 FilterValueDisplay 组件展示已选择的筛选条件，支持单独删除和清空全部
+- _ReactFilter(@kne/current-lib_react-filter)[import * as _ReactFilter from "@kne/react-filter"],(@kne/current-lib_react-filter/dist/index.css),antd(antd)
+
+```jsx
+const { FilterValueDisplay } = _ReactFilter;
+const { Flex } = antd;
+const { useState } = React;
+
+const FilterValueDisplayExample = () => {
+  const [filterValue, setFilterValue] = useState([
+    { name: 'keyword', label: '关键词', value: { label: 'React', value: 'React' } },
+    { name: 'status', label: '状态', value: { label: '已完成', value: 'completed' } },
+    { name: 'amount', label: '金额', value: { label: '100-500万', value: [100, 500] } },
+    {
+      name: 'tags',
+      label: '标签',
+      value: [
+        { label: '前端', value: 'frontend' },
+        { label: 'React', value: 'react' }
+      ]
+    }
+  ]);
+
+  return (
+    <Flex vertical gap={16}>
+      <h4>已选筛选条件展示</h4>
+      <FilterValueDisplay
+        value={filterValue}
+        onChange={setFilterValue}
+        extraExpand={
+          <span style={{ fontSize: 12, color: '#999' }}>
+            共 {filterValue.length} 项
+          </span>
+        }
+      />
+      <Flex gap={8}>
+        <span>当前值:</span>
+        <pre style={{ margin: 0, background: '#f5f5f5', padding: 8, borderRadius: 4, flex: 1 }}>
+          {JSON.stringify(filterValue, null, 2)}
+        </pre>
+      </Flex>
+    </Flex>
+  );
+};
+
+render(<FilterValueDisplayExample />);
+
+```
+
+- 弹出层筛选
+- 使用 PopoverItem 组件实现弹出层形式的筛选项，支持文本输入、数字输入、下拉选择和数值范围等多种交互形式
+- _ReactFilter(@kne/current-lib_react-filter)[import * as _ReactFilter from "@kne/react-filter"],(@kne/current-lib_react-filter/dist/index.css),antd(antd)
+
+```jsx
+const { PopoverItem } = _ReactFilter;
+const { Input, InputNumber, Space, Select, Radio, Flex } = antd;
+const { useState } = React;
+
+const PopoverItemExample = () => {
+  const [inputValue, setInputValue] = useState(null);
+  const [numberValue, setNumberValue] = useState(null);
+  const [selectValue, setSelectValue] = useState(null);
+  const [rangeValue, setRangeValue] = useState(null);
+
+  return (
+    <Flex vertical gap={24}>
+      <h4>弹出层筛选组件示例</h4>
+      <Flex wrap gap={16}>
+        {/* 输入框筛选 */}
+        <PopoverItem
+          label="文本输入"
+          value={inputValue}
+          onChange={setInputValue}
+        >
+          {({ value, onChange }) => (
+            <Input
+              style={{ width: 240 }}
+              placeholder="请输入文本"
+              value={value?.value || ''}
+              onChange={(e) => onChange(
+                e.target.value ? { label: e.target.value, value: e.target.value } : null
+              )}
+            />
+          )}
+        </PopoverItem>
+
+        {/* 数字输入筛选 */}
+        <PopoverItem
+          label="数字输入"
+          value={numberValue}
+          onChange={setNumberValue}
+          onValidate={(val) => val?.value !== undefined}
+        >
+          {({ value, onChange }) => (
+            <InputNumber
+              style={{ width: 240 }}
+              placeholder="请输入数字"
+              value={value?.value}
+              onChange={(val) => onChange(
+                val !== null ? { label: String(val), value: val } : null
+              )}
+            />
+          )}
+        </PopoverItem>
+
+        {/* 下拉选择筛选 */}
+        <PopoverItem
+          label="状态选择"
+          value={selectValue}
+          onChange={setSelectValue}
+        >
+          {({ value, onChange }) => (
+            <Select
+              style={{ width: 240 }}
+              placeholder="请选择状态"
+              value={value?.value}
+              onChange={(val, option) => onChange({
+                value: val,
+                label: option?.label || val
+              })}
+              options={[
+                { value: 'active', label: '激活' },
+                { value: 'inactive', label: '未激活' },
+                { value: 'pending', label: '待处理' }
+              ]}
+            />
+          )}
+        </PopoverItem>
+
+        {/* 数字范围筛选 */}
+        <PopoverItem
+          label="数值范围"
+          value={rangeValue}
+          onChange={setRangeValue}
+          onValidate={(val) => {
+            const range = val?.value;
+            return !(range && range[0] !== undefined && range[1] !== undefined && range[1] < range[0]);
+          }}
+        >
+          {({ value, onChange }) => (
+            <Space.Compact>
+              <InputNumber
+                style={{ width: 100 }}
+                placeholder="最小值"
+                value={value?.value?.[0]}
+                onChange={(val) => onChange({
+                  label: &#96;${val || '?'}-${value?.value?.[1] || '?'}&#96;,
+                  value: [val, value?.value?.[1]]
+                })}
+              />
+              <Input
+                style={{ width: 30, textAlign: 'center', borderLeft: 0, borderRight: 0 }}
+                placeholder="~"
+                disabled
+              />
+              <InputNumber
+                style={{ width: 100 }}
+                placeholder="最大值"
+                value={value?.value?.[1]}
+                onChange={(val) => onChange({
+                  label: &#96;${value?.value?.[0] || '?'}-${val || '?'}&#96;,
+                  value: [value?.value?.[0], val]
+                })}
+              />
+            </Space.Compact>
+          )}
+        </PopoverItem>
+      </Flex>
+
+      <Flex vertical gap={8}>
+        <h5>当前值:</h5>
+        <pre style={{ margin: 0, background: '#f5f5f5', padding: 12, borderRadius: 4 }}>
+          {JSON.stringify({
+            文本输入: inputValue,
+            数字输入: numberValue,
+            状态选择: selectValue,
+            数值范围: rangeValue
+          }, null, 2)}
+        </pre>
+      </Flex>
+    </Flex>
+  );
+};
+
+render(<PopoverItemExample />);
+
+```
 
 ### API
 
-| 属性名             | 说明                                                                           | 类型       | 默认值   |
-|-----------------|------------------------------------------------------------------------------|----------|-------|
-| value           | 筛选器的值，该组件为一个受控组件                                                             | object   | -     |
-| onChange        | 筛选器的值发生改变的时候调用的函数                                                            | function | -     |
-| list            | 筛选器的选项，为一个二维数组，二维数组中的每一个数组为一行，内部数组的每一项为一个筛选选项，筛选选项为Filter.type中的一项或者是自行扩展的选项 | array    | []    |
-| more            | 筛选项更多选项，为一个一维数组，数组中的每一项为一个筛选项，和list不同的是该筛选项默认为收起状态                           | array    | []    |
-| moreLabel       | 更多选项的label                                                                   | string   | 更多    |
-| moreTrigger     | 更多选项的触发方式，默认为hover触发，页可以设置为click                                             | string   | hover |
-| label           | 筛选器的label                                                                    | string   |筛选项|
-| labelHidden     | 筛选器的label及筛选内容行是否隐藏                                                          | boolean  | false    |
-| itemLabelHidden | 筛选项的label是否隐藏                                                                | boolean  |false|
-| unfoldText      | 展开提示文字                                                                       |string| 展开       |
-| foldText        | 收起提示文字                                                                       |string|收起|
-|displayLine| 默认展开行数                                                                       |number|2|
-|defaultDisplay| 默认是否展开                                                                       |boolean|false|
-|isExtra| 是否将list切分成收起项和默认展开项                                                          |boolean|true|
-|extra| 额外内容                                                                         |boolean|null|
+### Filter 主组件
+
+筛选组件，用于展示筛选项和处理筛选条件。
+
+#### 属性
+
+| 属性           | 类型                                                   | 默认值    | 说明              |
+|--------------|------------------------------------------------------|--------|-----------------|
+| value        | `Array<{ name: string, label: string, value: any }>` | -      | 筛选值数组           |
+| defaultValue | `Array<{ name: string, label: string, value: any }>` | `[]`   | 默认筛选值           |
+| onChange     | `(value: Array) => void`                             | -      | 筛选值变化回调         |
+| list         | `Array<Array>`                                       | `[]`   | 筛选项配置数组，支持多行    |
+| displayLine  | `number`                                             | `1`    | 默认展示的行数，超出部分折叠  |
+| label        | `string`                                             | `'筛选'` | 筛选区域标题          |
+| extra        | `ReactNode`                                          | -      | 额外操作区域，通常放置搜索按钮 |
+| extraExpand  | `ReactNode`                                          | -      | 已选区域额外内容        |
+| className    | `string`                                             | -      | 自定义类名           |
+
+#### 静态方法
+
+| 方法                                              | 说明                                                                    |
+|-------------------------------------------------|-----------------------------------------------------------------------|
+| `Filter.getFilterValue(filterValue)`            | 将筛选值数组转换为参数对象，如 `{ name: value }`                                     |
+| `Filter.useFilter()`                            | 获取 Filter Context，返回 `{ value, onChange }`                            |
+| `Filter.pickSelectValues(value)`                | 从筛选值中提取原始值数组，支持 `{ value }`、`{ id }` 格式                              |
+| `Filter.createFilterValueMapper(fieldMappers)`  | 声明式创建 mapFilterValue 函数，按字段映射转换规则                                   |
+| `Filter.filterToUrlParams(filterValue, options)`| 将筛选值数组序列化为 URLSearchParams，保留 label 信息                             |
+| `Filter.parseFilterEntry(str)`                  | 解析 URL 参数中的单个筛选值项为 `{ label, value }`                                |
+| `Filter.takeFilterEntry(searchParams, key, options)` | 从 URL 参数中读取筛选值项，支持单选/多选                                          |
+| `Filter.createUrlFilterReader(searchParams)`    | 创建 URL 筛选参数读取器，自动追踪已消费的参数 key                                       |
+| `Filter.useUrlFilter(options)`                  | 从 URL 参数初始化 Filter 状态的 hook（React Router 环境）                        |
+| `Filter.useUrlFilterValue(mapping)`             | useUrlFilter 的简化版，基于 filterParams[key] 格式自动解析 URL 参数                |
+| `Filter.createUrlParamsReader(searchParams)`    | 创建通用 URL 参数读取器，自动追踪已消费的参数 key                                       |
+| `Filter.stripConsumedUrlParams(searchParams, consumedKeys)` | 从 URL 参数中移除已消费的 key，返回新的 URLSearchParams 或 null |
+| `Filter.filterInterceptors.single`              | 单选拦截器：`{id, name}` ↔ `{label, value}` 数据格式转换                       |
+| `Filter.filterInterceptors.multi`              | 多选拦截器：`[{id, name}]` ↔ `[{label, value}]` 数据格式转换                    |
+
+#### 使用示例
+
+```javascript
+import Filter, { fields } from '@kne/react-filter';
+
+const { InputFilterItem, NumberRangeFilterItem } = fields;
+
+<Filter
+  value={filterValue}
+  onChange={setFilterValue}
+  list={[
+    [
+      { type: InputFilterItem, props: { name: 'keyword', label: '关键词' } },
+      { type: NumberRangeFilterItem, props: { name: 'amount', label: '金额' } }
+    ]
+  ]}
+  displayLine={1}
+  extra={<Button type="primary">搜索</Button>}
+/>
+```
+
+---
+
+### AdvancedFilter 高级筛选组件
+
+高级筛选组件，用于更复杂的筛选场景，采用垂直布局。
+
+#### 属性
+
+| 属性           | 类型                                                   | 默认值  | 说明       |
+|--------------|------------------------------------------------------|------|----------|
+| value        | `Array<{ name: string, label: string, value: any }>` | -    | 筛选值数组    |
+| defaultValue | `Array<{ name: string, label: string, value: any }>` | `[]` | 默认筛选值    |
+| onChange     | `(value: Array) => void`                             | -    | 筛选值变化回调  |
+| list         | `Array<Array>`                                       | `[]` | 筛选项配置数组  |
+| more         | `Array`                                              | -    | 额外折叠的筛选项 |
+| className    | `string`                                             | -    | 自定义类名    |
+
+#### 使用示例
+
+```javascript
+import { AdvancedFilter, fields } from '@kne/react-filter';
+
+<AdvancedFilter
+  value={filterValue}
+  onChange={setFilterValue}
+  list={[
+    [
+      { type: InputFilterItem, props: { name: 'name', label: '姓名' } }
+    ]
+  ]}
+/>
+```
+
+---
+
+### FilterValueDisplay 已选值展示
+
+展示已选择的筛选条件，支持单独删除和清空全部。
+
+#### 属性
+
+| 属性          | 类型                                                   | 默认值 | 说明      |
+|-------------|------------------------------------------------------|-----|---------|
+| value       | `Array<{ name: string, label: string, value: any }>` | -   | 筛选值数组   |
+| onChange    | `(value: Array) => void`                             | -   | 筛选值变化回调 |
+| extraExpand | `ReactNode`                                          | -   | 额外展示内容  |
+
+---
+
+### PopoverItem 弹出层筛选项
+
+弹出层形式的筛选项，支持确认取消操作。
+
+#### 属性
+
+| 属性               | 类型                                          | 默认值            | 说明        |
+|------------------|---------------------------------------------|----------------|-----------|
+| label            | `string`                                    | -              | 筛选项标签     |
+| value            | `{ label: string, value: any }`             | -              | 当前值       |
+| onChange         | `(value: object) => void`                   | -              | 值变化回调     |
+| onValidate       | `(value: object) => boolean`                | -              | 确认按钮校验函数  |
+| onOpenChange     | `(open: boolean) => void`                   | -              | 弹出层状态变化回调 |
+| placement        | `string`                                    | `'bottomLeft'` | 弹出层位置     |
+| overlayClassName | `string`                                    | -              | 弹出层自定义类名  |
+| children         | `(props: { value, onChange }) => ReactNode` | -              | 内容渲染函数    |
+
+#### 使用示例
+
+```javascript
+import { PopoverItem } from '@kne/react-filter';
+
+<PopoverItem
+  label="文本输入"
+  value={inputValue}
+  onChange={setInputValue}
+>
+  {({ value, onChange }) => (
+    <Input
+      value={value?.value}
+      onChange={(e) => onChange({ label: e.target.value, value: e.target.value })}
+    />
+  )}
+</PopoverItem>
+```
+
+---
+
+### FilterItem 筛选项容器
+
+筛选项的基础容器组件。
+
+#### 属性
+
+| 属性       | 类型          | 默认值 | 说明         |
+|----------|-------------|-----|------------|
+| label    | `string`    | -   | 筛选项标签      |
+| open     | `boolean`   | -   | 是否展开状态     |
+| active   | `boolean`   | -   | 是否激活状态（有值） |
+| children | `ReactNode` | -   | 子元素        |
+
+---
+
+### FilterLines 筛选行
+
+筛选行组件，支持多行展开收起。
+
+#### 属性
+
+| 属性          | 类型             | 默认值    | 说明      |
+|-------------|----------------|--------|---------|
+| list        | `Array<Array>` | `[]`   | 筛选项配置数组 |
+| displayLine | `number`       | `1`    | 默认展示行数  |
+| label       | `string`       | `'筛选'` | 标题      |
+| extra       | `ReactNode`    | -      | 额外操作区域  |
+| className   | `string`       | -      | 自定义类名   |
+
+---
+
+### FilterProvider 状态管理
+
+Filter 状态管理组件，用于自定义 Filter 结构。
+
+#### 属性
+
+| 属性           | 类型                                    | 默认值  | 说明       |
+|--------------|---------------------------------------|------|----------|
+| value        | `Array`                               | -    | 筛选值数组    |
+| defaultValue | `Array`                               | `[]` | 默认筛选值    |
+| onChange     | `(value: Array) => void`              | -    | 筛选值变化回调  |
+| children     | `ReactNode \| (context) => ReactNode` | -    | 子元素或渲染函数 |
+
+---
+
+### 高阶组件
+
+#### withFilterValue
+
+为组件注入筛选值和变更函数。
+
+```javascript
+import { withFilterValue } from '@kne/react-filter';
+
+const MyFilterItem = withFilterValue(({ name, label, value, onChange, ...props }) => {
+  return <Component value={value} onChange={onChange}/>;
+});
+```
+
+#### withFieldItem
+
+为组件包装 FilterItem 样式。
+
+```javascript
+import { withFieldItem } from '@kne/react-filter';
+
+const MyFieldItem = withFieldItem(MyComponent);
+```
+
+---
+
+### 筛选字段组件
+
+#### InputFilterItem 输入筛选
+
+弹出层形式的输入框筛选组件。
+
+| 属性          | 类型                   | 默认值 | 说明     |
+|-------------|----------------------|-----|--------|
+| name        | `string`             | -   | 字段名称   |
+| label       | `string`             | -   | 标签     |
+| placeholder | `string`             | -   | 占位符    |
+| onValidate  | `(value) => boolean` | -   | 确认校验函数 |
+
+#### NumberRangeFilterItem 数字区间筛选
+
+数字区间输入筛选组件。
+
+| 属性          | 类型       | 默认值 | 说明   |
+|-------------|----------|-----|------|
+| name        | `string` | -   | 字段名称 |
+| label       | `string` | -   | 标签   |
+| unit        | `string` | -   | 单位   |
+| min         | `number` | -   | 最小值  |
+| max         | `number` | -   | 最大值  |
+| placeholder | `string` | -   | 占位符  |
+
+#### DatePickerFilterItem 日期筛选
+
+日期选择筛选组件。
+
+| 属性     | 类型                                                   | 默认值            | 说明    |
+|--------|------------------------------------------------------|----------------|-------|
+| name   | `string`                                             | -              | 字段名称  |
+| label  | `string`                                             | -              | 标签    |
+| picker | `'date' \| 'week' \| 'month' \| 'quarter' \| 'year'` | `'date'`       | 选择器类型 |
+| format | `string`                                             | `'YYYY-MM-DD'` | 日期格式  |
+
+#### DateRangePickerFilterItem 日期范围筛选
+
+日期范围选择筛选组件。
+
+| 属性     | 类型                                  | 默认值            | 说明   |
+|--------|-------------------------------------|----------------|------|
+| name   | `string`                            | -              | 字段名称 |
+| label  | `string`                            | -              | 标签   |
+| format | `string`                            | `'YYYY-MM-DD'` | 日期格式 |
+| header | `ReactNode \| (props) => ReactNode` | -              | 头部内容 |
+
+#### TypeDateRangePickerFilterItem 类型日期范围筛选
+
+支持按日/周/月切换的日期范围选择筛选组件。
+
+| 属性     | 类型       | 默认值            | 说明   |
+|--------|----------|----------------|------|
+| name   | `string` | -              | 字段名称 |
+| label  | `string` | -              | 标签   |
+| format | `string` | `'YYYY-MM-DD'` | 日期格式 |
 
-#### Filter.type
+#### SuperSelectFilterItem 通用选择器筛选
 
-City(城市选择), List(列表选择，可以多选或者单选), Range(数据范围), Text(文字输入) Text.Number, Selector(下拉选项), Check(单项选择), RadioList(单选列表),
-CheckboxList（多选列表）
+基于 `@kne/super-select` 的通用选择器筛选项，支持单选/多选、搜索、全选等功能。
 
-DateTime(时间选择),DateTime.Time DateTime.Range DateTime.Week DateTime.Month DateTime.Year
+| 属性               | 类型                          | 默认值     | 说明       |
+|------------------|-----------------------------|---------|----------|
+| name             | `string`                    | -       | 字段名称     |
+| label            | `string`                    | -       | 标签       |
+| options          | `Array<{ value, label }>`   | -       | 选项数据     |
+| single           | `boolean`                   | `false` | 是否单选     |
+| allowSelectedAll | `boolean`                   | `false` | 是否支持全选   |
+| maxLength        | `number`                    | -       | 最多可选数量   |
 
-公共参数
+**使用示例：**
 
-| 属性名   | 说明                                         | 类型     | 默认值 |
-|-------|--------------------------------------------|--------|-----|
-| label | 筛选项名称                                      | string | -   |
-| name  | 筛选项的key                                    | string | -   |
-| placeholder| 筛选项的placeholder(如果可以显示的话)，如果不传值通常会去label的值 | string |-|
+```javascript
+import { SuperSelectFilterItem } from '@kne/react-filter';
 
-#### Text|Text.Number|Range
+// 多选
+<SuperSelectFilterItem
+  label="部门"
+  options={[
+    { value: 'tech', label: '技术研发部' },
+    { value: 'product', label: '产品设计部' }
+  ]}
+/>
 
-| 属性名   | 说明                                                    | 类型     | 默认值 |
-|-------|-------------------------------------------------------|--------|-----|
-|onBeforeSearch| 带有确定按钮的筛选项，在点击确定后会调用该方法，如果该方法返回为false，则该选项的值不会被提交给筛选项 | function | -   |
+// 单选
+<SuperSelectFilterItem
+  label="状态"
+  single
+  options={[
+    { value: 'active', label: '启用' },
+    { value: 'inactive', label: '停用' }
+  ]}
+/>
+```
+
+> 注意：需要安装 `@kne/super-select` 依赖。
+
+#### SelectFunctionFilterItem 职能筛选
+
+基于 `@kne/super-select-plus` 的职能选择器筛选项，支持多级职能数据选择、拼音搜索。
+
+| 属性        | 类型        | 默认值     | 说明       |
+|-----------|-----------|---------|----------|
+| name      | `string`  | -       | 字段名称     |
+| label     | `string`  | -       | 标签       |
+| single    | `boolean` | `false` | 是否单选     |
+| maxLength | `number`  | -       | 最多可选数量   |
+
+> 注意：需要安装 `@kne/super-select-plus` 依赖。
+
+#### SelectIndustryFilterItem 行业筛选
+
+基于 `@kne/super-select-plus` 的行业选择器筛选项，支持多级行业数据选择、拼音搜索。
+
+| 属性        | 类型        | 默认值     | 说明       |
+|-----------|-----------|---------|----------|
+| name      | `string`  | -       | 字段名称     |
+| label     | `string`  | -       | 标签       |
+| single    | `boolean` | `false` | 是否单选     |
+| maxLength | `number`  | -       | 最多可选数量   |
+
+> 注意：需要安装 `@kne/super-select-plus` 依赖。
+
+#### SelectAddressFilterItem 城市筛选
+
+基于 `@kne/super-select-plus` 的城市选择器筛选项，支持国内外城市搜索选择。
+
+| 属性        | 类型        | 默认值     | 说明       |
+|-----------|-----------|---------|----------|
+| name      | `string`  | -       | 字段名称     |
+| label     | `string`  | -       | 标签       |
+| single    | `boolean` | `false` | 是否单选     |
+| maxLength | `number`  | -       | 最多可选数量   |
+
+> 注意：需要安装 `@kne/super-select-plus` 依赖。
+
+#### CityFilterItem（高级筛选）
+
+城市选择器的高级筛选版本，用于 `AdvancedFilter` 组件的 `list` 配置中。展示热门城市标签，支持搜索选择其他城市。
+
+| 属性        | 类型        | 默认值     | 说明         |
+|-----------|-----------|---------|------------|
+| single    | `boolean` | `false` | 是否单选       |
+| maxLength | `number`  | `5`     | 最多可选数量     |
+
+**在高级筛选中使用：**
+
+```javascript
+import { AdvancedFilter } from '@kne/react-filter';
+import { CityFilterItem } from './AdvancedFilter/fields';
+
+<AdvancedFilter
+  list={[
+    [{ type: CityFilterItem, props: { label: '城市', single: true } }]
+  ]}
+/>
+```
+
+---
+
+### TypeDateRangePickerField 类型日期范围选择器
+
+支持按日/周/月切换的日期范围选择器基础组件。
+
+| 属性              | 类型                                                         | 默认值                             | 说明       |
+|-----------------|------------------------------------------------------------|---------------------------------|----------|
+| value           | `{ type: string, value: [Date, Date] }`                    | -                               | 当前值      |
+| defaultValue    | `{ type: string, value: [Date, Date] }`                    | `{ type: 'date', value: null }` | 默认值      |
+| onChange        | `(value: object) => void`                                  | -                               | 值变化回调    |
+| shortcuts       | `boolean`                                                  | `true`                          | 是否显示快捷选项 |
+| shortcutOptions | `Array<{ label: string, getValue: () => [Dayjs, Dayjs] }>` | -                               | 自定义快捷选项  |
+
+**value 结构：**
+
+```typescript
+interface TypeDateRangeValue {
+  type: 'date' | 'week' | 'month';  // 日期类型
+  value: [Date, Date] | null;       // 日期范围 [开始时间, 结束时间]
+}
+```
+
+**默认快捷选项：**
+
+- 近7天：`dayjs().subtract(7, 'day')` 至今天
+- 本月：本月第一天至最后一天
+- 近三个月：`dayjs().subtract(3, 'month')` 至今天
+- 当年：本年第一天至最后一天
+
+**自定义快捷选项示例：**
+
+```javascript
+import { TypeDateRangePickerField } from '@kne/react-filter';
+
+<TypeDateRangePickerField
+  shortcuts={true}
+  shortcutOptions={[
+    {
+      label: '最近一周',
+      getValue: () => [dayjs().subtract(7, 'day').startOf('day'), dayjs().endOf('day')]
+    },
+    {
+      label: '最近一月',
+      getValue: () => [dayjs().subtract(1, 'month').startOf('day'), dayjs().endOf('day')]
+    }
+  ]}
+/>
+```
+
+---
+
+### SearchInput 搜索输入
+
+搜索输入组件。
+
+| 属性          | 类型       | 默认值 | 说明   |
+|-------------|----------|-----|------|
+| name        | `string` | -   | 字段名称 |
+| label       | `string` | -   | 标签   |
+| placeholder | `string` | -   | 占位符  |
+
+---
+
+### 工具方法
+
+#### getFilterValue
+
+将筛选值数组转换为参数对象。
+
+```javascript
+import { getFilterValue } from '@kne/react-filter';
+
+const filterValue = [
+  { name: 'keyword', value: { label: 'test', value: 'test' } },
+  { name: 'status', value: [{ label: '已完成', value: 'done' }] }
+];
+
+const params = getFilterValue(filterValue);
+// { keyword: 'test', status: ['done'] }
+```
+
+---
+
+### 筛选值结构
+
+筛选值数组中的每一项结构：
+
+```typescript
+interface FilterValueItem {
+  name: string;      // 字段名称
+  label: string;     // 字段标签（用于展示）
+  value: {           // 单个值
+    label: string;   // 显示文本
+    value: any;      // 实际值
+  } | Array<{        // 或多个值
+    label: string;
+    value: any;
+  }> | null;         // 或空值
+}
+```
+
+---
+
+### URL 参数相关
+
+#### filterToUrlParams
+
+将筛选值数组序列化为 URLSearchParams，保留 label 信息以便反序列化还原完整筛选状态。
+
+| 参数             | 类型             | 默认值             | 说明                       |
+|----------------|----------------|-----------------|--------------------------|
+| filterValue    | `Array`        | -               | 筛选值数组                    |
+| options.prefix | `string`       | `'filterParams'` | URL 参数前缀，设为空字符串则不加前缀     |
+
+**序列化格式**：
+- 单值且 `label === value`：`prefix[name]=value`（如输入框）
+- 单值且 `label !== value`：`prefix[name]=label:value`
+- 多值：`prefix[name]=label1:value1,label2:value2`
+
+**使用示例：**
+
+```javascript
+import { filterToUrlParams } from '@kne/react-filter';
+
+const params = filterToUrlParams([
+  { name: 'keyword', label: '关键词', value: { label: '测试', value: '测试' } },
+  { name: 'city', label: '城市', value: [{ label: '上海', value: '010' }, { label: '北京', value: '020' }] },
+]);
+// params.toString() => 'filterParams[keyword]=测试&filterParams[city]=上海:010,北京:020'
+
+// 自定义前缀
+filterToUrlParams(filterValue, { prefix: 'f' });
+// => 'f[keyword]=测试'
+
+// 无前缀（直接平铺到 URL）
+filterToUrlParams(filterValue, { prefix: '' });
+// => 'keyword=测试'
+```
+
+---
+
+#### parseFilterEntry
+
+解析 URL 参数中的单个筛选值项，反序列化为 `{ label, value }` 对象。
+
+| 参数  | 类型       | 说明            |
+|-----|----------|---------------|
+| str | `string` | URL 参数中的原始字符串 |
+
+**解析规则**：
+- 无冒号：label 和 value 相同，如 `"测试"` → `{ label: '测试', value: '测试' }`
+- 有冒号：冒号前为 label，冒号后为 value，如 `"启用:active"` → `{ label: '启用', value: 'active' }`
+
+```javascript
+import { parseFilterEntry } from '@kne/react-filter';
+
+parseFilterEntry('测试');
+// => { label: '测试', value: '测试' }
+
+parseFilterEntry('启用:active');
+// => { label: '启用', value: 'active' }
+```
+
+---
+
+#### takeFilterEntry
+
+从 URL 参数中读取筛选值项，返回单选 `{ label, value }` 或多选数组。
 
-##### Range|DateTime.Range
+| 参数              | 类型                | 默认值             | 说明               |
+|-----------------|-------------------|-----------------|------------------|
+| searchParams    | `URLSearchParams` | -               | URL 参数对象         |
+| key             | `string`          | -               | 参数名（不含前缀）        |
+| options.multi   | `boolean`         | `false`         | 是否多选             |
+| options.prefix  | `string`          | `'filterParams'` | URL 参数前缀         |
 
-| 属性名   | 说明                                                           | 类型       | 默认值 |
-|-------|--------------------------------------------------------------|----------|-----|
-|   template    | 将一组数据范围显示成一段用户可阅读的问题的模版，参数为筛选项的值,要求返回一个描述的字符串                | function | -   |
-|placeholder| 当为字符串时前后两个输入框显示同样内容，当为一个数组时，第一个输入框显示数组的第一个值，第二个输入框显示为数组的第二个值 | string&#124;array                                | -        |
+```javascript
+import { takeFilterEntry } from '@kne/react-filter';
 
-#### Range
+// URL: ?filterParams[city]=上海:010,北京:020
+takeFilterEntry(searchParams, 'city', { multi: true });
+// => [{ label: '上海', value: '010' }, { label: '北京', value: '020' }]
 
-| 属性名   | 说明                       | 类型     | 默认值 |
-|-------|--------------------------|--------|-----|
-|startProps| 该参数会结构以后传给第一个InputNumber | object |-|
-|endProps| 该参数会结构以后传给第二个InputNumber | object |-|
+takeFilterEntry(searchParams, 'keyword', { prefix: '' });
+// => { label: '测试', value: '测试' }
+```
+
+---
+
+#### createUrlFilterReader
+
+创建 URL 筛选参数读取器，自动追踪已消费的参数 key。配合 `useUrlFilter` 使用，readUrlParams 返回的 consumedKeys 可被自动清除。
+
+| 参数              | 类型                | 默认值             | 说明       |
+|-----------------|-------------------|-----------------|----------|
+| searchParams    | `URLSearchParams` | -               | URL 参数对象 |
+| options.prefix  | `string`          | `'filterParams'` | URL 参数前缀 |
+
+**返回值**：`{ takeFilterEntry, getConsumedKeys }`
+
+```javascript
+import { createUrlFilterReader } from '@kne/react-filter';
+
+const { takeFilterEntry, getConsumedKeys } = createUrlFilterReader(searchParams);
+const keyword = takeFilterEntry('keyword');
+const city = takeFilterEntry('city', { multi: true });
+// getConsumedKeys() => ['filterParams[keyword]', 'filterParams[city]']
+```
+
+---
+
+#### useUrlFilter
+
+从 URL 参数初始化 Filter 状态的 hook，读取 URL 参数构建初始筛选值，并在挂载后自动清除已消费的 URL 参数。
+
+> 需要 React Router 环境支持 `useSearchParams`。
+
+| 参数                  | 类型         | 说明                                           |
+|---------------------|------------|----------------------------------------------|
+| options.readUrlParams | `Function` | 读取 URL 参数并返回 `{ consumedKeys: string[], ...data }` |
+| options.buildFilter   | `Function` | 接收 readUrlParams 的返回值，构建初始 filter 数组          |
+
+**返回值**：`[filter, setFilter]`
+
+```javascript
+import { useUrlFilter, createUrlParamsReader } from '@kne/react-filter';
+
+const [filter, setFilter] = useUrlFilter({
+  readUrlParams: (searchParams) => {
+    const { take, getConsumedKeys } = createUrlParamsReader(searchParams);
+    const orgId = take('tenantOrgId');
+    return { consumedKeys: getConsumedKeys(), orgId };
+  },
+  buildFilter: ({ orgId }) => [
+    { name: 'status', value: { label: '开启', value: 'open' } },
+    ...(orgId ? [{ name: 'tenantOrgId', value: { label: orgId, value: orgId } }] : [])
+  ]
+});
+```
 
-#### List
+---
 
-| 属性名      | 说明                                                                           | 类型                      | 默认值 |
-|----------|------------------------------------------------------------------------------|-------------------------|-----|
-| children | 筛选项的每一项的值，必须为 List.Item，也可以为一个render function可以接收到参数render({value,onChange}) | List.Item&#124;function | -   |
-| size     | 最大可以选中数量，等于1的时候为单选，操作逻辑和多选略有不同                                               | number                  |2|
-| options| 筛选项，为一个数组，每一项的值为{label,value}该属性有值优先取该值忽略children                            | array                   |-|
+#### useUrlFilterValue
 
-#### List.Item
+`useUrlFilter` 的简化版，基于 `filterParams[key]` 格式自动解析 URL 参数，支持单选和多选。
 
-| 属性名   | 说明     | 类型     | 默认值 |
-|-------|--------|--------|-----|
-| value | 筛选项的值  | -      | -   |
-| label | 筛选项显示项 | string | -   |
+| 参数      | 类型                     | 说明                             |
+|---------|------------------------|--------------------------------|
+| mapping | `string[] \| Object`   | URL 参数映射，支持数组、对象两种格式           |
 
-#### SearchButton
+**数组形式（默认单选）：**
+```javascript
+import { useUrlFilterValue } from '@kne/react-filter';
 
-用于自行封装过滤选项时的工具组件。Text,Text.Number，Range使用该组件实现。该组件可以让筛选项有一个包裹层在鼠标经过时显示，同时有一个确定按钮，在确定按钮点击时筛选项的结果会提交到Filter。
+const [filter, setFilter] = useUrlFilterValue(['keyword', 'status']);
+// URL: ?filterParams[keyword]=前端开发&filterParams[status]=招聘中:active
+// → filter: [
+//     { name: 'keyword', value: { label: '前端开发', value: '前端开发' } },
+//     { name: 'status', value: { label: '招聘中', value: 'active' } }
+//   ]
+```
+
+**对象形式（多选 + 自定义）：**
+```javascript
+const [filter, setFilter] = useUrlFilterValue({
+  keyword: true,                        // 单选
+  city: { multi: true },               // 多选
+  status: (parsed) => {                // 自定义转换
+    return parsed ? { name: 'status', value: parsed } : null;
+  }
+});
+// URL: ?filterParams[keyword]=测试&filterParams[city]=上海:010,北京:020
+```
+
+---
+
+#### createUrlParamsReader
+
+创建通用 URL 参数读取器，自动追踪已消费的参数 key。
+
+| 参数           | 类型                | 说明       |
+|--------------|-------------------|----------|
+| searchParams | `URLSearchParams` | URL 参数对象 |
+
+**返回值**：`{ take, getConsumedKeys }`
+- `take(key)` - 读取参数值，记录已消费
+- `getConsumedKeys()` - 返回已消费的 key 列表
+
+```javascript
+import { createUrlParamsReader } from '@kne/react-filter';
 
-| 属性名   | 说明                                                                        | 类型      | 默认值   |
-|-------|---------------------------------------------------------------------------|---------|-------|
-| defaultActive | 默认是否激活活跃状态                                                                | boolean | false |
-|defaultValue| 默认值通常不需要传，会取筛选器的对应项的值                                                     |-|-|
-|buttonText| 确认按钮的文案                                                                   | string  | 确定    |
-|template| 格式化结果函数                                                                   |function|-|
-|children| 是一个函数，需要传一个render函数返回内层的输入组件，会接收到children({value, setValue, setActive})参数 |function|-|
-|onBlur| 会模拟一个失去焦点的事件，点击该组件区域外的地方会触发并执行该函数                                         |function|-|
-|onSearch| 点击确认按钮时触发函数                                                               |function|-|
-|onBeforeSearch| 点击确认按钮会先触发该函数如果该函数显示返回false值则不会再触发onSearch函数，用于再筛选项的值提交给筛选器之前的数据验证|function|-|
-|onActiveChange|激活状态改变时触发函数|function|-|
+const { take, getConsumedKeys } = createUrlParamsReader(searchParams);
+const orgId = take('tenantOrgId');
+const orgName = take('orgName');
+// getConsumedKeys() => ['tenantOrgId', 'orgName']
+```
+
+---
+
+#### stripConsumedUrlParams
+
+从 URL 参数中移除已消费的 key，返回新的 URLSearchParams 或 null（无变化时）。
+
+| 参数           | 类型                | 说明                |
+|--------------|-------------------|-------------------|
+| searchParams | `URLSearchParams` | 当前 URL 参数         |
+| consumedKeys | `string[]`        | 需要移除的 key 列表      |
+
+**返回值**：`URLSearchParams | null`
+
+```javascript
+import { stripConsumedUrlParams } from '@kne/react-filter';
+
+const nextParams = stripConsumedUrlParams(searchParams, ['tenantOrgId', 'orgName']);
+if (nextParams) {
+  setSearchParams(nextParams, { replace: true });
+}
+```
 
-其他参数参考对应内部组件的参数
+---
 
+### 拦截器
+
+用于 SuperSelect 组件的 `{id, name}` 与 Filter 的 `{label, value}` 数据格式互转。
+
+#### singleSelectInterceptor
+
+单选拦截器：`{id, name}` ↔ `{label, value}`。
+
+| 属性      | 类型         | 说明                                    |
+|---------|------------|---------------------------------------|
+| input   | `Function` | `{id, name}` → `{label, value}` 的转换   |
+| output  | `Function` | `{label, value}` → `{id, name}` 的转换   |
+
+#### multiSelectInterceptor
+
+多选拦截器：`[{id, name}]` ↔ `[{label, value}]`。
+
+| 属性      | 类型         | 说明                                        |
+|---------|------------|-------------------------------------------|
+| input   | `Function` | `[{id, name}]` → `[{label, value}]` 的转换    |
+| output  | `Function` | `[{label, value}]` → `[{id, name}]` 的转换    |
+
+#### filterInterceptors
+
+拦截器集合对象。
+
+```javascript
+import { filterInterceptors, singleSelectInterceptor, multiSelectInterceptor } from '@kne/react-filter';
+
+// 两种引用方式等价
+filterInterceptors.single === singleSelectInterceptor; // true
+filterInterceptors.multi === multiSelectInterceptor;   // true
+```
+
+**使用示例：**
+
+```javascript
+import { filterInterceptors } from '@kne/react-filter';
+
+// 在 SuperSelect 组件中使用单选拦截
+<SuperSelect
+  valueKey="id"
+  labelKey="name"
+  interceptor={filterInterceptors.single}
+  /* ... */
+/>
+
+// 多选拦截
+<SuperSelect
+  valueKey="id"
+  labelKey="name"
+  interceptor={filterInterceptors.multi}
+  /* ... */
+/>
+```
+
+---
+
+### 工具方法
+
+#### pickSelectValues
+
+从筛选值中提取原始值数组。支持原始值、`{ value }` 对象、`{ id }` 对象以及它们的数组。
+
+| 参数    | 类型    | 说明          |
+|-------|-------|-------------|
+| value | `any` | 筛选值，支持多种格式 |
+
+```javascript
+import { pickSelectValues } from '@kne/react-filter';
+
+pickSelectValues([{ value: 1 }, { id: 2 }, '3']);
+// => ['1', '2', '3']
+
+pickSelectValues({ value: 'open' });
+// => ['open']
+
+pickSelectValues(null);
+// => []
+```
+
+#### createFilterValueMapper
+
+声明式创建 mapFilterValue 函数。`Filter.getFilterValue` 默认只读取 `{ value }`，而 SuperSelectFilterItem 等组件使用 `{ id, name }` 格式，需要额外处理。此工具通过声明字段映射规则，自动生成转换函数。
+
+| 参数           | 类型       | 说明                |
+|--------------|----------|-------------------|
+| fieldMappers | `Object` | 字段名到映射规则的映射       |
+
+**映射规则类型：**
+
+| 规则        | 说明                                     |
+|-----------|----------------------------------------|
+| `'string'` | 确保值为字符串类型                              |
+| `'multi'`  | 多选，从 filter entry 提取值数组                 |
+| `'single'` | 单选，从 filter entry 提取第一个值                |
+| `Function` | 自定义转换，接收 `(rawValue, { entry, filter, value })` |
+
+```javascript
+import { createFilterValueMapper } from '@kne/react-filter';
+
+const mapFilterValue = createFilterValueMapper({
+  id: 'string',
+  roles: 'multi',
+  tenantOrgId: 'single',
+  status: (rawValue) => normalizeStatus(rawValue)
+});
+
+const filterValue = mapFilterValue(filter, Filter.getFilterValue);
+```