@para-ui/core 5.0.0-beta.11 → 5.0.0-beta.13

package/ai-workflows/08-table-advanced-features.md

@@ -0,0 +1,365 @@
+# Workflow 8: 表格高级特性（排序 / 行内编辑 / 展开 / 分页）
+
+> **基于**：console/src/package/Service/src/content.tsx（Para 团队真实业务代码）  
+> **覆盖 baseline 失败任务**：Task 4（排序）/ Task 5（行展开）/ Task 6（行内编辑）/ Task 7（分页）/ Task 8（多选+批量）  
+> **集成 typescriptPitfalls**：HeadDataProps 泛型必填 / render 第一参是 row 不是 value / headData 字段 label/sort 不是 title/sorter / rowKey 必传 / RangeValue 类型 / method 首字母大写
+
+---
+
+## 何时使用
+
+数据管理列表需要以下能力中的 2 项及以上：
+
+```
+列排序  +  行展开详情  +  行内编辑（Switch/状态切换）  +  客户端/服务端分页  +  多选批量操作
+```
+
+**典型业务**：任务管理 / 订单列表 / 资产台账 / 用户管理 / 角色权限列表
+
+**不要用此模板的场景**：
+- 只需基础展示（无交互）→ 用基础 Table
+- 没有行展开、排序、行内编辑需求 → 用 Workflow 1（CRUD 列表）
+
+---
+
+## 关键模式（与脑补的区别）
+
+| 错误模式（AI 常犯） | 正确模式 |
+|------------------|--------|
+| ❌ `headData: HeadDataProps[]`（无泛型）导致 render 中 row 类型是 unknown | ✅ **`headData: HeadDataProps<TaskRow>[]`** 或 `<Table<TaskRow>>` 泛型传导，render 有类型提示 |
+| ❌ `{ title: '状态', dataIndex: 'status', sorter: true }` antd 风格 | ✅ **`{ label: '状态', name: 'status', sort: true }`**（label/name/sort，不是 title/dataIndex/sorter）|
+| ❌ `render={(value) => <Tag>{value}</Tag>}` 以为第一参是单元格值 | ✅ **`render={(row) => <Tag>{row.status}</Tag>}`** 第一参是整行数据（与 antd 相反）|
+| ❌ `<Table data={list} />` 不传 rowKey | ✅ **`rowKey='id'`** 必传，默认 'key' 业务数据几乎没有该字段 |
+| ❌ `rowKey={(row) => row.id}` 函数形式 | ✅ **`rowKey='id'`** 只接受字符串字段名 |
+| ❌ RangePicker 传普通数组 `[dayjs(), dayjs()]` | ✅ **`const val: RangeValue<Dayjs> = [...]`** 显式类型声明 |
+
+---
+
+## 完整代码（自包含，可直接复制）
+
+```tsx
+import React, { FunctionComponent, useState, useMemo } from 'react';
+import { Table, Button, Switch, PopConfirm, DatePicker } from '@para-ui/core';
+import { Message } from '@para-ui/core/Message';
+import type { HeadDataProps } from '@para-ui/core';
+import type { OperateBtnListProps } from '@para-ui/core/OperateBtn';
+import type { RangeValue } from '@para-ui/core';
+import { Dayjs } from 'dayjs';
+
+// 行数据类型（必须定义，用于 HeadDataProps<TaskRow> 泛型）
+interface TaskRow {
+  id: string;
+  title: string;
+  assignee: string;
+  status: 'pending' | 'running' | 'done' | 'failed';
+  priority: 'low' | 'medium' | 'high';
+  disabled: boolean;
+  createdAt: string;
+  detail: string;
+}
+
+const TaskListPage: FunctionComponent = () => {
+  const [refresh, setRefresh] = useState<number>(0);
+  const refreshData = (): void => setRefresh(Math.random());
+
+  // Switch 行内切换的异步 loading map（key = 行 id）
+  const [switchLoadingMap, setSwitchLoadingMap] = useState<Record<string, boolean>>({});
+
+  // 多选 state
+  const [checkValue, setCheckValue] = useState<string[]>([]);
+
+  // 日期范围筛选（注意：RangeValue<Dayjs> 不能传普通 Dayjs[]）
+  const [dateRange, setDateRange] = useState<RangeValue<Dayjs>>(null);
+
+  // 新建 Drawer
+  const [openForm, setOpenForm] = useState<boolean>(false);
+  const [editRow, setEditRow] = useState<TaskRow | undefined>();
+
+  // ---- Switch 行内切换（带 loading）----
+  const handleToggleDisabled = async (row: TaskRow): Promise<void> => {
+    setSwitchLoadingMap(prev => ({ ...prev, [row.id]: true }));
+    try {
+      await mockApi.updateStatus(row.id, !row.disabled);
+      Message.success(`已${row.disabled ? '启用' : '停用'} ${row.title}`);
+      refreshData();
+    } finally {
+      setSwitchLoadingMap(prev => ({ ...prev, [row.id]: false }));
+    }
+  };
+
+  // ---- 操作列定义 ----
+  const buildOperateBtnList = (row: TaskRow): OperateBtnListProps[] => [
+    {
+      key: 'edit',
+      label: '编辑',
+      onClick: () => { setEditRow(row); setOpenForm(true); }
+    },
+    {
+      key: 'delete',
+      label: '删除',
+      disabled: row.status === 'running',
+      toolTipTitle: row.status === 'running' ? '运行中不可删除' : undefined,
+      onClick: async () => {
+        await mockApi.deleteTask(row.id);
+        Message.success('已删除');
+        refreshData();
+      }
+    }
+  ];
+
+  // ---- 列定义（必须带泛型 HeadDataProps<TaskRow>，否则 render 中 row 是 unknown）----
+  const headData = useMemo<HeadDataProps<TaskRow>[]>(() => [
+    // sort: true 是布尔值，不是函数；字段名是 label/name/sort，不是 title/dataIndex/sorter
+    { name: 'title', label: '任务名称', sort: true, width: 200 },
+    { name: 'assignee', label: '负责人', width: 120 },
+    {
+      name: 'priority',
+      label: '优先级',
+      sort: true,
+      width: 100,
+      // render 第一参是整行数据（row），不是单元格值（与 antd 相反）
+      render: (row) => {
+        const map: Record<TaskRow['priority'], string> = {
+          low: '低', medium: '中', high: '高'
+        };
+        return map[row.priority];
+      }
+    },
+    {
+      name: 'status',
+      label: '状态',
+      width: 120,
+      render: (row) => {
+        const statusMap: Record<TaskRow['status'], string> = {
+          pending: '等待中', running: '运行中', done: '已完成', failed: '失败'
+        };
+        return statusMap[row.status];
+      }
+    },
+    {
+      name: 'disabled',
+      label: '启用',
+      width: 100,
+      render: (row) => (
+        // Switch loading 通过 loadingMap 控制，PopConfirm 包裹确认
+        <PopConfirm
+          title={row.disabled ? '确认启用此任务？' : '确认停用此任务？'}
+          onOk={() => handleToggleDisabled(row)}
+        >
+          <Switch
+            checked={!row.disabled}
+            loading={switchLoadingMap[row.id] ?? false}
+          />
+        </PopConfirm>
+      )
+    },
+    { name: 'createdAt', label: '创建时间', sort: true, width: 150 }
+  ], [switchLoadingMap]);
+
+  // ---- 批量操作 ----
+  const handleBatchStop = async (): Promise<void> => {
+    await mockApi.batchStop(checkValue);
+    Message.success(`已停用 ${checkValue.length} 个任务`);
+    setCheckValue([]);
+    refreshData();
+  };
+
+  return (
+    <div>
+      {/* 顶部筛选区 */}
+      <div style={{ marginBottom: 16, display: 'flex', gap: 8, alignItems: 'center' }}>
+        {/* RangePicker value 必须是 RangeValue<Dayjs>，不是普通 Dayjs[] */}
+        <DatePicker.RangePicker
+          value={dateRange}
+          onChange={(dates: RangeValue<Dayjs>) => setDateRange(dates)}
+        />
+        <Button onClick={() => { setDateRange(null); refreshData(); }}>
+          重置
+        </Button>
+        <Button onClick={() => { setEditRow(undefined); setOpenForm(true); }}>
+          新建任务
+        </Button>
+        {checkValue.length > 0 && (
+          <>
+            <span style={{ alignSelf: 'center' }}>已选 {checkValue.length} 项</span>
+            <PopConfirm title="确认批量停用？" onOk={handleBatchStop}>
+              <Button>批量停用</Button>
+            </PopConfirm>
+          </>
+        )}
+      </div>
+
+      {/* 表格本体 */}
+      {/* 关键：Table<TaskRow> 泛型 + rowKey='id'（字符串，不是函数）*/}
+      {/* pagination 只接受 boolean，不接受对象；分页配置用 paginationType */}
+      <Table<TaskRow>
+        rowKey="id"
+        data={mockData}
+        headData={headData}
+        refresh={refresh}
+        pagination={true}
+        paginationType="complex"
+        // 排序由 headData[n].sort: true 开启，Table 内部处理
+        // 操作列
+        operate={{
+          label: '操作',
+          width: 160,
+          operateBtnRender: (row: TaskRow) => ({
+            list: buildOperateBtnList(row),
+            showNum: 3
+          })
+        }}
+        // 多选；setCheck 签名 (keys: string[], data: T[]) => void
+        check={true}
+        setCheck={(keys: string[]) => setCheckValue(keys)}
+        // 行展开：expandable 是函数，返回展开内容
+        expandable={(row: TaskRow) => (
+          <div style={{ padding: '8px 16px', background: '#fafafa' }}>
+            <strong>详情：</strong>{row.detail}
+          </div>
+        )}
+      />
+
+      {/* 新建/编辑 Drawer 占位 */}
+      {openForm && (
+        <TaskFormDrawer
+          open={openForm}
+          rowData={editRow}
+          onFinish={(saved?: boolean) => {
+            setOpenForm(false);
+            setEditRow(undefined);
+            if (saved) refreshData();
+          }}
+        />
+      )}
+    </div>
+  );
+};
+
+export default TaskListPage;
+
+// === 占位 Mock（实际项目来自业务 API）===
+const mockData: TaskRow[] = [];
+const mockApi = {
+  updateStatus: async (id: string, disabled: boolean): Promise<void> => { void id; void disabled; },
+  deleteTask: async (id: string): Promise<void> => { void id; },
+  batchStop: async (ids: string[]): Promise<void> => { void ids; }
+};
+const TaskFormDrawer: FunctionComponent<{
+  open: boolean; rowData?: TaskRow; onFinish: (saved?: boolean) => void
+}> = () => null;
+```
+
+---
+
+## 5 个真实陷阱（来自 M2/M3 修复实证）
+
+### ❌ 陷阱 1：HeadDataProps 不带泛型 → render row 类型是 unknown（50% 对照实验失败的代表）
+
+```tsx
+// 错（最高频陷阱，M2/M3 修复实证：50% Task 失败来自此处）
+const headData: HeadDataProps[] = [
+  { name: 'status', label: '状态', render: (row) => row.status }
+  //                                                ^^ TS: 类型"unknown"上不存在属性"status"
+];
+
+// 对（方式 A：声明时带泛型）
+const headData: HeadDataProps<TaskRow>[] = [
+  { name: 'status', label: '状态', render: (row) => row.status }
+  //                                                ^^ row: TaskRow，有类型提示
+];
+
+// 对（方式 B：Table 组件泛型传导）
+<Table<TaskRow> headData={headData} ... />
+// 让泛型从组件级传导到 headData 中的 render 函数
+```
+
+### ❌ 陷阱 2：headData 字段名用 antd 风格（title/sorter/dataIndex）
+
+```tsx
+// 错（M2 ComboSelect 修复发现的高频错误，Table 同款）
+const headData = [
+  { title: '任务名', dataIndex: 'title', sorter: true }
+  // title → 不认识，label 才是正确字段名
+  // dataIndex → 不认识，name 才是正确字段名
+  // sorter: true → sorter 不是 sort，且 sort 只接受 boolean
+];
+
+// 对
+const headData: HeadDataProps<TaskRow>[] = [
+  { label: '任务名', name: 'title', sort: true }
+  //  ^^^^^ label    ^^^^ name      ^^^^ sort: boolean（不是函数）
+];
+```
+
+### ❌ 陷阱 3：render 第一参以为是单元格 value（与 antd 相反）
+
+```tsx
+// 错（antd 习惯带来的认知偏差）
+{ name: 'priority', label: '优先级', render: (value) => {
+  // value 实际上是整行 TaskRow 对象，不是 row.priority 字符串
+  return <Tag>{value}</Tag>; // 渲染出 [object Object]
+}}
+
+// 对：第一参是 row，第二参是 index，第三参是 val（单元格值）
+{ name: 'priority', label: '优先级', render: (row) => {
+  return <Tag>{row.priority}</Tag>; // row.priority 是 'low' | 'medium' | 'high'
+}}
+// 如果确实需要单元格值：render: (row, index, val) => val
+```
+
+### ❌ 陷阱 4：RangePicker value 传普通数组导致 TS 类型错误
+
+```tsx
+// 错（隐式类型推断为 Dayjs[]，不匹配 RangeValue<Dayjs>）
+const [dateRange, setDateRange] = useState([dayjs(), dayjs().add(7, 'day')]);
+// ^ 推断为 Dayjs[]，不是 RangeValue<Dayjs>
+
+<DatePicker.RangePicker
+  value={dateRange}   // TS: Type 'Dayjs[]' is not assignable to type 'RangeValue<Dayjs>'
+  onChange={(dates) => setDateRange(dates)}
+/>
+
+// 对
+import type { RangeValue } from '@para-ui/core';
+const [dateRange, setDateRange] = useState<RangeValue<Dayjs>>(null);
+//                               显式泛型 ↑，初始值 null 是合法的 RangeValue<Dayjs>
+
+<DatePicker.RangePicker
+  value={dateRange}
+  onChange={(dates: RangeValue<Dayjs>) => setDateRange(dates)}
+/>
+```
+
+### ❌ 陷阱 5：rowKey 传函数形式 + Switch loading 直接用 boolean state
+
+```tsx
+// 错（rowKey 只接受字符串字段名）
+<Table rowKey={(row) => row.id} ... />
+// TS: Type '(row: any) => string' is not assignable to type 'string'
+
+// 错（Switch loading 用单个 boolean state，多行并发切换会互相覆盖）
+const [loading, setLoading] = useState(false);
+// 点击 A 行时 B 行 Switch 也会进入 loading
+
+// 对：rowKey 用字符串；loading 用 loadingMap
+<Table rowKey="id" ... />
+const [switchLoadingMap, setSwitchLoadingMap] = useState<Record<string, boolean>>({});
+// 每行有独立 loading 状态，互不影响
+<Switch loading={switchLoadingMap[row.id] ?? false} />
+```
+
+---
+
+## 真实参考
+
+**Para 团队真实业务代码**：`console/src/package/Service/src/content.tsx`
+
+| 关键模式 | 行号 |
+|---------|------|
+| `useAsync(updateDisabled, 'id')` + `updateDisabledLoadingMap[row.id]` 实现 Switch loadingMap | 66, 452 |
+| `headData: HeadDataProps[]`（真实列定义，render row 第一参） | 249-481 |
+| `PopConfirm` 包裹 Switch 实现确认切换 | 425-455 |
+| `operate.operateBtnRender` + `showNum: 5` | 598-608 |
+| `check={true}` + `setCheck={onChangeTableCheck}` | 609-612 |
+| `refresh={refresh}` + `setRefresh(Math.random())` 驱动刷新 | 56, 77 |