---
title: 设计文档
order: 2
category: pro
---

# PisellRecordBoard 组件设计文档

## 1 组件概述

### 1.1 组件定位

PisellRecordBoard 是**记录看板容器**：在统一的数据与检索语义下，组合**工具栏、批量操作、表格或卡片内容区、分页**，并可选地与 *
*PisellFloorMapLayout** 构成「列表 ⟷ 平面图」双视图。本体不发起数据请求，只约定 Context 形状与 UI 分区。

### 1.2 使用场景

- 中后台列表页：搜索、筛选、排序、分页、行内样式与扩展行
- 与 DataSourceContainer / useRequest 等**受控**数据源对接
- 需要批量操作栏（删除、导出、自定义 actions）
- 餐厅座位图、卖场陈列等：**同一数据源**下表格与平面图切换编辑

## 2 概念模型

- **RecordBoard（容器）**：持有并下发 `data` / `pagination` / `searchParams` / 多选 / 列 UI 状态等。
- **Shell Frame（外壳）**：基于 PisellShellFrame 的「顶栏 + 批量条 + 主内容 + 底部分页」骨架；与具体 Layout 正交。
- **Layout**：内容区形态（Grid / Card）；**不含**分页组件（分页在外壳底部）。
- **bodyView**：在 ShellFrame 内**同时存在表格区（Grid/Card）与 `FloorMap` 槽位**（或根级 `floorMap` + 表格区）时，表示主内容区渲染
  **表格子树**还是**平面图**；与 `layoutType`（grid/card）**独立**。仅 `FloorMap`、无表格区子节点时固定为平面图，无 Segmented。

## 3 信息架构：工具栏（ToolBar）

### 3.1 从左到右的阅读顺序

```
[ 表格 | 平面图 ]（可选） → [ 快筛字段… ] → [ 关键词搜索 ] →（topLeft 插槽）
                                                                    …
（topRight 插槽）← [ 重置 ] ← [ 高级筛选 ] ← [ 排序 ] ← [ 列设置 ]（可选）
```

- **视图切换**：Segmented 置于**最左侧**，避免与「搜索」混淆；切换**不改变** `searchParams`，仅改变主内容渲染。
- **快筛 vs 高级筛选**：快筛贴近搜索，适合 1～3 个高频条件；复杂条件进 PisellFilter 弹层。
- **列设置**：靠右、与排序/筛选并列，表示「表格视图配置」；平面图下仍展示时，仅影响**回到表格**时的列状态。

### 3.2 批量操作栏（BatchActionBar）

- 无选中项时可隐藏或弱化；有选中项时与表格勾选状态一致。
- 全选/反选/清空语义以**当前页 `data`** 为准（与设计一致时需产品说明跨页策略由业务扩展）。

## 4 数据流（产品视角）

1. 用户操作搜索 / 筛选 / 排序 → 写入 **`searchParams`** → 调用 **`onSearch`**（通常触发刷新、回到第一页）。
2. 用户翻页 → **`onPageChange(pageNumber, pageSize)`**。
3. 用户勾选行 → **`onSelectionChange(keys, rows)`**（可与 grid 受控绑定）。
4. 用户在列设置中显隐列 / 调整顺序 → 容器状态更新，可选 **持久化到本地**（同一列表再进入保持习惯）。

详见 [开发文档](./PisellRecordBoard.$tab-dev.md) 中与 ToolBar、Grid 的字段绑定表。

## 5 双视图：表格与平面图

### 5.1 为什么共用一个 RecordBoard

- **一份检索语义**：`keyword` / `filter` / `sort` 对两种视图应一致（筛选掉的数据在平面图也不应出现）。
- **一份分页状态（表格）**：平面图通常展示**当前筛选结果全量或业务自定义子集**；产品上要明确是否仍依赖表格分页结果集。默认实现：
  **平面图模式隐藏底部分页**，避免「表格第 2 页」与「平面图全量」冲突；业务应将 `data` 切成与意图一致的集合。

### 5.2 平面图模式下的布局期望

- 主区域绝大部分高度交给 **PisellFloorMapLayout**（内部再分工具条、画布、侧栏）。
- 外层 ShellFrame **不再**对平面图包一层纵向滚动容器（避免与画布缩放、拖拽冲突）。

### 5.3 设计配合点

- 平面图编辑侧栏、Tab、与 RecordBoard ToolBar 的**视觉层级**：ToolBar 仍为页面级；平面图内含「放置工具 / 画布 Tab」为**次级**
  。参见 PisellFloorMapLayout 设计文档 § 平面图编辑态。

## 6 栅格与密度

- 表格默认支持小/中尺寸与横向滚动；**满高 + 表头固定**为推荐列表体验（`scroll.autoCalc`）。
- 同值列折叠：在「当前页数据高度同质」场景减少重复信息，总结区置于表头上方，需留出纵向空间（实现侧已计入 scroll 计算）。

## 7 响应式与端

- ToolBar 横排字段较多时，依赖 PisellToolBar 与业务插槽的折行/省略策略；快筛字段数量建议产品侧限制。
- 移动端若复用 RecordBoard，需单独评审 Touch 下筛选弹层与表格交互；当前实现以桌面端列表为主场景。

## 8 文案与无障碍

- 视图切换、排序等按钮文案走 **getText**（materials + utils 回退），保证中/英/繁一致策略与项目规范对齐。
- Segmented、Sort/Filter 按钮需可聚焦；列设置弹层内列表支持键盘与屏幕阅读器（依赖 antd / 内部 Popover 实现）。

## 9 扩展方向（产品预留）

- 更多 Layout：如看板列（kanban）复用同一 Context。
- ToolBar 上一级 Tab（如「全部订单」「我负责的」）通过 `toolBar.tabs` 插槽承载。

## 10 使用示例（自包含）

```tsx
import React from 'react';
import { PisellRecordBoard } from '@pisell/materials';
import { Button } from 'antd';

const list: { id: string; name: string }[] = [];
const contextValue = {
  data: list,
  loading: false,
  total: 0,
  pagination: { pageNumber: 1, pageSize: 10 },
  onPageChange: () => {},
  searchParams: {},
  onSearch: () => {},
  layoutType: 'grid' as const,
  rowKey: 'id',
};

function ExampleWithShellFrame() {
  return (
    <PisellRecordBoard layoutType="grid" rowKey="id" {...contextValue} grid={{ columns: [] }}>
      <PisellRecordBoard.ShellFrame>
        <PisellRecordBoard.GridLayout />
      </PisellRecordBoard.ShellFrame>
    </PisellRecordBoard>
  );
}

function ExampleContentOnly() {
  return (
    <PisellRecordBoard {...contextValue}>
      <PisellRecordBoard.GridLayout />
    </PisellRecordBoard>
  );
}

function ExampleCustomCombo() {
  return (
    <PisellRecordBoard rowKey="id" {...contextValue}>
      <PisellRecordBoard.ToolBar />
      <PisellRecordBoard.BatchActionBar />
      <PisellRecordBoard.Grid />
      <PisellRecordBoard.Pagination />
    </PisellRecordBoard>
  );
}

function ExampleWithToolBarProps() {
  return (
    <PisellRecordBoard
      layoutType="grid"
      rowKey="id"
      {...contextValue}
      toolBar={{
        topLeft: <Button>新建</Button>,
        search: { triggerType: 'input' },
        filter: { hiddenOtherFilter: false },
      }}
    >
      <PisellRecordBoard.ShellFrame>
        <PisellRecordBoard.GridLayout />
      </PisellRecordBoard.ShellFrame>
    </PisellRecordBoard>
  );
}

export default ExampleWithShellFrame;
```

## 11 相关文档

- [使用文档](./PisellRecordBoard.md)
- [开发文档](./PisellRecordBoard.$tab-dev.md)
- [测试文档](./PisellRecordBoard.$tab-test.md)
- [ShellFrame](./ShellFrame.md)
