@rainbow-oh/yee-c 0.12.2 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-oh/yee-c",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "yee basic components",
   "keywords": [
     "react",

package/src/Field/demo/standalone.tsx

@@ -0,0 +1,30 @@
+import { Field, Input, TextArea } from '@rainbow-oh/yee-c';
+import React, { useState } from 'react';
+
+export default () => {
+  const [name, setName] = useState('');
+  const [remark, setRemark] = useState('');
+
+  return (
+    <div style={{ maxWidth: 400 }}>
+      <Field label="Name" required>
+        <Input
+          value={name}
+          onChange={(v: string) => setName(v)}
+          placeholder="Standalone controlled Input"
+        />
+      </Field>
+      <Field label="Remark">
+        <TextArea
+          value={remark}
+          onChange={(v: string) => setRemark(v)}
+          placeholder="Standalone controlled TextArea"
+          rows={3}
+        />
+      </Field>
+      <Field>
+        <Input placeholder="Field without label" />
+      </Field>
+    </div>
+  );
+};

package/src/Field/field.tsx

@@ -28,7 +28,7 @@ const Field: FC<FieldProps> = (props) => {
 
   const [, forceUpdate] = useReducer((x) => x + 1, 0);
 
-  const { form } = useVirtualField(formName, name, {
+  const { form } = useVirtualField(formName ?? '', name ?? '', {
     props,
     onStoreChange: forceUpdate,
   });
@@ -49,20 +49,33 @@ const Field: FC<FieldProps> = (props) => {
   };
 
   const getControlled = (children: React.ReactElement) => {
-    const mergedDisabled =
-      disabled || (children as React.ReactElement<any>).props.disabled;
+    const childProps = (children as React.ReactElement<any>).props;
+
+    // Pure layout mode (no form): children keep their own value/onChange.
+    // Only a Field-level disabled is merged down.
+    // Pure layout mode (no form or no field name): children keep their own
+    // value/onChange. Only a Field-level disabled is merged down.
+    if (!form || name === undefined) {
+      if (disabled === undefined) return children;
+      return React.cloneElement(children as React.ReactElement<any>, {
+        disabled: disabled || childProps.disabled,
+      });
+    }
+
+    const mergedDisabled = disabled || childProps.disabled;
+    const fieldName = name;
 
     const attr = {
-      value: getFieldValue?.(name),
+      value: getFieldValue?.(fieldName),
       name: formName,
-      id: name,
+      id: fieldName,
       disabled: mergedDisabled,
       onChange: (value: unknown, ...rest: Array<unknown>) => {
         const callbacks = getCallbacks?.();
         let _value = value;
         const fieldsValue = getFieldsValue?.();
         const feedback = callbacks?.onValuesBeforeChange?.(
-          { [name]: _value },
+          { [fieldName]: _value },
           fieldsValue,
         );
 
@@ -70,20 +83,20 @@ const Field: FC<FieldProps> = (props) => {
           _value = feedback;
         }
 
-        setFieldsValue?.({ [name]: _value }, 'onChange');
+        setFieldsValue?.({ [fieldName]: _value }, 'onChange');
 
         // Call child component's onChange
         if ((children.props as any)?.onChange) {
           (children.props as any).onChange(_value, ...rest);
         }
 
-        callbacks?.['onValuesChange']?.({ [name]: _value }, fieldsValue);
+        callbacks?.['onValuesChange']?.({ [fieldName]: _value }, fieldsValue);
 
         forceUpdate();
       },
       onBlur: (event: unknown) => {
         // Fire-and-forget async validation; store notifies onStoreChange on completion.
-        void validateField?.(name, 'onBlur');
+        void validateField?.(fieldName, 'onBlur');
 
         // Call child component's onBlur
         if ((children.props as any).onBlur) {
@@ -95,7 +108,8 @@ const Field: FC<FieldProps> = (props) => {
     return React.cloneElement(children, attr);
   };
 
-  const validate = getFieldValidate?.(name);
+  const validate =
+    name !== undefined ? getFieldValidate?.(name) : undefined;
 
   return (
     <div
@@ -109,18 +123,20 @@ const Field: FC<FieldProps> = (props) => {
       )}
       style={style}
     >
-      <label
-        className={clsx(
-          `${prefixCls}-label`,
-          {
-            [`${prefixCls}-required`]: isRequired(),
-          },
-          classNames?.label,
-        )}
-        style={styles?.label}
-      >
-        {label}
-      </label>
+      {label ? (
+        <label
+          className={clsx(
+            `${prefixCls}-label`,
+            {
+              [`${prefixCls}-required`]: isRequired(),
+            },
+            classNames?.label,
+          )}
+          style={styles?.label}
+        >
+          {label}
+        </label>
+      ) : null}
       <div
         className={clsx(`${prefixCls}-content`, classNames?.content)}
         style={styles?.content}

package/src/Field/index.en-US.md

@@ -10,11 +10,15 @@ toc: 'content'
 
 # Field
 
-A standalone form field component that works without a `<Form>` wrapper. Uses `useVirtualForm` to create a virtual form for value management and validation.
+A standalone form field component that works without a `<Form>` wrapper. Two usage modes:
+
+- **Virtual form mode**: create a virtual form with `useVirtualForm`; Field manages value and validation (pass `formName` + `name`)
+- **Pure layout mode**: omit `formName` (or the form is not registered); Field only renders the label layout and required asterisk, while `value`/`onChange` pass straight through to the child — state is managed by the consumer
 
 ## Code Demo
 
 <code src="./demo/basic.tsx" title="Basic" description="Create a virtual form with useVirtualForm and bind Field to Input"></code>
+<code src="./demo/standalone.tsx" title="Pure Layout" description="Without formName, state is managed by the consumer and Field only handles label layout"></code>
 <code src="./demo/validation.tsx" title="Validation" description="required, minLength, regexp, validator rules and validateTrigger"></code>
 <code src="./demo/layout.tsx" title="Layout & Style" description="Vertical/horizontal layout and semantic style customization"></code>
 <code src="./demo/disabled.tsx" title="Disabled" description="Disable the entire field via the disabled prop"></code>
@@ -25,14 +29,14 @@ A standalone form field component that works without a `<Form>` wrapper. Uses `u
 
 | Property | Type | Description | Default |
 | --- | --- | --- | --- |
-| formName | `string` | Virtual form name (required) | - |
-| name | `string` | Field name (required) | - |
+| formName | `string` | Virtual form name; omit for pure layout mode | - |
+| name | `string` | Field name (required in virtual form mode) | - |
 | label | `React.ReactNode` | Field label | - |
 | children | `React.ReactElement` | Form control (must be a single React element) | - |
 | rules | `Rule[]` | Validation rules | - |
 | required | `boolean` | Whether the field is required (shows asterisk) | `false` |
 | layout | `'vertical' \| 'horizontal'` | Layout direction | `'vertical'` |
-| disabled | `boolean` | Whether the field is disabled | `false` |
+| disabled | `boolean` | Whether the field is disabled (merged onto the child, also works in pure layout mode) | `false` |
 | prefixCls | `string` | Class name prefix | `'yee-field'` |
 | className | `string` | Root element class name | - |
 | style | `React.CSSProperties` | Root element style | - |

package/src/Field/index.zh-CN.md

@@ -10,11 +10,15 @@ toc: 'content'
 
 # Field 字段
 
-脱离 `<Form>` 组件独立使用的表单字段组件，通过 `useVirtualForm` 创建虚拟表单来实现值管理和校验。
+脱离 `<Form>` 组件独立使用的表单字段组件。两种用法：
+
+- **虚拟表单模式**：通过 `useVirtualForm` 创建虚拟表单，Field 负责值管理和校验（传 `formName` + `name`）
+- **纯布局模式**：不传 `formName`（或该表单未注册），Field 只负责 label 布局与必填星号，`value`/`onChange` 由使用者自己控制并直接透传给子控件
 
 ## 代码演示
 
 <code src="./demo/basic.tsx" title="基础用法" description="使用 useVirtualForm 创建虚拟表单，配合 Field 绑定 Input"></code>
+<code src="./demo/standalone.tsx" title="纯布局模式" description="不传 formName，受控状态自己管理，Field 只负责标签布局"></code>
 <code src="./demo/validation.tsx" title="校验规则" description="required、minLength、regexp、validator 等校验规则，以及 validateTrigger 控制触发时机"></code>
 <code src="./demo/layout.tsx" title="布局与样式" description="垂直/水平布局、语义化样式定制"></code>
 <code src="./demo/disabled.tsx" title="禁用状态" description="通过 disabled 属性禁用整个字段"></code>
@@ -25,14 +29,14 @@ toc: 'content'
 
 | 属性名 | 类型 | 描述 | 默认值 |
 | --- | --- | --- | --- |
-| formName | `string` | 所属虚拟表单名称（必填） | - |
-| name | `string` | 字段名称（必填） | - |
+| formName | `string` | 所属虚拟表单名称；不传时 Field 为纯布局模式 | - |
+| name | `string` | 字段名称（虚拟表单模式下必填） | - |
 | label | `React.ReactNode` | 字段标签 | - |
 | children | `React.ReactElement` | 表单控件（必须是单个 React 元素） | - |
 | rules | `Rule[]` | 校验规则 | - |
 | required | `boolean` | 是否必填（显示星号标记） | `false` |
 | layout | `'vertical' \| 'horizontal'` | 布局方式 | `'vertical'` |
-| disabled | `boolean` | 是否禁用 | `false` |
+| disabled | `boolean` | 是否禁用（会合并到子控件上，纯布局模式下同样生效） | `false` |
 | prefixCls | `string` | 类名前缀 | `'yee-field'` |
 | className | `string` | 根元素类名 | - |
 | style | `React.CSSProperties` | 根元素样式 | - |

package/src/Field/interface.ts

@@ -28,13 +28,16 @@ export interface FieldProps {
    */
   label?: React.ReactNode;
   /**
-   * Field name
+   * Field name (required only when used with a registered virtual form)
    */
-  name: string;
+  name?: string;
   /**
-   * Name of the parent form
+   * Name of the parent form.
+   * When omitted (or no form is registered under this name), Field renders
+   * as a pure layout wrapper: the child keeps its own value/onChange and
+   * no validation runs.
    */
-  formName: string;
+  formName?: string;
   /**
    * Whether disabled
    */

package/src/Field/style/index.less

@@ -25,6 +25,7 @@
   &-content {
     position: relative;
     padding-bottom: var(--yee-field-content-padding-bottom);
+    width: stretch;
   }
 
   &-error {

package/src/Table/demo/controlled-filter.tsx

@@ -0,0 +1,107 @@
+import { Button, message, Space, Table } from '@rainbow-oh/yee-c';
+import React, { useState } from 'react';
+
+import type { ColumnProps } from '@rainbow-oh/yee-c';
+
+interface RecordType {
+  key: string;
+  name: string;
+  age: number;
+  gender: string;
+}
+
+const allData: RecordType[] = [
+  { key: '1', name: 'John Brown', age: 32, gender: 'male' },
+  { key: '2', name: 'Jim Green', age: 42, gender: 'male' },
+  { key: '3', name: 'Joe Black', age: 32, gender: 'male' },
+  { key: '4', name: 'Jon Snow', age: 42, gender: 'female' },
+  { key: '5', name: 'Arya Stark', age: 16, gender: 'female' },
+];
+
+export default () => {
+  const { messageApi, messageHolder } = message.useMessage();
+
+  // Server-side search: keep the keyword controlled, refetch in onChange.
+  const [nameKeyword, setNameKeyword] = useState<string>('');
+
+  // Controlled local filter: the tree selection lives in the parent state.
+  const [genders, setGenders] = useState<string[]>([]);
+
+  const columns: ColumnProps[] = [
+    {
+      title: 'Name',
+      dataIndex: 'name',
+      key: 'name',
+      filter: {
+        searchable: true,
+        // No onFilter: no local matching, the search hits the "server".
+        filteredValue: nameKeyword,
+      },
+    },
+    {
+      title: 'Age',
+      dataIndex: 'age',
+      key: 'age',
+    },
+    {
+      title: 'Gender',
+      dataIndex: 'gender',
+      key: 'gender',
+      filter: {
+        filterMode: 'tree',
+        items: [
+          { label: 'Male', key: 'male' },
+          { label: 'Female', key: 'female' },
+        ],
+        filteredValue: genders,
+        onFilter: (value, record) => value === record.gender,
+      },
+    },
+  ];
+
+  const handleChange: React.ComponentProps<typeof Table>['onChange'] = (
+    info,
+  ) => {
+    if (info.action !== 'filter') return;
+
+    const filters = (info.filters ?? {}) as {
+      name?: string;
+      gender?: string[];
+    };
+
+    // The committing column's key is always present in the payload — with its
+    // empty value on clear — so both setting and clearing are mirrored here.
+    const name = filters.name ?? '';
+    if (name !== nameKeyword) {
+      // Pretend to refetch with ?name=<keyword>.
+      messageApi.info(`Fetch: /api/users?name=${name}`);
+      setNameKeyword(name);
+    }
+
+    setGenders(filters.gender ?? []);
+  };
+
+  const data = allData.filter((item) => {
+    const matchName = nameKeyword
+      ? item.name.toLowerCase().includes(nameKeyword.toLowerCase())
+      : true;
+    const matchGender = genders.length ? genders.includes(item.gender) : true;
+    return matchName && matchGender;
+  });
+
+  return (
+    <>
+      {messageHolder}
+      <Space block style={{ marginBottom: 16 }}>
+        <Button onClick={() => setNameKeyword('')}>Reset name search</Button>
+        <Button onClick={() => setGenders([])}>Reset gender filter</Button>
+      </Space>
+      <Table
+        columns={columns}
+        dataSource={data}
+        onChange={handleChange}
+        pagination={false}
+      />
+    </>
+  );
+};

package/src/Table/hooks/useFilter.ts

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import type { ColumnProps, FilterValue } from '../interface';
 
 type FilterInput = FilterValue | FilterValue[];
@@ -16,9 +16,81 @@ type FilterRecord = {
 const isEmptyFilterValue = (value: FilterInput) =>
   value === '' || (Array.isArray(value) && value.length === 0);
 
+export const isControlledFilter = (column?: ColumnProps) =>
+  column?.filter?.filteredValue !== undefined;
+
 const normalizeValue = (value: unknown) =>
   value === null || value === undefined ? '' : String(value).toLowerCase();
 
+// Controlled columns (`filteredValue` defined) always take their value from
+// the prop; internal records for them are ignored entirely — a commit on a
+// controlled column must not leak into the merged state while the parent has
+// not (yet) applied the new prop value.
+const mergeRecords = (
+  internalRecords: Array<FilterRecord>,
+  columnMap: Map<string, ColumnProps>,
+): Array<FilterRecord> => {
+  const controlled: Array<FilterRecord> = [];
+  columnMap.forEach((column, dataIndex) => {
+    if (!isControlledFilter(column)) return;
+    const value = column.filter?.filteredValue as FilterInput;
+    if (!isEmptyFilterValue(value)) {
+      controlled.push({ dataIndex, value });
+    }
+  });
+  const merged = internalRecords.filter(
+    (record) => !isControlledFilter(columnMap.get(record.dataIndex)),
+  );
+  if (!controlled.length && merged.length === internalRecords.length) {
+    return internalRecords;
+  }
+  return [...merged, ...controlled];
+};
+
+const applyFilters = (
+  data: Array<Record<string, unknown>>,
+  records: Array<FilterRecord>,
+  columnMap: Map<string, ColumnProps>,
+) => {
+  const handled = records.filter(
+    ({ dataIndex, value }) =>
+      Boolean(dataIndex) &&
+      columnMap.has(dataIndex) &&
+      !isEmptyFilterValue(value),
+  );
+  if (!handled.length) {
+    return data;
+  }
+  return data.filter((item) => {
+    return handled.every(({ dataIndex, value }) => {
+      const column = columnMap.get(dataIndex);
+
+      // Controlled column without `onFilter` is server-side: the data the
+      // consumer renders is already filtered upstream, pass it through.
+      if (isControlledFilter(column) && !column?.filter?.onFilter) {
+        return true;
+      }
+
+      const customFilter = column?.filter?.onFilter;
+      if (customFilter) {
+        return Array.isArray(value)
+          ? value.some((filterValue) => customFilter(filterValue, item))
+          : customFilter(value, item);
+      }
+
+      const targetValue = normalizeValue(item[dataIndex]);
+
+      if (Array.isArray(value)) {
+        return value.some(
+          (filterValue) => targetValue === normalizeValue(filterValue),
+        );
+      }
+
+      return targetValue.includes(normalizeValue(value));
+    });
+  });
+};
+
 export default function useFilter({
   data,
   columns,
@@ -26,7 +98,9 @@ export default function useFilter({
   data: Array<Record<string, unknown>>;
   columns: ColumnProps[];
 }) {
-  const [filterRecords, setFilterRecords] = useState<Array<FilterRecord>>([]);
+  const [internalRecords, setInternalRecords] = useState<Array<FilterRecord>>(
+    [],
+  );
   const columnMap = useMemo(
     () =>
       new Map(
@@ -38,64 +112,48 @@ export default function useFilter({
   );
 
   useEffect(() => {
-    setFilterRecords((current) => {
+    setInternalRecords((current) => {
       const next = current.filter(({ dataIndex }) => columnMap.has(dataIndex));
       return next.length === current.length ? current : next;
     });
   }, [columnMap]);
 
-  const onFilter = ({ value, dataIndex }: FilterOptions) => {
-    setFilterRecords((current) => {
-      if (isEmptyFilterValue(value)) {
-        return current.filter((item) => item.dataIndex !== dataIndex);
-      }
+  const activeRecords = useMemo(
+    () => mergeRecords(internalRecords, columnMap),
+    [internalRecords, columnMap],
+  );
 
-      const index = current.findIndex((item) => item.dataIndex === dataIndex);
-      if (index === -1) {
-        return [...current, { dataIndex, value }];
-      }
+  const filtered = useMemo(
+    () => applyFilters(data, activeRecords, columnMap),
+    [columnMap, data, activeRecords],
+  );
 
-      return current.map((item, itemIndex) =>
-        itemIndex === index ? { ...item, value } : item,
-      );
-    });
-  };
+  // Mirrors useSorter.onSort: computes the next state synchronously and
+  // returns it, so callers can emit onChange with the result in the same tick.
+  const onFilter = useCallback(
+    ({ value, dataIndex }: FilterOptions) => {
+      const nextInternal = isEmptyFilterValue(value)
+        ? internalRecords.filter((item) => item.dataIndex !== dataIndex)
+        : internalRecords.some((item) => item.dataIndex === dataIndex)
+          ? internalRecords.map((item) =>
+              item.dataIndex === dataIndex ? { ...item, value } : item,
+            )
+          : [...internalRecords, { dataIndex, value }];
 
-  const filtered = useMemo(() => {
-    const handled = filterRecords.filter(
-      ({ dataIndex, value }) =>
-        Boolean(dataIndex) &&
-        columnMap.has(dataIndex) &&
-        !isEmptyFilterValue(value),
-    );
-    if (!handled.length) {
-      return data;
-    }
-    return data.filter((item) => {
-      return handled.every(({ dataIndex, value }) => {
-        const customFilter = columnMap.get(dataIndex)?.filter?.onFilter;
-        if (customFilter) {
-          return Array.isArray(value)
-            ? value.some((filterValue) => customFilter(filterValue, item))
-            : customFilter(value, item);
-        }
-
-        const targetValue = normalizeValue(item[dataIndex]);
-
-        if (Array.isArray(value)) {
-          return value.some(
-            (filterValue) => targetValue === normalizeValue(filterValue),
-          );
-        }
-
-        return targetValue.includes(normalizeValue(value));
-      });
-    });
-  }, [columnMap, data, filterRecords]);
+      setInternalRecords(nextInternal);
+
+      const nextActive = mergeRecords(nextInternal, columnMap);
+      return {
+        data: applyFilters(data, nextActive, columnMap),
+        filterRecords: nextActive,
+      };
+    },
+    [internalRecords, columnMap, data],
+  );
 
   return {
     data: filtered,
-    filterRecords,
+    filterRecords: activeRecords,
     onFilter,
   };
 }

package/src/Table/index.en-US.md

@@ -22,6 +22,7 @@ A table displays rows of data.
 <code src="./demo/expand.tsx" title="Expandable" description="Expandable rows"></code>
 <code src="./demo/pagination.tsx" title="Pagination" description="Table with pagination"></code>
 <code src="./demo/column-filter.tsx" title="column filter" description="Table column filter"></code>
+<code src="./demo/controlled-filter.tsx" title="controlled filter" description="Controlled filtering with filteredValue: server-side search and programmatic reset"></code>
 <code src="./demo/grouping.tsx" title="Grouping" description="Multi-level header"></code>
 <code src="./demo/fixed.tsx" title="Fixed Columns" description="Fix columns on both sides and scroll horizontally to see the effect"></code>
 <code src="./demo/resizable.tsx" title="Resizable Columns" description="Drag the right edge of a header cell to resize it; arrow keys work too"></code>
@@ -77,7 +78,7 @@ A table displays rows of data.
 | styles | `Partial<Record<ColumnSemanticType, React.CSSProperties>>` | Column semantic styles | - |
 | align | `'left' \| 'right' \| 'center'` | Alignment | - |
 | fixed | `'left' \| 'right' \| true` | Fixed column | - |
-| filter | `object` | Filter configuration | - |
+| filter | `object` | Filter configuration, see [ColumnFilter](#columnfilter) below | - |
 | sorter | `boolean \| object` | Sorter configuration | - |
 | dataIndex | `string` | Data index | - |
 | key | `string \| number` | Unique key | - |
@@ -92,6 +93,26 @@ A table displays rows of data.
 | onHeaderCell | `(column: ColumnProps) => object` | Header cell props | - |
 | render | `(record: object, rowIndex: number) => React.ReactNode` | Custom render | - |
 
+### ColumnFilter
+
+Filter configuration of `ColumnProps.filter`.
+
+| Property | Type | Description | Default |
+| --- | --- | --- | --- |
+| filterMode | `'tree' \| 'menu'` | Filter menu mode (effective when `items` is set) | `menu` |
+| items | `Array<Record<string, any>>` | Filter menu items; renders a checkable tree panel when set | - |
+| searchable | `boolean` | Whether searchable; renders a search input when `items` is unset | `true` |
+| filterOnClose | `boolean` | Whether to apply the filter when the panel closes | `true` |
+| icon | `(filtered: boolean) => React.ReactNode` | Custom filter icon | - |
+| render | `() => React.ReactNode` | Custom filter panel content | - |
+| onFilter | `(value: FilterValue, record: object) => boolean` | Local filter function; falls back to default string-includes matching when unset | - |
+| filtered | `boolean` | Force the filter icon highlight (takes precedence over `filteredValue`) | - |
+| filteredValue | `FilterValue \| FilterValue[]` | (Controlled) Filter value. When set, the column's filter state is fully controlled: panel echo, icon highlight and the `filters` in `onChange` all derive from it; reset with `''` / `[]` | - |
+
+> **Controlled + server-side filtering**: with `filteredValue` set and no `onFilter`, no local matching happens at all — whether the data is filtered is decided by refetching in your `onChange` handler (see the controlled filter demo below).
+>
+> When `action === 'filter'`, the key of the column that was just committed is always present in `filters` (with `''` / `[]` on clear), so parents can mirror filter state from the payload alone.
+
 ### RowSelectionType
 
 | Property | Type | Description | Default |

package/src/Table/index.ts

@@ -5,6 +5,7 @@ import Head from './theader';
 
 export type {
   ColumnProps,
+  FilterValue,
   HeaderCell,
   PaginationType,
   RowSelectionType,

package/src/Table/index.zh-CN.md

@@ -29,6 +29,7 @@ toc: 'content'
 <code src="./demo/summary.tsx" title="统计" description="表格的统计行"></code>
 <code src="./demo/filter.tsx" title="筛选" description="表格的筛选功能"></code>
 <code src="./demo/column-filter.tsx" title="列筛选" description="表格的列筛选功能"></code>
+<code src="./demo/controlled-filter.tsx" title="受控筛选" description="filteredValue 受控筛选，支持服务端搜索与程序化重置"></code>
 <code src="./demo/components-override.tsx" title="自定义表格元素" description="可被外部（如 dnd-kit）接管的 tbody / 行渲染"></code>
 
 ## API
@@ -82,7 +83,7 @@ toc: 'content'
 | styles       | `Partial<Record<ColumnSemanticType, React.CSSProperties>>`           | 列结构化样式                   | -      |
 | align        | `'left' \| 'right' \| 'center'`                                      | 对齐方式                       | -      |
 | fixed        | `'left' \| 'right' \| true`                                          | 固定列                         | -      |
-| filter       | `object`                                                             | 过滤配置                       | -      |
+| filter       | `object`                                                             | 过滤配置，见下方 [ColumnFilter](#columnfilter) | -      |
 | sorter       | `boolean \| object`                                                  | 排序配置                       | -      |
 | dataIndex    | `string`                                                             | 行数据索引                     | -      |
 | key          | `string \| number`                                                   | 唯一key                        | -      |
@@ -97,6 +98,26 @@ toc: 'content'
 | onHeaderCell | `(column: ColumnProps) => object`                                    | 设置表头单元格属性             | -      |
 | render       | `(record: Record<string, any>, rowIndex: number) => React.ReactNode` | 自定义渲染函数                 | -      |
 
+### ColumnFilter
+
+`ColumnProps.filter` 的过滤配置。
+
+| 属性名        | 类型                                        | 描述                                                                                                  | 默认值 |
+| ------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------ |
+| filterMode    | `'tree' \| 'menu'`                          | 筛选菜单模式（配置 `items` 时生效）                                                                   | `menu` |
+| items         | `Array<Record<string, any>>`                | 筛选菜单项，配置后渲染树形多选面板                                                                    | -      |
+| searchable    | `boolean`                                   | 是否可搜索；未配置 `items` 时渲染搜索输入框                                                           | `true` |
+| filterOnClose | `boolean`                                   | 关闭筛选面板时是否自动应用筛选                                                                        | `true` |
+| icon          | `(filtered: boolean) => React.ReactNode`    | 自定义筛选图标                                                                                        | -      |
+| render        | `() => React.ReactNode`                     | 自定义筛选面板内容                                                                                    | -      |
+| onFilter      | `(value: FilterValue, record: object) => boolean` | 本地过滤函数；不配置时使用默认的字符串包含匹配                                                  | -      |
+| filtered      | `boolean`                                   | 强制筛选图标高亮（优先级高于由 `filteredValue` 派生的高亮）                                          | -      |
+| filteredValue | `FilterValue \| FilterValue[]`              | （受控）筛选值。配置后该列筛选状态完全受控：面板回显、图标高亮、`onChange` 的 `filters` 均以其为准；重置传 `''` / `[]` | -      |
+
+> **受控 + 服务端过滤**：列配置 `filteredValue` 且不配置 `onFilter` 时，不做任何本地过滤，数据是否过滤由你在 `onChange` 里重新请求决定，适合后台搜索场景（见下方「受控筛选」示例）。
+>
+> `action === 'filter'` 时，本次操作的列的 key 必在 `filters` 中（清空时值为 `''` / `[]`），父组件可直接据此镜像筛选状态。
+
 ### RowSelectionType
 
 | 属性名                 | 类型                                                                                         | 描述                        | 默认值 |