@kne/react-filter 1.0.4 → 1.0.6

package/README.md

@@ -95,6 +95,9 @@ function MyComponent() {
 | `DateRangePickerFilterItem` | 日期范围筛选 |
 | `TypeDateRangePickerFilterItem` | 类型日期范围筛选（日/周/月切换） |
 | `SuperSelectFilterItem` | 通用选择器筛选（单选/多选/搜索/全选） |
+| `SelectTableListFilterItem` | 表格选择器筛选（多列数据展示） |
+| `SelectTreeFilterItem` | 树形选择器筛选（层级数据） |
+| `SelectCascaderFilterItem` | 级联选择器筛选（父子关联、搜索过滤） |
 | `SelectFunctionFilterItem` | 职能筛选（多级数据、拼音搜索） |
 | `SelectIndustryFilterItem` | 行业筛选（多级数据、拼音搜索） |
 | `SelectAddressFilterItem` | 城市筛选（国内外城市搜索） |
@@ -140,7 +143,7 @@ const {
   SelectIndustryFilterItem, SelectAddressFilterItem
 } = fields;
 const { Flex, Button, message } = antd;
-const { useState } = React;
+const { useState, useRef, useEffect } = React;
 
 const departmentOptions = [
   { value: 'tech', label: '技术研发部' },
@@ -151,8 +154,70 @@ const departmentOptions = [
   { value: 'marketing', label: '市场营销部' }
 ];
 
+const filterList = [
+  {
+    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: '城市' }
+  }
+];
+
+const ContainerWidthIndicator = ({ containerRef }) => {
+  const [width, setWidth] = useState(0);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return undefined;
+
+    const update = () => setWidth(Math.round(el.clientWidth));
+    update();
+
+    const observer = new ResizeObserver(update);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [containerRef]);
+
+  return (
+    <div style={{ fontSize: 12, color: '#999', marginBottom: 4 }}>
+      中间容器宽度: {width}px（观察收起/更多时是否持续增大或跳动）
+    </div>
+  );
+};
+
 const BaseExample = () => {
   const [filterValue, setFilterValue] = useState([]);
+  const filterContainerRef = useRef(null);
 
   const handleSearch = () => {
     const params = Filter.getFilterValue(filterValue);
@@ -161,54 +226,35 @@ const BaseExample = () => {
   };
 
   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 vertical gap={16} style={{ width: '100%' }}>
+      <div style={{ width: '100%' }}>
+        <ContainerWidthIndicator containerRef={filterContainerRef} />
+        <div
+          style={{
+            width: '100%',
+            display: 'flex',
+            alignItems: 'flex-start',
+            gap: 8
+          }}
+        >
+          <Button>左侧操作</Button>
+          <div
+            ref={filterContainerRef}
+            style={{
+              flex: 1,
+              minWidth: 0,
+              overflow: 'hidden',
+              border: '1px dashed #d9d9d9',
+              borderRadius: 4
+            }}
+          >
+            <Filter value={filterValue} onChange={setFilterValue} list={filterList} />
+          </div>
+          <Button type="primary" onClick={handleSearch}>
+            搜索
+          </Button>
+        </div>
+      </div>
       <Flex gap={8}>
         <span>当前筛选值:</span>
         <pre style={{ margin: 0, background: '#f5f5f5', padding: 8, borderRadius: 4, flex: 1 }}>{JSON.stringify(filterValue, null, 2)}</pre>
@@ -333,7 +379,7 @@ render(<AdvancedFilterExample />);
 ```
 
 - 筛选字段组件
-- 展示所有筛选字段组件类型，包括输入筛选、数字区间、日期选择、下拉选择以及 SuperSelect 业务选择器（职能/行业/城市）
+- 展示所有筛选字段组件类型，包括输入筛选、数字区间、日期选择、下拉选择以及 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
@@ -341,8 +387,8 @@ const { fields, PopoverItem } = _ReactFilter;
 const {
   InputFilterItem, NumberRangeFilterItem, DatePickerFilterItem,
   DateRangePickerFilterItem, TypeDateRangePickerFilterItem,
-  SuperSelectFilterItem, SelectFunctionFilterItem,
-  SelectIndustryFilterItem, SelectAddressFilterItem
+  SuperSelectFilterItem, SelectTableListFilterItem, SelectTreeFilterItem, SelectCascaderFilterItem,
+  SelectFunctionFilterItem, SelectIndustryFilterItem, SelectAddressFilterItem
 } = fields;
 const { Input, InputNumber, Space, Flex, Select, Divider, Tag } = antd;
 const { useState } = React;
@@ -512,6 +558,120 @@ const SuperSelectExample = () => {
   );
 };
 
+// SuperSelect 其他选择组件示例（表格/树形/级联）
+const employeeOptions = [
+  { id: 'emp_1', name: '张三', department: '技术研发部', position: '工程师' },
+  { id: 'emp_2', name: '李四', department: '产品设计部', position: '设计师' },
+  { id: 'emp_3', name: '王五', department: '运营部', position: '经理' },
+  { id: 'emp_4', name: '赵六', department: '市场部', position: '专员' },
+  { id: 'emp_5', name: '钱七', department: '技术研发部', position: '工程师' }
+];
+
+const employeeColumns = [
+  { name: 'name', title: '姓名', span: 8 },
+  { name: 'department', title: '部门', span: 8 },
+  { name: 'position', title: '职位', span: 8 }
+];
+
+const organizationTree = [
+  { id: 'root', parentId: null, name: '集团总部' },
+  { id: 'tech', parentId: 'root', name: '技术中心' },
+  { id: 'tech-fe', parentId: 'tech', name: '前端开发组' },
+  { id: 'tech-be', parentId: 'tech', name: '后端开发组' },
+  { id: 'product', parentId: 'root', name: '产品中心' },
+  { id: 'product-design', parentId: 'product', name: '产品设计组' }
+];
+
+const regionData = [
+  {
+    id: 'beijing',
+    name: '北京市',
+    children: [
+      { id: 'haidian', name: '海淀区' },
+      { id: 'chaoyang', name: '朝阳区' }
+    ]
+  },
+  {
+    id: 'guangdong',
+    name: '广东省',
+    children: [
+      {
+        id: 'guangzhou',
+        name: '广州市',
+        children: [
+          { id: 'tianhe', name: '天河区' },
+          { id: 'yuexiu', name: '越秀区' }
+        ]
+      },
+      {
+        id: 'shenzhen',
+        name: '深圳市',
+        children: [
+          { id: 'nanshan', name: '南山区' },
+          { id: 'futian', name: '福田区' }
+        ]
+      }
+    ]
+  }
+];
+
+const SuperSelectVariantsExample = () => {
+  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}>
+        <SelectTableListFilterItem
+          label="员工（表格多选）"
+          value={values.employee}
+          onChange={(val) => setValues(prev => ({ ...prev, employee: val }))}
+          options={employeeOptions}
+          columns={employeeColumns}
+          valueKey="id"
+          labelKey="name"
+        />
+        <SelectTreeFilterItem
+          label="部门（树形多选）"
+          value={values.department}
+          onChange={(val) => setValues(prev => ({ ...prev, department: val }))}
+          options={organizationTree}
+          valueKey="id"
+          labelKey="name"
+        />
+        <SelectCascaderFilterItem
+          label="地区（级联多选）"
+          value={values.region}
+          onChange={(val) => setValues(prev => ({ ...prev, region: val }))}
+          options={regionData}
+          valueKey="id"
+          labelKey="name"
+        />
+        <SelectCascaderFilterItem
+          label="地区（级联单选）"
+          single
+          value={values.singleRegion}
+          onChange={(val) => setValues(prev => ({ ...prev, singleRegion: val }))}
+          options={regionData}
+          valueKey="id"
+          labelKey="name"
+        />
+      </Flex>
+      <pre style={{ margin: 0, background: '#f5f5f5', padding: 8, borderRadius: 4 }}>
+        {JSON.stringify(values, null, 2)}
+      </pre>
+    </Flex>
+  );
+};
+
 // 业务选择器示例（职能/行业/城市）
 const BusinessSelectExample = () => {
   const [values, setValues] = useState({});
@@ -554,11 +714,63 @@ const BusinessSelectExample = () => {
   );
 };
 
-render(<FilterFieldsExample />);
-render(<Divider />);
-render(<SuperSelectExample />);
-render(<Divider />);
-render(<BusinessSelectExample />);
+const FilterFieldsDemo = () => (
+  <Flex vertical>
+    <FilterFieldsExample />
+    <Divider />
+    <SuperSelectExample />
+    <Divider />
+    <SuperSelectVariantsExample />
+    <Divider />
+    <BusinessSelectExample />
+  </Flex>
+);
+
+render(<FilterFieldsDemo />);
+
+```
+
+- 搜索输入
+- 使用 SearchInput 实现顶部关键词搜索，输入停止 500ms 后自动提交筛选值，输入法组合输入完成后才开始触发搜索
+- _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 { SearchInput, FilterProvider, getFilterValue } = _ReactFilter;
+const { Flex, Button, Typography, message } = antd;
+const { useState } = React;
+
+const SearchInputExample = () => {
+  const [filterValue, setFilterValue] = useState([]);
+
+  const handleSearch = () => {
+    const params = getFilterValue(filterValue);
+    message.info(&#96;搜索参数: ${JSON.stringify(params)}&#96;);
+    console.log('搜索参数:', params);
+  };
+
+  return (
+    <Flex vertical gap={16}>
+      <Typography.Title level={4}>SearchInput 搜索输入</Typography.Title>
+      <Typography.Paragraph style={{ margin: 0 }}>
+        输入停止 500ms 后自动写入筛选值并触发搜索；中文等输入法组合输入期间不会触发搜索，确认文本后才开始计时。按回车或点击搜索按钮会立即提交。 清空后也会在 500ms 后移除该筛选条件。
+      </Typography.Paragraph>
+      <FilterProvider value={filterValue} onChange={setFilterValue}>
+        <Flex gap={8} align="center">
+          <SearchInput name="keyword" label="关键词" placeholder="请输入关键词" style={{ width: 320 }} allowClear />
+          <Button type="primary" onClick={handleSearch}>
+            查看搜索参数
+          </Button>
+        </Flex>
+      </FilterProvider>
+      <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(<SearchInputExample />);
 
 ```
 
@@ -759,36 +971,36 @@ render(<PopoverItemExample />);
 
 #### 属性
 
-| 属性           | 类型                                                   | 默认值    | 说明              |
-|--------------|------------------------------------------------------|--------|-----------------|
-| 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`                                             | -      | 自定义类名           |
+| 属性         | 类型                                                 | 默认值   | 说明                           |
+| ------------ | ---------------------------------------------------- | -------- | ------------------------------ |
+| 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}]` 数据格式转换                    |
+| 方法                                                        | 说明                                                                |
+| ----------------------------------------------------------- | ------------------------------------------------------------------- |
+| `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}]` 数据格式转换        |
 
 #### 使用示例
 
@@ -808,7 +1020,7 @@ const { InputFilterItem, NumberRangeFilterItem } = fields;
   ]}
   displayLine={1}
   extra={<Button type="primary">搜索</Button>}
-/>
+/>;
 ```
 
 ---
@@ -819,29 +1031,21 @@ const { InputFilterItem, NumberRangeFilterItem } = fields;
 
 #### 属性
 
-| 属性           | 类型                                                   | 默认值  | 说明       |
-|--------------|------------------------------------------------------|------|----------|
-| 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`                                             | -    | 自定义类名    |
+| 属性         | 类型                                                 | 默认值 | 说明             |
+| ------------ | ---------------------------------------------------- | ------ | ---------------- |
+| 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: '姓名' } }
-    ]
-  ]}
-/>
+<AdvancedFilter value={filterValue} onChange={setFilterValue} list={[[{ type: InputFilterItem, props: { name: 'name', label: '姓名' } }]]} />;
 ```
 
 ---
@@ -852,11 +1056,11 @@ import { AdvancedFilter, fields } from '@kne/react-filter';
 
 #### 属性
 
-| 属性          | 类型                                                   | 默认值 | 说明      |
-|-------------|------------------------------------------------------|-----|---------|
-| value       | `Array<{ name: string, label: string, value: any }>` | -   | 筛选值数组   |
-| onChange    | `(value: Array) => void`                             | -   | 筛选值变化回调 |
-| extraExpand | `ReactNode`                                          | -   | 额外展示内容  |
+| 属性        | 类型                                                 | 默认值 | 说明           |
+| ----------- | ---------------------------------------------------- | ------ | -------------- |
+| value       | `Array<{ name: string, label: string, value: any }>` | -      | 筛选值数组     |
+| onChange    | `(value: Array) => void`                             | -      | 筛选值变化回调 |
+| extraExpand | `ReactNode`                                          | -      | 额外展示内容   |
 
 ---
 
@@ -866,34 +1070,25 @@ import { AdvancedFilter, fields } from '@kne/react-filter';
 
 #### 属性
 
-| 属性               | 类型                                          | 默认值            | 说明        |
-|------------------|---------------------------------------------|----------------|-----------|
-| label            | `string`                                    | -              | 筛选项标签     |
-| value            | `{ label: string, value: any }`             | -              | 当前值       |
-| onChange         | `(value: object) => void`                   | -              | 值变化回调     |
-| onValidate       | `(value: object) => boolean`                | -              | 确认按钮校验函数  |
+| 属性             | 类型                                        | 默认值         | 说明               |
+| ---------------- | ------------------------------------------- | -------------- | ------------------ |
+| 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` | -              | 内容渲染函数    |
+| 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>
+<PopoverItem label="文本输入" value={inputValue} onChange={setInputValue}>
+  {({ value, onChange }) => <Input value={value?.value} onChange={e => onChange({ label: e.target.value, value: e.target.value })} />}
+</PopoverItem>;
 ```
 
 ---
@@ -904,12 +1099,12 @@ import { PopoverItem } from '@kne/react-filter';
 
 #### 属性
 
-| 属性       | 类型          | 默认值 | 说明         |
-|----------|-------------|-----|------------|
-| label    | `string`    | -   | 筛选项标签      |
-| open     | `boolean`   | -   | 是否展开状态     |
-| active   | `boolean`   | -   | 是否激活状态（有值） |
-| children | `ReactNode` | -   | 子元素        |
+| 属性     | 类型        | 默认值 | 说明                 |
+| -------- | ----------- | ------ | -------------------- |
+| label    | `string`    | -      | 筛选项标签           |
+| open     | `boolean`   | -      | 是否展开状态         |
+| active   | `boolean`   | -      | 是否激活状态（有值） |
+| children | `ReactNode` | -      | 子元素               |
 
 ---
 
@@ -919,13 +1114,14 @@ import { PopoverItem } from '@kne/react-filter';
 
 #### 属性
 
-| 属性          | 类型             | 默认值    | 说明      |
-|-------------|----------------|--------|---------|
-| list        | `Array<Array>` | `[]`   | 筛选项配置数组 |
-| displayLine | `number`       | `1`    | 默认展示行数  |
-| label       | `string`       | `'筛选'` | 标题      |
-| extra       | `ReactNode`    | -      | 额外操作区域  |
-| className   | `string`       | -      | 自定义类名   |
+| 属性        | 类型           | 默认值   | 说明           |
+| ----------- | -------------- | -------- | -------------- |
+| list                 | `Array`                  | `[]`      | 筛选项配置数组，默认支持单层数组，也兼容双层数组 |
+| displayLine          | `number`                 | `1`       | 双层数组模式下默认展示行数 |
+| visibleCountStrategy | `'asc' \| 'desc'`        | `'asc'`   | 单层数组模式下可见项计算策略，`asc` 从少往多累加，`desc` 从多往少递减 |
+| label                | `string`                 | `'筛选'`  | 标题 |
+| extra                | `ReactNode`              | -         | 额外操作区域 |
+| className            | `string`                 | -         | 自定义类名 |
 
 ---
 
@@ -935,12 +1131,12 @@ Filter 状态管理组件，用于自定义 Filter 结构。
 
 #### 属性
 
-| 属性           | 类型                                    | 默认值  | 说明       |
-|--------------|---------------------------------------|------|----------|
-| value        | `Array`                               | -    | 筛选值数组    |
-| defaultValue | `Array`                               | `[]` | 默认筛选值    |
-| onChange     | `(value: Array) => void`              | -    | 筛选值变化回调  |
-| children     | `ReactNode \| (context) => ReactNode` | -    | 子元素或渲染函数 |
+| 属性         | 类型                                  | 默认值 | 说明             |
+| ------------ | ------------------------------------- | ------ | ---------------- |
+| value        | `Array`                               | -      | 筛选值数组       |
+| defaultValue | `Array`                               | `[]`   | 默认筛选值       |
+| onChange     | `(value: Array) => void`              | -      | 筛选值变化回调   |
+| children     | `ReactNode \| (context) => ReactNode` | -      | 子元素或渲染函数 |
 
 ---
 
@@ -954,7 +1150,7 @@ Filter 状态管理组件，用于自定义 Filter 结构。
 import { withFilterValue } from '@kne/react-filter';
 
 const MyFilterItem = withFilterValue(({ name, label, value, onChange, ...props }) => {
-  return <Component value={value} onChange={onChange}/>;
+  return <Component value={value} onChange={onChange} />;
 });
 ```
 
@@ -976,45 +1172,45 @@ const MyFieldItem = withFieldItem(MyComponent);
 
 弹出层形式的输入框筛选组件。
 
-| 属性          | 类型                   | 默认值 | 说明     |
-|-------------|----------------------|-----|--------|
-| name        | `string`             | -   | 字段名称   |
-| label       | `string`             | -   | 标签     |
-| placeholder | `string`             | -   | 占位符    |
-| onValidate  | `(value) => boolean` | -   | 确认校验函数 |
+| 属性        | 类型                 | 默认值 | 说明         |
+| ----------- | -------------------- | ------ | ------------ |
+| name        | `string`             | -      | 字段名称     |
+| label       | `string`             | -      | 标签         |
+| placeholder | `string`             | -      | 占位符       |
+| onValidate  | `(value) => boolean` | -      | 确认校验函数 |
 
 #### NumberRangeFilterItem 数字区间筛选
 
 数字区间输入筛选组件。
 
-| 属性          | 类型       | 默认值 | 说明   |
-|-------------|----------|-----|------|
-| name        | `string` | -   | 字段名称 |
-| label       | `string` | -   | 标签   |
-| unit        | `string` | -   | 单位   |
-| min         | `number` | -   | 最小值  |
-| max         | `number` | -   | 最大值  |
-| placeholder | `string` | -   | 占位符  |
+| 属性        | 类型     | 默认值 | 说明     |
+| ----------- | -------- | ------ | -------- |
+| name        | `string` | -      | 字段名称 |
+| label       | `string` | -      | 标签     |
+| unit        | `string` | -      | 单位     |
+| min         | `number` | -      | 最小值   |
+| max         | `number` | -      | 最大值   |
+| placeholder | `string` | -      | 占位符   |
 
 #### DatePickerFilterItem 日期筛选
 
 日期选择筛选组件。
 
-| 属性     | 类型                                                   | 默认值            | 说明    |
-|--------|------------------------------------------------------|----------------|-------|
-| name   | `string`                                             | -              | 字段名称  |
-| label  | `string`                                             | -              | 标签    |
+| 属性   | 类型                                                 | 默认值         | 说明       |
+| ------ | ---------------------------------------------------- | -------------- | ---------- |
+| name   | `string`                                             | -              | 字段名称   |
+| label  | `string`                                             | -              | 标签       |
 | picker | `'date' \| 'week' \| 'month' \| 'quarter' \| 'year'` | `'date'`       | 选择器类型 |
-| format | `string`                                             | `'YYYY-MM-DD'` | 日期格式  |
+| format | `string`                                             | `'YYYY-MM-DD'` | 日期格式   |
 
 #### DateRangePickerFilterItem 日期范围筛选
 
 日期范围选择筛选组件。
 
-| 属性     | 类型                                  | 默认值            | 说明   |
-|--------|-------------------------------------|----------------|------|
+| 属性   | 类型                                | 默认值         | 说明     |
+| ------ | ----------------------------------- | -------------- | -------- |
 | name   | `string`                            | -              | 字段名称 |
-| label  | `string`                            | -              | 标签   |
+| label  | `string`                            | -              | 标签     |
 | format | `string`                            | `'YYYY-MM-DD'` | 日期格式 |
 | header | `ReactNode \| (props) => ReactNode` | -              | 头部内容 |
 
@@ -1022,24 +1218,24 @@ const MyFieldItem = withFieldItem(MyComponent);
 
 支持按日/周/月切换的日期范围选择筛选组件。
 
-| 属性     | 类型       | 默认值            | 说明   |
-|--------|----------|----------------|------|
+| 属性   | 类型     | 默认值         | 说明     |
+| ------ | -------- | -------------- | -------- |
 | name   | `string` | -              | 字段名称 |
-| label  | `string` | -              | 标签   |
+| label  | `string` | -              | 标签     |
 | format | `string` | `'YYYY-MM-DD'` | 日期格式 |
 
 #### SuperSelectFilterItem 通用选择器筛选
 
 基于 `@kne/super-select` 的通用选择器筛选项，支持单选/多选、搜索、全选等功能。
 
-| 属性               | 类型                          | 默认值     | 说明       |
-|------------------|-----------------------------|---------|----------|
-| name             | `string`                    | -       | 字段名称     |
-| label            | `string`                    | -       | 标签       |
-| options          | `Array<{ value, label }>`   | -       | 选项数据     |
-| single           | `boolean`                   | `false` | 是否单选     |
-| allowSelectedAll | `boolean`                   | `false` | 是否支持全选   |
-| maxLength        | `number`                    | -       | 最多可选数量   |
+| 属性             | 类型                      | 默认值  | 说明         |
+| ---------------- | ------------------------- | ------- | ------------ |
+| name             | `string`                  | -       | 字段名称     |
+| label            | `string`                  | -       | 标签         |
+| options          | `Array<{ value, label }>` | -       | 选项数据     |
+| single           | `boolean`                 | `false` | 是否单选     |
+| allowSelectedAll | `boolean`                 | `false` | 是否支持全选 |
+| maxLength        | `number`                  | -       | 最多可选数量 |
 
 **使用示例：**
 
@@ -1068,16 +1264,65 @@ import { SuperSelectFilterItem } from '@kne/react-filter';
 
 > 注意：需要安装 `@kne/super-select` 依赖。
 
+#### SelectTableListFilterItem 表格选择器筛选
+
+基于 `@kne/super-select` 的 `SelectTableList` 组件，适用于需要展示多列数据的筛选场景。
+
+| 属性      | 类型       | 默认值  | 说明         |
+| --------- | ---------- | ------- | ------------ |
+| name      | `string`   | -       | 字段名称     |
+| label     | `string`   | -       | 标签         |
+| options   | `Array`    | -       | 选项数据     |
+| columns   | `Array`    | -       | 表格列配置   |
+| valueKey  | `string`   | `'id'`  | 值字段名     |
+| labelKey  | `string`   | `'name'`| 标签字段名   |
+| single    | `boolean`  | `false` | 是否单选     |
+| maxLength | `number`   | -       | 最多可选数量 |
+
+> 注意：需要安装 `@kne/super-select` 依赖。
+
+#### SelectTreeFilterItem 树形选择器筛选
+
+基于 `@kne/super-select` 的 `SelectTree` 组件，适用于组织架构、分类等层级数据筛选。
+
+| 属性      | 类型       | 默认值  | 说明         |
+| --------- | ---------- | ------- | ------------ |
+| name      | `string`   | -       | 字段名称     |
+| label     | `string`   | -       | 标签         |
+| options   | `Array`    | -       | 树形数据（含 `parentId`） |
+| valueKey  | `string`   | `'id'`  | 值字段名     |
+| labelKey  | `string`   | `'name'`| 标签字段名   |
+| single    | `boolean`  | `false` | 是否单选     |
+| maxLength | `number`   | -       | 最多可选数量 |
+
+> 注意：需要安装 `@kne/super-select` 依赖。
+
+#### SelectCascaderFilterItem 级联选择器筛选
+
+基于 `@kne/super-select` 的 `SelectCascader` 组件，支持多列菜单展示、父子关联选择、搜索过滤。
+
+| 属性      | 类型       | 默认值  | 说明         |
+| --------- | ---------- | ------- | ------------ |
+| name      | `string`   | -       | 字段名称     |
+| label     | `string`   | -       | 标签         |
+| options   | `Array`    | -       | 级联数据（含 `children`） |
+| valueKey  | `string`   | `'id'`  | 值字段名     |
+| labelKey  | `string`   | `'name'`| 标签字段名   |
+| single    | `boolean`  | `false` | 是否单选     |
+| maxLength | `number`   | -       | 最多可选数量 |
+
+> 注意：需要安装 `@kne/super-select` 依赖。
+
 #### SelectFunctionFilterItem 职能筛选
 
 基于 `@kne/super-select-plus` 的职能选择器筛选项，支持多级职能数据选择、拼音搜索。
 
-| 属性        | 类型        | 默认值     | 说明       |
-|-----------|-----------|---------|----------|
+| 属性      | 类型      | 默认值  | 说明         |
+| --------- | --------- | ------- | ------------ |
 | name      | `string`  | -       | 字段名称     |
-| label     | `string`  | -       | 标签       |
+| label     | `string`  | -       | 标签         |
 | single    | `boolean` | `false` | 是否单选     |
-| maxLength | `number`  | -       | 最多可选数量   |
+| maxLength | `number`  | -       | 最多可选数量 |
 
 > 注意：需要安装 `@kne/super-select-plus` 依赖。
 
@@ -1085,12 +1330,12 @@ import { SuperSelectFilterItem } from '@kne/react-filter';
 
 基于 `@kne/super-select-plus` 的行业选择器筛选项，支持多级行业数据选择、拼音搜索。
 
-| 属性        | 类型        | 默认值     | 说明       |
-|-----------|-----------|---------|----------|
+| 属性      | 类型      | 默认值  | 说明         |
+| --------- | --------- | ------- | ------------ |
 | name      | `string`  | -       | 字段名称     |
-| label     | `string`  | -       | 标签       |
+| label     | `string`  | -       | 标签         |
 | single    | `boolean` | `false` | 是否单选     |
-| maxLength | `number`  | -       | 最多可选数量   |
+| maxLength | `number`  | -       | 最多可选数量 |
 
 > 注意：需要安装 `@kne/super-select-plus` 依赖。
 
@@ -1098,12 +1343,12 @@ import { SuperSelectFilterItem } from '@kne/react-filter';
 
 基于 `@kne/super-select-plus` 的城市选择器筛选项，支持国内外城市搜索选择。
 
-| 属性        | 类型        | 默认值     | 说明       |
-|-----------|-----------|---------|----------|
+| 属性      | 类型      | 默认值  | 说明         |
+| --------- | --------- | ------- | ------------ |
 | name      | `string`  | -       | 字段名称     |
-| label     | `string`  | -       | 标签       |
+| label     | `string`  | -       | 标签         |
 | single    | `boolean` | `false` | 是否单选     |
-| maxLength | `number`  | -       | 最多可选数量   |
+| maxLength | `number`  | -       | 最多可选数量 |
 
 > 注意：需要安装 `@kne/super-select-plus` 依赖。
 
@@ -1111,10 +1356,10 @@ import { SuperSelectFilterItem } from '@kne/react-filter';
 
 城市选择器的高级筛选版本，用于 `AdvancedFilter` 组件的 `list` 配置中。展示热门城市标签，支持搜索选择其他城市。
 
-| 属性        | 类型        | 默认值     | 说明         |
-|-----------|-----------|---------|------------|
-| single    | `boolean` | `false` | 是否单选       |
-| maxLength | `number`  | `5`     | 最多可选数量     |
+| 属性      | 类型      | 默认值  | 说明         |
+| --------- | --------- | ------- | ------------ |
+| single    | `boolean` | `false` | 是否单选     |
+| maxLength | `number`  | `5`     | 最多可选数量 |
 
 **在高级筛选中使用：**
 
@@ -1122,11 +1367,7 @@ import { SuperSelectFilterItem } from '@kne/react-filter';
 import { AdvancedFilter } from '@kne/react-filter';
 import { CityFilterItem } from './AdvancedFilter/fields';
 
-<AdvancedFilter
-  list={[
-    [{ type: CityFilterItem, props: { label: '城市', single: true } }]
-  ]}
-/>
+<AdvancedFilter list={[[{ type: CityFilterItem, props: { label: '城市', single: true } }]]} />;
 ```
 
 ---
@@ -1135,20 +1376,20 @@ import { CityFilterItem } from './AdvancedFilter/fields';
 
 支持按日/周/月切换的日期范围选择器基础组件。
 
-| 属性              | 类型                                                         | 默认值                             | 说明       |
-|-----------------|------------------------------------------------------------|---------------------------------|----------|
-| value           | `{ type: string, value: [Date, Date] }`                    | -                               | 当前值      |
-| defaultValue    | `{ type: string, value: [Date, Date] }`                    | `{ type: 'date', value: null }` | 默认值      |
-| onChange        | `(value: object) => void`                                  | -                               | 值变化回调    |
+| 属性            | 类型                                                       | 默认值                          | 说明             |
+| --------------- | ---------------------------------------------------------- | ------------------------------- | ---------------- |
+| 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] }>` | -                               | 自定义快捷选项  |
+| shortcutOptions | `Array<{ label: string, getValue: () => [Dayjs, Dayjs] }>` | -                               | 自定义快捷选项   |
 
 **value 结构：**
 
 ```typescript
 interface TypeDateRangeValue {
-  type: 'date' | 'week' | 'month';  // 日期类型
-  value: [Date, Date] | null;       // 日期范围 [开始时间, 结束时间]
+  type: 'date' | 'week' | 'month'; // 日期类型
+  value: [Date, Date] | null; // 日期范围 [开始时间, 结束时间]
 }
 ```
 
@@ -1176,20 +1417,38 @@ import { TypeDateRangePickerField } from '@kne/react-filter';
       getValue: () => [dayjs().subtract(1, 'month').startOf('day'), dayjs().endOf('day')]
     }
   ]}
-/>
+/>;
 ```
 
 ---
 
 ### SearchInput 搜索输入
 
-搜索输入组件。
+搜索输入组件，适合放在列表顶部做关键词搜索。输入过程中维护本地输入值，停止输入 500ms 后自动提交筛选值；中文等输入法组合输入期间不会触发搜索，确认文本后才开始计时。按回车或点击搜索按钮会立即提交。清空后搜索会提交 `null`，用于移除该筛选条件。
+
+| 属性        | 类型                               | 默认值 | 说明                                 |
+| ----------- | ---------------------------------- | ------ | ------------------------------------ |
+| name        | `string`                           | -      | 字段名称，用于写入筛选值             |
+| label       | `string`                           | -      | 标签，用于展示已选筛选条件           |
+| value       | `{ label: string, value: string }` | -      | 当前搜索值                           |
+| onChange    | `(value: object \| null) => void`  | -      | 搜索提交回调，清空搜索时返回 `null`  |
+| placeholder | `string`                           | -      | 占位符                               |
+| searchDelay | `number`                           | `500`  | 自动提交搜索的防抖等待时间，单位毫秒 |
+
+#### 使用示例
+
+```javascript
+import { SearchInput, FilterProvider, getFilterValue } from '@kne/react-filter';
+
+const [filterValue, setFilterValue] = useState([]);
+
+<FilterProvider value={filterValue} onChange={setFilterValue}>
+  <SearchInput name="keyword" label="关键词" placeholder="请输入关键词" searchDelay={500} allowClear />
+</FilterProvider>;
 
-| 属性          | 类型       | 默认值 | 说明   |
-|-------------|----------|-----|------|
-| name        | `string` | -   | 字段名称 |
-| label       | `string` | -   | 标签   |
-| placeholder | `string` | -   | 占位符  |
+const params = getFilterValue(filterValue);
+// { keyword: 'React' }
+```
 
 ---
 
@@ -1219,15 +1478,20 @@ const params = getFilterValue(filterValue);
 
 ```typescript
 interface FilterValueItem {
-  name: string;      // 字段名称
-  label: string;     // 字段标签（用于展示）
-  value: {           // 单个值
-    label: string;   // 显示文本
-    value: any;      // 实际值
-  } | Array<{        // 或多个值
-    label: string;
-    value: any;
-  }> | null;         // 或空值
+  name: string; // 字段名称
+  label: string; // 字段标签（用于展示）
+  value:
+    | {
+        // 单个值
+        label: string; // 显示文本
+        value: any; // 实际值
+      }
+    | Array<{
+        // 或多个值
+        label: string;
+        value: any;
+      }>
+    | null; // 或空值
 }
 ```
 
@@ -1239,12 +1503,13 @@ interface FilterValueItem {
 
 将筛选值数组序列化为 URLSearchParams，保留 label 信息以便反序列化还原完整筛选状态。
 
-| 参数             | 类型             | 默认值             | 说明                       |
-|----------------|----------------|-----------------|--------------------------|
-| filterValue    | `Array`        | -               | 筛选值数组                    |
-| options.prefix | `string`       | `'filterParams'` | URL 参数前缀，设为空字符串则不加前缀     |
+| 参数           | 类型     | 默认值           | 说明                                 |
+| -------------- | -------- | ---------------- | ------------------------------------ |
+| filterValue    | `Array`  | -                | 筛选值数组                           |
+| options.prefix | `string` | `'filterParams'` | URL 参数前缀，设为空字符串则不加前缀 |
 
 **序列化格式**：
+
 - 单值且 `label === value`：`prefix[name]=value`（如输入框）
 - 单值且 `label !== value`：`prefix[name]=label:value`
 - 多值：`prefix[name]=label1:value1,label2:value2`
@@ -1256,7 +1521,14 @@ 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' }] },
+  {
+    name: 'city',
+    label: '城市',
+    value: [
+      { label: '上海', value: '010' },
+      { label: '北京', value: '020' }
+    ]
+  }
 ]);
 // params.toString() => 'filterParams[keyword]=测试&filterParams[city]=上海:010,北京:020'
 
@@ -1275,11 +1547,12 @@ filterToUrlParams(filterValue, { prefix: '' });
 
 解析 URL 参数中的单个筛选值项，反序列化为 `{ label, value }` 对象。
 
-| 参数  | 类型       | 说明            |
-|-----|----------|---------------|
-| str | `string` | URL 参数中的原始字符串 |
+| 参数 | 类型     | 说明                   |
+| ---- | -------- | ---------------------- |
+| str  | `string` | URL 参数中的原始字符串 |
 
 **解析规则**：
+
 - 无冒号：label 和 value 相同，如 `"测试"` → `{ label: '测试', value: '测试' }`
 - 有冒号：冒号前为 label，冒号后为 value，如 `"启用:active"` → `{ label: '启用', value: 'active' }`
 
@@ -1299,12 +1572,12 @@ parseFilterEntry('启用:active');
 
 从 URL 参数中读取筛选值项，返回单选 `{ label, value }` 或多选数组。
 
-| 参数              | 类型                | 默认值             | 说明               |
-|-----------------|-------------------|-----------------|------------------|
-| searchParams    | `URLSearchParams` | -               | URL 参数对象         |
-| key             | `string`          | -               | 参数名（不含前缀）        |
-| options.multi   | `boolean`         | `false`         | 是否多选             |
-| options.prefix  | `string`          | `'filterParams'` | URL 参数前缀         |
+| 参数           | 类型              | 默认值           | 说明               |
+| -------------- | ----------------- | ---------------- | ------------------ |
+| searchParams   | `URLSearchParams` | -                | URL 参数对象       |
+| key            | `string`          | -                | 参数名（不含前缀） |
+| options.multi  | `boolean`         | `false`          | 是否多选           |
+| options.prefix | `string`          | `'filterParams'` | URL 参数前缀       |
 
 ```javascript
 import { takeFilterEntry } from '@kne/react-filter';
@@ -1323,10 +1596,10 @@ takeFilterEntry(searchParams, 'keyword', { prefix: '' });
 
 创建 URL 筛选参数读取器，自动追踪已消费的参数 key。配合 `useUrlFilter` 使用，readUrlParams 返回的 consumedKeys 可被自动清除。
 
-| 参数              | 类型                | 默认值             | 说明       |
-|-----------------|-------------------|-----------------|----------|
-| searchParams    | `URLSearchParams` | -               | URL 参数对象 |
-| options.prefix  | `string`          | `'filterParams'` | URL 参数前缀 |
+| 参数           | 类型              | 默认值           | 说明         |
+| -------------- | ----------------- | ---------------- | ------------ |
+| searchParams   | `URLSearchParams` | -                | URL 参数对象 |
+| options.prefix | `string`          | `'filterParams'` | URL 参数前缀 |
 
 **返回值**：`{ takeFilterEntry, getConsumedKeys }`
 
@@ -1347,10 +1620,10 @@ const city = takeFilterEntry('city', { multi: true });
 
 > 需要 React Router 环境支持 `useSearchParams`。
 
-| 参数                  | 类型         | 说明                                           |
-|---------------------|------------|----------------------------------------------|
+| 参数                  | 类型       | 说明                                                      |
+| --------------------- | ---------- | --------------------------------------------------------- |
 | options.readUrlParams | `Function` | 读取 URL 参数并返回 `{ consumedKeys: string[], ...data }` |
-| options.buildFilter   | `Function` | 接收 readUrlParams 的返回值，构建初始 filter 数组          |
+| options.buildFilter   | `Function` | 接收 readUrlParams 的返回值，构建初始 filter 数组         |
 
 **返回值**：`[filter, setFilter]`
 
@@ -1358,15 +1631,12 @@ const city = takeFilterEntry('city', { multi: true });
 import { useUrlFilter, createUrlParamsReader } from '@kne/react-filter';
 
 const [filter, setFilter] = useUrlFilter({
-  readUrlParams: (searchParams) => {
+  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 } }] : [])
-  ]
+  buildFilter: ({ orgId }) => [{ name: 'status', value: { label: '开启', value: 'open' } }, ...(orgId ? [{ name: 'tenantOrgId', value: { label: orgId, value: orgId } }] : [])]
 });
 ```
 
@@ -1376,11 +1646,12 @@ const [filter, setFilter] = useUrlFilter({
 
 `useUrlFilter` 的简化版，基于 `filterParams[key]` 格式自动解析 URL 参数，支持单选和多选。
 
-| 参数      | 类型                     | 说明                             |
-|---------|------------------------|--------------------------------|
-| mapping | `string[] \| Object`   | URL 参数映射，支持数组、对象两种格式           |
+| 参数    | 类型                 | 说明                                 |
+| ------- | -------------------- | ------------------------------------ |
+| mapping | `string[] \| Object` | URL 参数映射，支持数组、对象两种格式 |
 
 **数组形式（默认单选）：**
+
 ```javascript
 import { useUrlFilterValue } from '@kne/react-filter';
 
@@ -1393,11 +1664,13 @@ const [filter, setFilter] = useUrlFilterValue(['keyword', 'status']);
 ```
 
 **对象形式（多选 + 自定义）：**
+
 ```javascript
 const [filter, setFilter] = useUrlFilterValue({
-  keyword: true,                        // 单选
-  city: { multi: true },               // 多选
-  status: (parsed) => {                // 自定义转换
+  keyword: true, // 单选
+  city: { multi: true }, // 多选
+  status: parsed => {
+    // 自定义转换
     return parsed ? { name: 'status', value: parsed } : null;
   }
 });
@@ -1410,11 +1683,12 @@ const [filter, setFilter] = useUrlFilterValue({
 
 创建通用 URL 参数读取器，自动追踪已消费的参数 key。
 
-| 参数           | 类型                | 说明       |
-|--------------|-------------------|----------|
+| 参数         | 类型              | 说明         |
+| ------------ | ----------------- | ------------ |
 | searchParams | `URLSearchParams` | URL 参数对象 |
 
 **返回值**：`{ take, getConsumedKeys }`
+
 - `take(key)` - 读取参数值，记录已消费
 - `getConsumedKeys()` - 返回已消费的 key 列表
 
@@ -1433,10 +1707,10 @@ const orgName = take('orgName');
 
 从 URL 参数中移除已消费的 key，返回新的 URLSearchParams 或 null（无变化时）。
 
-| 参数           | 类型                | 说明                |
-|--------------|-------------------|-------------------|
-| searchParams | `URLSearchParams` | 当前 URL 参数         |
-| consumedKeys | `string[]`        | 需要移除的 key 列表      |
+| 参数         | 类型              | 说明                |
+| ------------ | ----------------- | ------------------- |
+| searchParams | `URLSearchParams` | 当前 URL 参数       |
+| consumedKeys | `string[]`        | 需要移除的 key 列表 |
 
 **返回值**：`URLSearchParams | null`
 
@@ -1459,19 +1733,19 @@ if (nextParams) {
 
 单选拦截器：`{id, name}` ↔ `{label, value}`。
 
-| 属性      | 类型         | 说明                                    |
-|---------|------------|---------------------------------------|
-| input   | `Function` | `{id, name}` → `{label, value}` 的转换   |
-| output  | `Function` | `{label, value}` → `{id, name}` 的转换   |
+| 属性   | 类型       | 说明                                   |
+| ------ | ---------- | -------------------------------------- |
+| 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}]` 的转换    |
+| 属性   | 类型       | 说明                                       |
+| ------ | ---------- | ------------------------------------------ |
+| input  | `Function` | `[{id, name}]` → `[{label, value}]` 的转换 |
+| output | `Function` | `[{label, value}]` → `[{id, name}]` 的转换 |
 
 #### filterInterceptors
 
@@ -1482,7 +1756,7 @@ import { filterInterceptors, singleSelectInterceptor, multiSelectInterceptor } f
 
 // 两种引用方式等价
 filterInterceptors.single === singleSelectInterceptor; // true
-filterInterceptors.multi === multiSelectInterceptor;   // true
+filterInterceptors.multi === multiSelectInterceptor; // true
 ```
 
 **使用示例：**
@@ -1515,8 +1789,8 @@ import { filterInterceptors } from '@kne/react-filter';
 
 从筛选值中提取原始值数组。支持原始值、`{ value }` 对象、`{ id }` 对象以及它们的数组。
 
-| 参数    | 类型    | 说明          |
-|-------|-------|-------------|
+| 参数  | 类型  | 说明                 |
+| ----- | ----- | -------------------- |
 | value | `any` | 筛选值，支持多种格式 |
 
 ```javascript
@@ -1536,17 +1810,17 @@ pickSelectValues(null);
 
 声明式创建 mapFilterValue 函数。`Filter.getFilterValue` 默认只读取 `{ value }`，而 SuperSelectFilterItem 等组件使用 `{ id, name }` 格式，需要额外处理。此工具通过声明字段映射规则，自动生成转换函数。
 
-| 参数           | 类型       | 说明                |
-|--------------|----------|-------------------|
-| fieldMappers | `Object` | 字段名到映射规则的映射       |
+| 参数         | 类型     | 说明                   |
+| ------------ | -------- | ---------------------- |
+| fieldMappers | `Object` | 字段名到映射规则的映射 |
 
 **映射规则类型：**
 
-| 规则        | 说明                                     |
-|-----------|----------------------------------------|
-| `'string'` | 确保值为字符串类型                              |
-| `'multi'`  | 多选，从 filter entry 提取值数组                 |
-| `'single'` | 单选，从 filter entry 提取第一个值                |
+| 规则       | 说明                                                    |
+| ---------- | ------------------------------------------------------- |
+| `'string'` | 确保值为字符串类型                                      |
+| `'multi'`  | 多选，从 filter entry 提取值数组                        |
+| `'single'` | 单选，从 filter entry 提取第一个值                      |
 | `Function` | 自定义转换，接收 `(rawValue, { entry, filter, value })` |
 
 ```javascript
@@ -1556,7 +1830,7 @@ const mapFilterValue = createFilterValueMapper({
   id: 'string',
   roles: 'multi',
   tenantOrgId: 'single',
-  status: (rawValue) => normalizeStatus(rawValue)
+  status: rawValue => normalizeStatus(rawValue)
 });
 
 const filterValue = mapFilterValue(filter, Filter.getFilterValue);