@pisell/materials 1.0.1048 → 1.0.1050

package/es/components/pisellFilter/docs/PisellFilter.md

@@ -3,8 +3,8 @@ nav:
   title: 组件
   order: 1
 group:
-  title: DataDisplay
-  order: 3
+  title: Data Entry
+  order: 1
 title: PisellFilter
 order: 16
 category: pro
@@ -12,84 +12,83 @@ category: pro
 
 # PisellFilter - 筛选组件
 
-## 简介
+PisellFilter 基于 Ant Design Form 封装，提供快速筛选与高级筛选两种模式，支持单选、输入、日期、日期范围、搜索等多种筛选类型，适用于表格、列表等需要筛选能力的场景。
+
+## 何时使用
 
-PisellFilter 是一个强大的筛选组件，基于 Ant Design Form 封装，提供了快速筛选和高级筛选两种模式。适用于表格、列表等需要复杂筛选功能的场景。
+- 列表/表格需要「快速筛选项 + 高级筛选项」的组合筛选
+- 需要与 Form 联动的筛选条件（支持字段前缀、受控 value/onChange）
+- 需要多种筛选类型：单选、输入框、日期、日期范围、带搜索按钮的输入
 
 ## 特性
 
-- 🎯 **双模式筛选**: 支持快速筛选和高级筛选两种模式
-- 🎨 **灵活配置**: 支持多种筛选类型（单选、输入、日期等）
-- 📱 **表单集成**: 基于 Ant Design Form 封装，支持表单联动
-- 🔄 **受控模式**: 支持完全受控的筛选状态管理
-- ⚡ **性能优化**: 合理的状态管理和更新机制
-- 🎭 **TypeScript**: 完整的 TypeScript 类型定义
+- 双模式：快速筛选（quickFilter）与高级筛选（otherFilter）可单独或同时使用
+- 多类型：single、input、datePicker、rangePicker、search
+- 表单集成：基于 Ant Design Form，支持表单联动
+- 受控模式：通过 `value` 与 `onChange` 管理筛选值
+- TypeScript：完整类型定义
 
 ## 基础用法
 
 ```tsx
-import {useState} from 'react';
-import {PisellFilter} from '@pisell/materials';
-
-const Demo = () => {
-    const [filterValue, setFilterValue] = useState({
-        quickFilter: [],
-        otherFilter: [],
-    });
-
-    return (
-        <PisellFilter
-            value={filterValue}
-            onChange={setFilterValue}
-            quickFilterMaxLength={5}
-            formFiltersPrefix="filter_"
-        />
-    );
+import React, { useState } from 'react';
+import { PisellFilter } from '@pisell/materials';
+
+export default () => {
+  const [filterValue, setFilterValue] = useState({
+    quickFilter: [],
+    otherFilter: [],
+  });
+
+  return (
+    <PisellFilter
+      value={filterValue}
+      onChange={setFilterValue}
+      quickFilterMaxLength={5}
+      formFiltersPrefix="filter_"
+    />
+  );
 };
-
-export default Demo;
 ```
 
 ## API
 
 ### PisellFilter Props
 
-| 参数                   | 说明         | 类型                                           | 默认值       | 版本 |
-|----------------------|------------|----------------------------------------------|-----------|----|
-| value                | 筛选值        | `FilterValueType`                            | -         | -  |
-| onChange             | 筛选值变化回调    | `(value: FilterValueType) => void`           | -         | -  |
-| hiddenQuickFilter    | 隐藏快速筛选     | `boolean`                                    | `true`    | -  |
-| hiddenOtherFilter    | 隐藏高级筛选     | `boolean`                                    | `false`   | -  |
-| quickFilterMaxLength | 快速筛选最大显示数量 | `number`                                     | `100`     | -  |
-| formFiltersPrefix    | 表单字段前缀     | `string`                                     | `''`      | -  |
-| renderItem           | 自定义渲染筛选项   | `(item: any, otherProps?: any) => ReactNode` | -         | -  |
-| size                 | 筛选按钮尺寸     | `'small' \| 'middle' \| 'large'`             | `'large'` | -  |
-| placement            | 弹出层定位      | `Popover` 的 placement                        | -         | -  |
+| 参数                  | 说明                   | 类型                 | 默认值  | 必填 |
+| --------------------- | ---------------------- | -------------------- | ------- | ---- |
+| value                 | 筛选值                 | `FilterValueType`    | -       | ❌   |
+| onChange              | 筛选值变化回调         | `(value: FilterValueType) => void` | -       | ❌   |
+| hiddenQuickFilter     | 隐藏快速筛选           | `boolean`            | `true`  | ❌   |
+| hiddenOtherFilter     | 隐藏高级筛选           | `boolean`            | `false` | ❌   |
+| quickFilterMaxLength  | 快速筛选最大显示数量   | `number`             | `100`   | ❌   |
+| formFiltersPrefix     | 表单字段前缀           | `string`             | `''`    | ❌   |
+| renderItem            | 自定义渲染筛选项       | `(item: any, otherProps?: any) => ReactNode` | -       | ❌   |
 
 ### FilterValueType
 
-```typescript
+```ts
 interface FilterValueType {
-    quickFilter: FilterItemProps[];  // 快速筛选项数组
-    otherFilter: FilterItemProps[];  // 高级筛选项数组
+  quickFilter: FilterItemProps[];  // 快速筛选项数组
+  otherFilter: FilterItemProps[];  // 高级筛选项数组
 }
 ```
 
 ### FilterItemProps
 
-```typescript
+```ts
 interface FilterItemProps {
-    type: 'single' | 'input' | 'datePicker' | 'rangePicker' | 'search';  // 筛选类型
-    name?: string | string[];        // 字段名称
-    key: string;                     // 唯一标识
-    props: object;                   // 传递给筛选组件的属性
-    label?: string;                  // 显示标签
-    sort?: boolean;                  // 是否可排序
-    localFilter?: boolean;           // 是否本地筛选
-    other: Record<string, any>;      // 其他配置
-    isCustom?: boolean;              // 是否自定义
-    columnKey?: string;              // 列键值
-    isHidden?: boolean;              // 是否隐藏
+  type: 'single' | 'input' | 'datePicker' | 'rangePicker' | 'search';
+  name?: string | string[];
+  key: string;
+  props: object;
+  label?: string;
+  sort?: boolean;
+  localFilter?: boolean;
+  other: Record<string, any>;
+  isCustom?: boolean;
+  columnKey?: string;
+  isHidden?: boolean;
 }
 ```
 
@@ -98,369 +97,227 @@ interface FilterItemProps {
 ### 快速筛选模式
 
 ```tsx
-import {PisellFilter} from '@pisell/materials';
-
-const Demo = () => {
-    const [filterValue, setFilterValue] = useState({
-        quickFilter: [
-            {
-                type: 'single',
-                key: 'status',
-                label: '状态',
-                name: 'status',
-                props: {
-                    options: [
-                        {label: '全部', value: 'all'},
-                        {label: '启用', value: 'enabled'},
-                        {label: '禁用', value: 'disabled'},
-                    ],
-                },
-                other: {},
-            },
-        ],
-        otherFilter: [],
-    });
-
-    return (
-        <PisellFilter
-            value={filterValue}
-            onChange={setFilterValue}
-            hiddenQuickFilter={false}
-            hiddenOtherFilter={true}
-            quickFilterMaxLength={3}
-        />
-    );
+import React, { useState } from 'react';
+import { PisellFilter } from '@pisell/materials';
+
+const initialQuickFilter = [
+  {
+    type: 'single' as const,
+    key: 'status',
+    label: '状态',
+    name: 'status',
+    props: {
+      options: [
+        { label: '全部', value: 'all' },
+        { label: '启用', value: 'enabled' },
+        { label: '禁用', value: 'disabled' },
+      ],
+    },
+    other: {},
+  },
+];
+
+export default () => {
+  const [filterValue, setFilterValue] = useState({
+    quickFilter: initialQuickFilter,
+    otherFilter: [],
+  });
+
+  return (
+    <PisellFilter
+      value={filterValue}
+      onChange={setFilterValue}
+      hiddenQuickFilter={false}
+      hiddenOtherFilter
+      quickFilterMaxLength={3}
+    />
+  );
 };
-
-export default Demo;
 ```
 
 ### 高级筛选模式
 
 ```tsx
-import {PisellFilter} from '@pisell/materials';
-
-const Demo = () => {
-    const [filterValue, setFilterValue] = useState({
-        quickFilter: [],
-        otherFilter: [
-            {
-                type: 'input',
-                key: 'keyword',
-                label: '关键词',
-                name: 'keyword',
-                props: {
-                    placeholder: '请输入关键词',
-                },
-                other: {},
-            },
-            {
-                type: 'datePicker',
-                key: 'created_at',
-                label: '创建时间',
-                name: 'created_at',
-                props: {},
-                other: {},
-            },
-        ],
-    });
-
-    return (
-        <PisellFilter
-            value={filterValue}
-            onChange={setFilterValue}
-            hiddenQuickFilter={true}
-            hiddenOtherFilter={false}
-        />
-    );
+import React, { useState } from 'react';
+import { PisellFilter } from '@pisell/materials';
+
+const initialOtherFilter = [
+  {
+    type: 'input' as const,
+    key: 'keyword',
+    label: '关键词',
+    name: 'keyword',
+    props: { placeholder: '请输入关键词' },
+    other: {},
+  },
+  {
+    type: 'datePicker' as const,
+    key: 'created_at',
+    label: '创建时间',
+    name: 'created_at',
+    props: {},
+    other: {},
+  },
+];
+
+export default () => {
+  const [filterValue, setFilterValue] = useState({
+    quickFilter: [],
+    otherFilter: initialOtherFilter,
+  });
+
+  return (
+    <PisellFilter
+      value={filterValue}
+      onChange={setFilterValue}
+      hiddenQuickFilter
+      hiddenOtherFilter={false}
+    />
+  );
 };
-
-export default Demo;
 ```
 
 ### 混合模式
 
 ```tsx
-import {PisellFilter} from '@pisell/materials';
-
-const Demo = () => {
-    const [filterValue, setFilterValue] = useState({
-        quickFilter: [
-            {
-                type: 'single',
-                key: 'category',
-                label: '分类',
-                name: 'category',
-                props: {
-                    options: [
-                        {label: '全部', value: 'all'},
-                        {label: '类型A', value: 'a'},
-                        {label: '类型B', value: 'b'},
-                    ],
-                },
-                other: {},
-            },
-        ],
-        otherFilter: [
-            {
-                type: 'rangePicker',
-                key: 'date_range',
-                label: '日期范围',
-                name: ['start_date', 'end_date'],
-                props: {},
-                other: {},
-            },
+import React, { useState } from 'react';
+import { PisellFilter } from '@pisell/materials';
+
+const initialValue = {
+  quickFilter: [
+    {
+      type: 'single' as const,
+      key: 'category',
+      label: '分类',
+      name: 'category',
+      props: {
+        options: [
+          { label: '全部', value: 'all' },
+          { label: '类型A', value: 'a' },
+          { label: '类型B', value: 'b' },
         ],
-    });
-
-    return (
-        <PisellFilter
-            value={filterValue}
-            onChange={setFilterValue}
-            hiddenQuickFilter={false}
-            hiddenOtherFilter={false}
-            quickFilterMaxLength={5}
-            formFiltersPrefix="filter_"
-        />
-    );
+      },
+      other: {},
+    },
+  ],
+  otherFilter: [
+    {
+      type: 'input' as const,
+      key: 'keyword',
+      label: '关键词',
+      name: 'keyword',
+      props: { placeholder: '请输入' },
+      other: {},
+    },
+  ],
 };
 
-export default Demo;
+export default () => {
+  const [filterValue, setFilterValue] = useState(initialValue);
+
+  return (
+    <PisellFilter
+      value={filterValue}
+      onChange={setFilterValue}
+      hiddenQuickFilter={false}
+      hiddenOtherFilter={false}
+      quickFilterMaxLength={5}
+      formFiltersPrefix="filter_"
+    />
+  );
+};
 ```
 
 ### 自定义渲染
 
 ```tsx
-import {PisellFilter} from '@pisell/materials';
-import {Tag} from 'antd';
-
-const Demo = () => {
-    const [filterValue, setFilterValue] = useState({
-        quickFilter: [],
-        otherFilter: [],
-    });
-
-    const renderItem = (item: any, otherProps: any) => {
-        return (
-            <div style={{padding: '8px'}}>
-                <Tag color="blue">{item.label}</Tag>
-                {/* 自定义渲染逻辑 */}
-            </div>
-        );
-    };
-
-    return (
-        <PisellFilter
-            value={filterValue}
-            onChange={setFilterValue}
-            renderItem={renderItem}
-        />
-    );
+import React, { useState } from 'react';
+import { PisellFilter } from '@pisell/materials';
+import { Tag } from 'antd';
+
+export default () => {
+  const [filterValue, setFilterValue] = useState({
+    quickFilter: [],
+    otherFilter: [],
+  });
+
+  const renderItem = (item: { label?: string }, _otherProps?: unknown) => (
+    <div style={{ padding: '8px' }}>
+      <Tag color="blue">{item.label}</Tag>
+    </div>
+  );
+
+  return (
+    <PisellFilter
+      value={filterValue}
+      onChange={setFilterValue}
+      renderItem={renderItem}
+    />
+  );
 };
-
-export default Demo;
 ```
 
 ### 本地筛选
 
 ```tsx
-import {PisellFilter} from '@pisell/materials';
-
-const Demo = () => {
-    const [filterValue, setFilterValue] = useState({
-        quickFilter: [
-            {
-                type: 'single',
-                key: 'status',
-                label: '状态',
-                name: 'status',
-                props: {
-                    options: [
-                        {label: '全部', value: 'all'},
-                        {label: '启用', value: 'enabled'},
-                    ],
-                },
-                localFilter: true,  // 启用本地筛选
-                other: {},
-            },
-        ],
-        otherFilter: [],
-    });
-
-    return (
-        <PisellFilter
-            value={filterValue}
-            onChange={setFilterValue}
-            hiddenQuickFilter={false}
-        />
-    );
+import React, { useState } from 'react';
+import { PisellFilter } from '@pisell/materials';
+
+const initialQuickFilter = [
+  {
+    type: 'single' as const,
+    key: 'status',
+    label: '状态',
+    name: 'status',
+    props: {
+      options: [
+        { label: '全部', value: 'all' },
+        { label: '启用', value: 'enabled' },
+      ],
+    },
+    localFilter: true,
+    other: {},
+  },
+];
+
+export default () => {
+  const [filterValue, setFilterValue] = useState({
+    quickFilter: initialQuickFilter,
+    otherFilter: [],
+  });
+
+  return (
+    <PisellFilter
+      value={filterValue}
+      onChange={setFilterValue}
+      hiddenQuickFilter={false}
+    />
+  );
 };
-
-export default Demo;
 ```
 
 ## 筛选类型说明
 
-### 1. single - 单选筛选
-
-适用于选项固定的单选场景，如状态、分类等。
-
-```typescript
-{
-    type: 'single',
-        key
-:
-    'status',
-        label
-:
-    '状态',
-        name
-:
-    'status',
-        props
-:
-    {
-        options: [
-            {label: '全部', value: 'all'},
-            {label: '启用', value: 'enabled'},
-            {label: '禁用', value: 'disabled'},
-        ],
-    }
-,
-    other: {
-    }
-,
-}
-```
-
-### 2. input - 输入框筛选
-
-适用于文本输入场景，如关键词搜索。
-
-```typescript
-{
-    type: 'input',
-        key
-:
-    'keyword',
-        label
-:
-    '关键词',
-        name
-:
-    'keyword',
-        props
-:
-    {
-        placeholder: '请输入关键词',
-    }
-,
-    other: {
-    }
-,
-}
-```
-
-### 3. datePicker - 日期选择
-
-适用于单个日期选择场景。
-
-```typescript
-{
-    type: 'datePicker',
-        key
-:
-    'created_at',
-        label
-:
-    '创建时间',
-        name
-:
-    'created_at',
-        props
-:
-    {
-        format: 'YYYY-MM-DD',
-    }
-,
-    other: {
-    }
-,
-}
-```
-
-### 4. rangePicker - 日期范围选择
-
-适用于日期范围筛选场景。
-
-```typescript
-{
-    type: 'rangePicker',
-        key
-:
-    'date_range',
-        label
-:
-    '日期范围',
-        name
-:
-    ['start_date', 'end_date'],
-        props
-:
-    {
-        format: 'YYYY-MM-DD',
-    }
-,
-    other: {
-    }
-,
-}
-```
+| type         | 说明               | 典型用法 |
+| ------------ | ------------------ | -------- |
+| `single`     | 单选筛选           | 状态、分类等，`props.options` 配置选项 |
+| `input`      | 输入框筛选         | 关键词，`props.placeholder` 等 |
+| `datePicker` | 单日期选择         | 创建时间等，`props.format` 可选 |
+| `rangePicker`| 日期范围           | 起止日期，`name` 可为 `[startKey, endKey]` |
+| `search`     | 带搜索按钮的输入   | 搜索框，`props.placeholder` 等 |
 
-### 5. search - 搜索框
-
-适用于带搜索按钮的输入场景。
-
-```typescript
-{
-    type: 'search',
-        key
-:
-    'search',
-        label
-:
-    '搜索',
-        name
-:
-    'search',
-        props
-:
-    {
-        placeholder: '请输入搜索内容',
-    }
-,
-    other: {
-    }
-,
-}
-```
+每项需包含 `type`、`key`、`name`、`props`、`other`，其余见 `FilterItemProps`。
 
 ## 注意事项
 
-1. **表单集成**: PisellFilter 组件内部已集成 Form，使用时无需再包裹 Form 组件
-2. **状态管理**: 组件使用受控模式，需要通过 `value` 和 `onChange` 管理状态
-3. **字段前缀**: 使用 `formFiltersPrefix` 可以避免字段名冲突
-4. **性能优化**: 大量筛选项时，建议设置合理的 `quickFilterMaxLength`
-5. **数据结构**: 确保 `quickFilter` 和 `otherFilter` 的数据结构符合 `FilterItemProps` 类型定义
-
-## 设计指南
-
-详见 [设计文档](./PisellFilter.$tab-design.md)
-
-## 开发指南
-
-详见 [开发文档](./PisellFilter.$tab-dev.md)
+1. **表单集成**：组件内部已集成 Form，无需再包一层 Form
+2. **受控模式**：通过 `value` 与 `onChange` 管理筛选值，二者需配套使用
+3. **字段前缀**：`formFiltersPrefix` 可避免与页面其他表单字段冲突
+4. **性能**：筛选项较多时建议设置合理的 `quickFilterMaxLength`
+5. **数据结构**：`quickFilter`、`otherFilter` 需符合 `FilterItemProps` 类型；日期类筛选项使用 datePicker/rangePicker 时，需在页面提供 `LocalizationProvider`（参见 PisellQuickFilter 文档）
 
-## 测试指南
+## 相关文档
 
-详见 [测试文档](./PisellFilter.$tab-test.md)
+- [设计文档](./PisellFilter.$tab-design.md)
+- [开发文档](./PisellFilter.$tab-dev.md)
+- [测试文档](./PisellFilter.$tab-test.md)