---
nav:
  title: 组件
  order: 1
group:
  title: Data Display
  order: 1
title: Shell Frame（记录看板外壳）
order: 2
category: pro
---

# Shell Frame 记录看板外壳

Shell Frame 是 **PisellRecordBoard** 的外壳子组件，基于 `PisellShellFrame` 实现，提供「工具栏 + 多选操作栏 + 内容区 +
分页」的完整布局，与 **GridLayout** / **CardLayout** 搭配使用。

## 组件介绍

- **使用方式**：在 `PisellRecordBoard` 下使用 `PisellRecordBoard.ShellFrame` 包裹内容区（Layout），即可获得工具栏、多选操作栏和底部分页。
- **数据与配置**：Shell Frame 内各子组件通过 **useRecordBoardContext** 消费容器的 `data`、`searchParams`、`onSearch`、
  `columnVisibility` 等；工具栏、分页、批量操作栏的展示与行为由 **grid** / **toolBar** / **pagination** / **batchActionBar
  ** 等打散配置控制。

## 结构示意

```
┌─────────────────────────────────────────────────────────────────┐
│ ToolBar（最左可选：表格/平面图；左侧 QuickFilter + 搜索；右侧列设置、排序、筛选、重置） │
├─────────────────────────────────────────────────────────────────┤
│ BatchActionBar（有选中项时展示：全选/反选/清空/删除 + 自定义 actions）│
├─────────────────────────────────────────────────────────────────┤
│ 主内容：children（GridLayout/CardLayout）或 PisellFloorMapLayout   │
├─────────────────────────────────────────────────────────────────┤
│ Pagination（仅表格主内容时展示；平面图模式隐藏）                    │
└─────────────────────────────────────────────────────────────────┘
```

### 平面图模式（`FloorMap` 子组件 / 根级 `floorMap`）

当 ShellFrame 解析到 **平面图能力**（子节点含 **`PisellRecordBoard.FloorMap`** 和/或根级传入 **`floorMap`**）且当前 *
*`bodyView === 'floorMap'`**（或仅平面图、无表格区子节点时固定为平面图）时：

- 主内容区渲染 **PisellFloorMapLayout**，**不再**使用 `ScrollAreaMeasurer` 包裹（避免与画布滚动/缩放冲突）。
- **底部分页不展示**；批量操作栏仍保留（若业务需要可再在 BatchActionBar 层做显隐）。
- 切换回 **表格** 时恢复滚动测量与底部分页。
- **仅平面图、无 Grid 子节点** 时，左侧 **QuickFilter** 仍可来自 **`grid.columns`**（列上 `filter.quickFilter`）或 *
  *`toolBar.quickFilter.filterList`**
  ；详见 [PisellRecordBoard - 仅平面图快筛](./PisellRecordBoard.md#仅平面图左侧快筛与搜索无-gridlayout)。

详见 [PisellRecordBoard 使用文档](./PisellRecordBoard.md) 中的「平面图（Floor Map）」章节。

## 使用方式

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

const list = [{id: '1', name: '示例'}];
const columns = [{title: '名称', dataIndex: 'name', key: 'name'}];

export default () => (
    <PisellRecordBoard
        rowKey="id"
        data={list}
        loading={false}
        total={100}
        pagination={{pageNumber: 1, pageSize: 10}}
        onPageChange={() => {
        }}
        searchParams={{}}
        onSearch={() => {
        }}
        grid={{columns}}
    >
        <PisellRecordBoard.ShellFrame>
            <PisellRecordBoard.GridLayout/>
        </PisellRecordBoard.ShellFrame>
    </PisellRecordBoard>
);
```

## 子模块说明

| 模块                     | 说明                                                                                                                                                               |
|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **ToolBar**            | 工具栏。左侧：QuickFilter（可选）+ PisellFind 搜索；右侧：列设置、Sort、PisellFilter、ToolBarReset、slots.topRight。筛选项与排序项可由 `grid.columns` 派生，或通过 `toolBar.filter` / `toolBar.sort` 覆盖。 |
| **BatchActionBar**     | 多选操作栏。有选中行时展示；全选/反选/清空基于当前页 data；删除与自定义操作通过 `batchActionBar.actions` 等配置。                                                                                        |
| **Pagination**         | 底部分页。从 context 取 `pagination`、`total`、`onPageChange`；可透传 `childComponentProps.pagination`。样式类名：`record-board-shell-frame-pagination`。                            |
| **Search**             | 独立搜索槽（非 ToolBar 内嵌）。绑定 `searchParams.keyword` 与 `onSearch`，可通过 `childComponentProps.search` 透传 PisellFind 的 props。                                               |
| **ToolBarReset**       | 重置按钮。清空筛选与排序（filter.values、sort），并调用 `onSearch` / `onReset`。                                                                                                     |
| **ToolBarQuickFilter** | 左侧内联快速筛选。将 quickFilter 直接展示在 ToolBar 左侧；与 `searchParams.filter` 联动。启用时建议 Filter 弹层传 `hiddenQuickFilter: true`。                                                   |
| **ColumnSetting**      | 列显示隐藏入口。有 `grid.columns` 且 `toolBar.columnSetting !== false` 时在 ToolBar 右侧展示；点击弹出列显隐勾选。                                                                          |

## 配置入口（childComponentProps）

Shell Frame 内各块通过 RecordBoard 打散传入的 **grid**、**toolBar**、**pagination**、**batchActionBar** 等生效，对应关系如下。

| 配置键                | 作用范围           | 说明                                                                                                                                                                                                                                     |
|--------------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **grid**           | 列、滚动、多选、列默认隐藏  | `columns`、`defaultHiddenColumnKeys`、列上 `hidden: true` 参与列显隐；ColumnSetting 据此展示列列表。                                                                                                                                                     |
| **toolBar**        | ToolBar        | `search`：true/对象/false，控制搜索展示与透传。`filter`：同上，控制筛选弹层。`sort`：同上，控制排序。`quickFilter`：true 或 `{ filterList, formFiltersPrefix, size }`。`columnSetting`：是否显示列设置入口，默认 true。`topLeft` / `topRight` / `bottomLeft` / `bottomRight` / `tabs`：插槽。 |
| **pagination**     | Pagination     | 透传给底部分页组件（如 showSizeChanger、sizeOptions 等）。                                                                                                                                                                                            |
| **batchActionBar** | BatchActionBar | 与 PisellBatchActionBar 的 props 对齐：`actions`、`defaultActions`、`overflowThreshold`、`onDelete` 等。                                                                                                                                         |

## 搜索与筛选约定

- **搜索**：默认绑定 `searchParams.keyword`，变更时调用 `onSearch({ ...searchParams, keyword: value })`。
- **筛选**：绑定 `searchParams.filter`，结构为 `{ quickFilter, otherFilter, values }`；ToolBar 内右侧 Filter 弹层默认
  `hiddenQuickFilter: true`，快筛全部在左侧 QuickFilter 展示。**筛选默认值**：在受控用法下，给传入的 `searchParams` 设置初始值，在
  `filter.values` 里按 quickFilter 的 `name`/`key`
  写好默认值即可（详见 [PisellRecordBoard - 筛选默认值](./PisellRecordBoard.md#筛选默认值quickfilter)）。
- **排序**：绑定 `searchParams.sort`，单值字符串；Sort 与 Filter 变更均通过 `onSearch` 写回 `searchParams`。

## 相关文档

- [PisellRecordBoard 使用文档](./PisellRecordBoard.md)
- [PisellRecordBoard 开发文档](./PisellRecordBoard.$tab-dev.md)（ShellFrame 分支实现）
