@para-ui/core 5.0.0-beta.12 → 5.0.0-beta.14

package/ai-workflows/07-search-filter-table-trio.md

@@ -0,0 +1,387 @@
+# Workflow 7: Search + Filter + Table 三件套
+
+> **覆盖 baseline 失败任务**：Task 2（Search 受控模式）/ 加强对比 Task 22/28/30 已通过的模式
+> **集成 typescriptPitfalls**：Search 3 条（onChange 第一参 string / onKeydown 小写 / onClickBtn）+ SelectInput 联合泛型陷阱（M3 修复同款）+ DatePicker.RangePicker RangeValue 类型 + Select 多选 value 数组 + Table headData / render row / rowKey
+
+---
+
+## 何时使用
+
+列表页面需要组合多个过滤条件缩小结果集，然后展示到 Table：
+
+```
+Search 关键字搜索  +  Select/SelectInput 枚举过滤  +  DatePicker.RangePicker 时间范围  →  Table 联动展示
+```
+
+**典型业务**：订单搜索 / 用户列表筛选 / 资产查询 / 任务记录过滤
+
+**不要用此模板的场景**：
+- 全局顶部搜索（跨模块跳转）→ 用独立的 GlobalSearch 组件
+- 只有单个关键字搜索，无组合过滤 → 只用 Search + Table 即可
+- 搜索条件极其复杂（≥10 个字段）→ 考虑拆成高级搜索面板 + 简单搜索默认视图
+
+---
+
+## 关键模式（与脑补的区别）
+
+| 错误模式（AI 常犯） | 正确模式 |
+|------------------|--------|
+| ❌ `<Search onChange={(e) => setVal(e.target.value)} />` | ✅ **`onChange={(val) => setVal(val)}`**（第一参是 string 值，不是 event；与原生 input 不同） |
+| ❌ `<Search onKeyDown={handleEnter} />` | ✅ **`onKeydown={handleEnter}`**（prop 名小写 d；onKeyDown 驼峰 D 不存在，静默无效） |
+| ❌ `<SelectInput onChange={(val, _e) => setCategory(val)} />` 触发 TS7006 | ✅ **`onChange={(val: string \| undefined, _e: React.SyntheticEvent) => setCategory(val ?? '')}`**（联合泛型推断失败时 val 隐式 any，必须显式标注） |
+| ❌ `<DatePicker.RangePicker value={[dayjs(), dayjs().add(7,'day')]} />` | ✅ **`const range: RangeValue<Dayjs> = [...]; <DatePicker.RangePicker value={range} />`**（必须显式标注 `RangeValue<Dayjs>`，普通数组推断为 `Dayjs[]` 不匹配） |
+| ❌ `<Select multiple value={'active'} />` | ✅ **`<Select multiple value={['active']} />`**（多选 value 始终是数组） |
+| ❌ `headData={[{ title: '名称', dataIndex: 'name' }]}` | ✅ **`headData={[{ label: '名称', name: 'name' }]}`**（Para UI 用 label/name，不是 antd 的 title/dataIndex） |
+| ❌ `render={(value) => <Tag>{value}</Tag>}` | ✅ **`render={(row) => <Tag>{row.status}</Tag>}`**（第一参是整行 row，不是单元格值，与 antd 相反） |
+
+---
+
+## 完整代码（自包含，可直接复制）
+
+```tsx
+import React, { FunctionComponent, useMemo, useState } from 'react';
+import dayjs, { Dayjs } from 'dayjs';
+import { Button, DatePicker, Search, Select, SelectInput, Table } from '@para-ui/core';
+import { Message } from '@para-ui/core/Message';
+import type { HeadDataProps, RangeValue } from '@para-ui/core';
+
+// ---- 业务类型 ----
+type OrderStatus = 'pending' | 'processing' | 'completed' | 'cancelled';
+
+interface OrderRow {
+  id: string;
+  name: string;
+  category: string;
+  status: OrderStatus;
+  amount: number;
+  createdAt: string;  // ISO 日期字符串
+}
+
+// ---- 过滤条件类型 ----
+interface FilterState {
+  keyword: string;
+  category: string;
+  statusList: OrderStatus[];
+  dateRange: RangeValue<Dayjs>;   // ⚠️ 必须用 RangeValue<Dayjs>，不能用 Dayjs[] 或 [Dayjs, Dayjs]
+}
+
+// ---- 模拟数据 ----
+const mockOrders: OrderRow[] = [
+  { id: 'o1', name: '标准订单 A', category: 'standard', status: 'pending', amount: 100, createdAt: '2026-04-01' },
+  { id: 'o2', name: '加急订单 B', category: 'express', status: 'completed', amount: 250, createdAt: '2026-04-15' },
+  { id: 'o3', name: '标准订单 C', category: 'standard', status: 'processing', amount: 80, createdAt: '2026-05-01' },
+  { id: 'o4', name: '批量订单 D', category: 'bulk', status: 'cancelled', amount: 500, createdAt: '2026-05-10' },
+];
+
+const statusMap: Record<OrderStatus, string> = {
+  pending: '待处理',
+  processing: '处理中',
+  completed: '已完成',
+  cancelled: '已取消',
+};
+
+// ---- 主组件 ----
+const OrderListPage: FunctionComponent = () => {
+  // ---- 过滤状态 ----
+  const [filter, setFilter] = useState<FilterState>({
+    keyword: '',
+    category: '',
+    statusList: [],
+    dateRange: null,   // RangeValue<Dayjs> 初始为 null
+  });
+
+  // ---- 关键字搜索（受控）----
+  // Search.onChange 第一参是 string 值，不是 event
+  const handleKeywordChange = (val: string): void => {
+    setFilter(prev => ({ ...prev, keyword: val }));
+  };
+
+  // 点击搜索按钮或回车时触发查询
+  const handleSearch = (val: string): void => {
+    setFilter(prev => ({ ...prev, keyword: val }));
+    Message.info(`搜索: ${val || '（全部）'}`, 1500);
+  };
+
+  // ---- SelectInput 分类过滤 ----
+  // M3 修复同款：联合泛型推断失败时 val 隐式 any，必须显式标注参数类型
+  const handleCategoryChange = (val: string | undefined, _e: React.SyntheticEvent): void => {
+    setFilter(prev => ({ ...prev, category: val ?? '' }));
+  };
+
+  // ---- Select 多选状态过滤 ----
+  // ⚠️ Select onChange 签名是 (val: T | T[] | undefined, e)，多选时 val 是 T[]
+  // 直接传 (val: OrderStatus[]) 报类型错误——用 as 断言或在函数体内收窄
+  const handleStatusChange = (val: OrderStatus[] | OrderStatus | undefined, _e: React.SyntheticEvent): void => {
+    const list = Array.isArray(val) ? val : [];
+    setFilter(prev => ({ ...prev, statusList: list }));
+  };
+
+  // ---- DatePicker.RangePicker 时间范围 ----
+  // ⚠️ onChange 第一参类型是 RangeValue<Dayjs>（来自 rc-picker），不是 [Dayjs, Dayjs] | null
+  // RangeValue<Dayjs> = [EventValue<Dayjs>, EventValue<Dayjs>] | null
+  // EventValue<Dayjs> = Dayjs | null（rc-picker 定义）
+  const handleDateRangeChange = (
+    dates: RangeValue<Dayjs>,
+    _strs: [string, string]
+  ): void => {
+    setFilter(prev => ({ ...prev, dateRange: dates }));
+  };
+
+  // ---- 过滤逻辑（前端过滤，实际项目中通常是发 API 请求）----
+  const filteredData = useMemo<OrderRow[]>(() => {
+    return mockOrders.filter(order => {
+      if (filter.keyword && !order.name.includes(filter.keyword)) return false;
+      if (filter.category && order.category !== filter.category) return false;
+      if (filter.statusList.length > 0 && !filter.statusList.includes(order.status)) return false;
+      if (filter.dateRange) {
+        const [start, end] = filter.dateRange;
+        const created = dayjs(order.createdAt);
+        // ⚠️ RangeValue 子项可能是 string | Dayjs | null | undefined（NullableDateType）
+        // 用 dayjs.isDayjs 收窄类型再调用 Dayjs 方法
+        if (start && dayjs.isDayjs(start) && created.isBefore(start.startOf('day'))) return false;
+        if (end && dayjs.isDayjs(end) && created.isAfter(end.endOf('day'))) return false;
+      }
+      return true;
+    });
+  }, [filter]);
+
+  // ---- 重置所有过滤条件 ----
+  const handleReset = (): void => {
+    setFilter({ keyword: '', category: '', statusList: [], dateRange: null });
+  };
+
+  // ---- Table headData（Para UI 用 label/name，render 第一参是 row）----
+  const headData = useMemo<HeadDataProps<OrderRow>[]>(() => [
+    {
+      name: 'name',
+      label: '订单名称',
+      width: 160,
+    },
+    {
+      name: 'category',
+      label: '类别',
+      width: 100,
+      // render 第一参是整行 row（与 antd 相反，不是单元格 value）
+      render: (row) => ({ standard: '标准', express: '加急', bulk: '批量' }[row.category] ?? row.category),
+    },
+    {
+      name: 'status',
+      label: '状态',
+      width: 100,
+      render: (row) => statusMap[row.status],
+    },
+    {
+      name: 'amount',
+      label: '金额',
+      width: 100,
+      sort: true,   // Para UI 用 sort: boolean，不是 antd 的 sorter 函数
+    },
+    {
+      name: 'createdAt',
+      label: '创建时间',
+      width: 120,
+    },
+  ], []);
+
+  return (
+    <div style={{ padding: 24 }}>
+      <h2>订单列表</h2>
+
+      {/* 过滤工具栏 */}
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, marginBottom: 16, alignItems: 'center' }}>
+
+        {/* 关键字搜索：受控模式 */}
+        <Search
+          value={filter.keyword}
+          placeholder="搜索订单名称"
+          allowClear={true}
+          // ⚠️ onChange 第一参是 string 值，不是 event（与原生 input 不同）
+          onChange={handleKeywordChange}
+          // ⚠️ prop 名是 onKeydown（小写 d），不是 onKeyDown（大写 D）
+          onKeydown={(e) => { if (e.key === 'Enter') handleSearch(filter.keyword); }}
+          onClickBtn={handleSearch}
+          onClear={() => setFilter(prev => ({ ...prev, keyword: '' }))}
+          style={{ width: 200 }}
+        />
+
+        {/* SelectInput 分类过滤 */}
+        {/* ⚠️ M3 修复同款：onChange val 隐式 any，必须显式标注 (val: string | undefined, _e: React.SyntheticEvent) */}
+        <SelectInput
+          value={filter.category}
+          placeholder="全部类别"
+          list={[
+            { label: '标准', value: 'standard' },
+            { label: '加急', value: 'express' },
+            { label: '批量', value: 'bulk' },
+          ]}
+          onChange={handleCategoryChange}
+          style={{ width: 140 }}
+        />
+
+        {/* Select 多选状态过滤 */}
+        {/* ⚠️ multiple=true 时 value 是数组，onChange 签名是 (T | T[] | undefined, e) 联合 */}
+        <Select
+          multiple={true}
+          value={filter.statusList}
+          placeholder="全部状态"
+          list={[
+            { label: '待处理', value: 'pending' },
+            { label: '处理中', value: 'processing' },
+            { label: '已完成', value: 'completed' },
+            { label: '已取消', value: 'cancelled' },
+          ]}
+          onChange={handleStatusChange}
+          style={{ width: 160 }}
+        />
+
+        {/* DatePicker.RangePicker 时间范围 */}
+        {/* ⚠️ value 必须是 RangeValue<Dayjs>（不能是普通 Dayjs[]） */}
+        <DatePicker.RangePicker
+          value={filter.dateRange}
+          onChange={handleDateRangeChange}
+          placeholder={['开始日期', '结束日期']}
+          format="YYYY-MM-DD"
+          // disabledDate 参数是 Dayjs，不是 Date（无 .getTime()）
+          disabledDate={(cur) => cur && cur.isAfter(dayjs().endOf('day'))}
+        />
+
+        <Button variant="outlined" onClick={handleReset}>重置</Button>
+      </div>
+
+      {/* 结果计数 */}
+      <div style={{ marginBottom: 8, color: '#666', fontSize: 13 }}>
+        共 {filteredData.length} 条结果
+      </div>
+
+      {/* Table：Para UI 风格（headData / render row / rowKey string） */}
+      <Table<OrderRow>
+        rowKey="id"          // ⚠️ 必须显式传 rowKey（默认 'key' 在业务数据中几乎不存在）
+        data={filteredData}
+        headData={headData}  // ⚠️ Para UI 用 headData，不是 antd 的 columns
+        pagination={false}
+        autoSize={false}
+      />
+    </div>
+  );
+};
+
+export default OrderListPage;
+```
+
+---
+
+## 5 个真实陷阱（来自 M2/M3 修复实证）
+
+### ❌ 陷阱 1：Search onChange 当 event 处理（与原生 input 不同）
+
+```tsx
+// 错（Task 2 失败根因）
+<Search onChange={(e) => setKeyword(e.target.value)} />
+// TS 报：string 上不存在属性 'target'
+// Search.onChange 第一参是 string 值，不是 SyntheticEvent
+
+// 对
+<Search onChange={(val) => setKeyword(val)} />
+// val: string，直接使用
+
+// 陷阱变体：onKeyDown 大写 D 静默无效
+<Search onKeyDown={handleEnter} />   // 不存在，静默忽略
+<Search onKeydown={handleEnter} />   // ✅ prop 名小写 d（src/Search/index.tsx:36 实证）
+```
+
+### ❌ 陷阱 2：SelectInput onChange 参数隐式 any（M3 修复同款）
+
+```tsx
+// 错（M3 修复发现：联合泛型 Single | Multiple 在泛型 T 未推断时 val 隐式 any）
+<SelectInput onChange={(val, _e) => setCategory(val as string)} />
+// TS7006: Parameter 'val' implicitly has an 'any' type
+
+// 对：显式标注参数类型
+// 单选模式：
+<SelectInput onChange={(val: string | undefined, _e: React.SyntheticEvent) => setCategory(val ?? '')} />
+// 多选模式：
+<SelectInput onChange={(val: string[], _e: React.SyntheticEvent) => setValues(val ?? [])} />
+```
+
+### ❌ 陷阱 3：DatePicker.RangePicker value 用普通数组类型，onChange 签名写错
+
+```tsx
+// 错 1：value 推断为 Dayjs[]，不匹配 RangeValue<Dayjs>
+const [range, setRange] = useState([dayjs(), dayjs().add(7, 'day')]);
+<DatePicker.RangePicker value={range} />
+// TS2322: 'Dayjs[]' is not assignable to type 'RangeValue<Dayjs>'
+
+// 错 2：onChange 参数类型写成 [Dayjs, Dayjs] | null
+// 实际签名来自 rc-picker：(values: RangeValue<DateType>, formatString: [string, string]) => void
+onChange={(dates: [Dayjs, Dayjs] | null, strs) => setRange(dates)}
+// TS2322: RangeValue<Dayjs> 不能赋给 [Dayjs, Dayjs] | null
+
+// 错 3：直接对解构值调用 Dayjs 方法（类型是 NullableDateType = string|Dayjs|null|undefined）
+const [start, end] = range;
+if (start && created.isBefore(start.startOf('day'))) ...
+// TS2339: Property 'startOf' does not exist on type 'string | Dayjs'
+
+// 对：显式标注 RangeValue<Dayjs>，onChange 也用 RangeValue；解构值用 dayjs.isDayjs 收窄
+import type { RangeValue } from '@para-ui/core';
+const [range, setRange] = useState<RangeValue<Dayjs>>(null);
+<DatePicker.RangePicker
+  value={range}
+  onChange={(dates: RangeValue<Dayjs>, _strs: [string, string]) => setRange(dates)}
+/>
+// 解构后用 dayjs.isDayjs 收窄再调用方法
+const [start, end] = range ?? [null, null];
+if (start && dayjs.isDayjs(start) && created.isBefore(start.startOf('day'))) ...
+```
+
+### ❌ 陷阱 4：Select 多选 onChange 直接传窄类型函数
+
+```tsx
+// 错（Select onChange 是联合重载 (T | T[] | undefined, e)，传窄类型函数报类型不匹配）
+const handleStatus = (val: OrderStatus[], _e: React.SyntheticEvent) => { ... };
+<Select multiple onChange={handleStatus} />
+// TS2322: (val: OrderStatus[], _e) 不能赋给 (val: OrderStatus | OrderStatus[] | undefined, e) => void
+
+// 另一个常见错误：多选 value 传单值
+<Select multiple value={'pending'} />   // multiple=true 时 value 应是数组
+
+// 对：handler 参数用联合类型，函数体内用 Array.isArray 收窄
+const handleStatus = (val: OrderStatus[] | OrderStatus | undefined, _e: React.SyntheticEvent) => {
+  const list = Array.isArray(val) ? val : [];
+  setStatusList(list);
+};
+<Select multiple value={statusList} onChange={handleStatus} />
+```
+
+### ❌ 陷阱 5：Table headData / render 用 antd 风格
+
+```tsx
+// 错（Task 22/28/30 常见混淆：antd columns 风格移植到 Para UI）
+<Table columns={[
+  { title: '状态', dataIndex: 'status', sorter: true,
+    render: (value) => <Tag>{value}</Tag> }  // 第一参是 value（antd 惯例）
+]} />
+
+// 对：Para UI 用 headData，render 第一参是整行 row
+<Table<OrderRow>
+  rowKey="id"         // 必须显式传，默认 'key' 几乎不存在
+  headData={[
+    { label: '状态', name: 'status', sort: true,     // sort: boolean，不是 sorter 函数
+      render: (row) => statusMap[row.status] }        // 第一参是 row（整行数据）
+  ]}
+/>
+```
+
+---
+
+## 真实参考
+
+**Para 团队真实业务代码**（因路径隔离，以下是任务说明中的引用路径）：
+
+| 关键模式 | 所在文件 | 说明 |
+|---------|---------|------|
+| 搜索 + 过滤模式 | `console/src/package/Cluster/src/content.tsx` | Search + Select 联动 + Table |
+| SelectInput onChange 显式类型 | `src/SelectInput/component.json` typescriptPitfalls[2] | M3 修复同款：val 隐式 any |
+| RangeValue<Dayjs> 类型 | `src/DatePicker/component.json` typescriptPitfalls[2] | RangePicker value 必须用 RangeValue |
+| Select 多选 value 数组 | `src/Select/component.json` typescriptPitfalls[3] | multiple=true 时 value 是 T[] |
+| Table headData / render row | `src/Table/component.json` typescriptPitfalls[0-1] | label/name 字段；render 第一参是 row |
+| Search onChange string 直接用 | `src/Search/component.json` typescriptPitfalls[0] | val: string，不是 event |