---
title: 设计文档
order: 2
category: sub-component
---

# ToolBar 设计文档

## 设计来源

本组件基于 Figma 设计稿实现 (node-id=12890-101101)

## 设计理念

ToolBar 作为 PisellGridPro 的核心子组件，旨在提供一个灵活、可扩展的工具栏布局方案，满足各种表格操作场景的需求。

### 核心价值

1. **灵活性**: 支持多种布局组合，适应不同业务场景
2. **一致性**: 统一的间距和布局规范，保证视觉一致性
3. **可扩展性**: 所有插槽支持任意 ReactNode，便于业务定制
4. **响应式**: 自适应容器宽度，保证在不同屏幕下的良好体验

## 布局规范

### 整体结构

```
Container (display: flex, flex-direction: column)
├── padding-bottom: 16px
├── gap: 12px
└── background: #ffffff
```

### 行间距规范

- 行与行之间间距: 12px
- 底部内边距: 16px

### 各区域布局

#### Tabs 行

```
display: flex
flex-direction: row
align-items: center
gap: 12px
align-self: stretch
```

**用途**: 放置标签页组件，用于切换不同的数据视图

#### Top/Bottom 行

```
display: flex
flex-direction: row
align-items: center
justify-content: space-between
gap: 12px
align-self: stretch
```

**左侧区域 (topLeft/bottomLeft)**:

```
display: flex
flex-direction: row
align-items: flex-start
gap: 8px
flex: 1
```

**右侧区域 (topRight/bottomRight)**:

```
display: flex
flex-direction: row
align-items: center
gap: 12px
flex-shrink: 0
```

## 间距系统

| 位置             | 间距值 | 说明                        |
| ---------------- | ------ | --------------------------- |
| 行间距           | 12px   | 各行之间的垂直间距          |
| 左侧区域元素间距 | 8px    | topLeft/bottomLeft 内元素   |
| 右侧区域元素间距 | 12px   | topRight/bottomRight 内元素 |
| 容器底部内边距   | 16px   | 整个 ToolBar 的底部间距     |

## 视觉规范

### 颜色

- **背景色**: #ffffff (白色)
- **边框**: 无默认边框
- **阴影**: 无默认阴影

> 注: 颜色方案遵循 Ant Design 设计规范，可通过 className 和 style 自定义

### 对齐方式

- **Tabs 行**: 左对齐，items 水平居中
- **左侧区域**: flex-start 对齐，支持内容自适应
- **右侧区域**: 居中对齐，固定宽度不收缩

## 使用场景

### 场景 1: 简单操作栏

```
<ToolBar
  topLeft={<>操作按钮组</>}
  topRight={<>搜索、设置等</>}
/>
```

**适用于**: 简单的列表页面，只需要基本的操作按钮和搜索功能

### 场景 2: 带标签页的工具栏

```
<ToolBar
  tabs={<Tabs />}
  topLeft={<>操作按钮组</>}
  topRight={<>搜索、设置等</>}
/>
```

**适用于**: 需要切换不同视图的列表页面，如"全部/已发布/草稿"

### 场景 3: 复杂筛选场景

```
<ToolBar
  topLeft={<>操作按钮组</>}
  topRight={<>搜索</>}
  bottomLeft={<>筛选器组</>}
  bottomRight={<>高级筛选、重置</>}
/>
```

**适用于**: 需要多个筛选条件的复杂列表页面

### 场景 4: 完整功能

```
<ToolBar
  tabs={<Tabs />}
  topLeft={<>操作按钮组</>}
  topRight={<>搜索、导出</>}
  bottomLeft={<>筛选器组</>}
  bottomRight={<>高级筛选、重置</>}
/>
```

**适用于**: 功能完整的后台管理列表页面

## 响应式设计

### 桌面端 (≥ 1200px)

- 所有功能正常展示
- 左侧区域自适应，右侧区域固定

### 平板端 (768px - 1199px)

- 建议减少 topLeft/bottomLeft 的元素数量
- 或使用下拉菜单收纳部分功能

### 移动端 (< 768px)

- 建议将部分功能收纳到抽屉或弹窗
- 或使用分页展示功能

## 设计原则

### 1. 内容优先

- 只渲染有内容的行，避免空白占位
- 按需加载，不强制使用所有插槽

### 2. 布局灵活

- 左侧区域自适应，支持多个元素
- 右侧区域固定宽度，保证重要操作始终可见

### 3. 语义清晰

- 虽然使用位置命名，但不限制内容类型
- 开发者可根据实际需求自由组合

### 4. 易于扩展

- 所有插槽均支持 ReactNode
- 支持通过 className 和 style 自定义样式

## 可访问性

- 所有交互元素应有适当的 ARIA 标签
- 支持键盘导航
- 颜色对比度符合 WCAG 2.1 AA 标准

## 设计资源

- [Figma 设计稿](https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=12701-116234&p=f)
- [文档规范](https://m1ed09stz4r.feishu.cn/wiki/FdDcw20BPijIS8kTDVrc1esknlh)

## 版本历史

- v1.0.0: 初始版本，支持基础布局功能
