---
nav:
  title: 组件
  order: 1
group:
  title: 基础组件
  order: 1
title: ToolBar (PisellToolBar)
order: 5
category: pro
---

# ToolBar - 工具栏组件

ToolBar（对外导出为 **PisellToolBar**）是 PisellGridPro 的工具栏子组件，支持标签页行与上下两行共多个插槽，用于放置筛选、排序、操作按钮等。

## 何时使用

- 与 PisellGridPro 搭配，需要工具栏区域（标签页、搜索、筛选、操作按钮等）
- 需要固定结构的工具栏布局（tabs / topLeft / topRight / bottomLeft / bottomRight）

## 特性

- 🎯 **灵活布局**: 支持 tabs 行和上下两行的六个插槽位置
- 📐 **响应式设计**: 自适应容器宽度，支持左右分栏布局
- 🎨 **高度可定制**: 所有插槽均支持自定义 ReactNode 内容
- 🔧 **易于集成**: 作为 PisellGridPro 的一部分，无缝集成表格功能
- 💡 **语义化命名**: 虽然内部使用位置命名，但设计上支持任意内容放置

## 基础用法

从 `@pisell/materials` 引入 **PisellToolBar** 使用，与 PisellGridPro、PisellGridView 等组合构成完整页面布局。

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

export default () => (
  <PisellToolBar
    topLeft={
      <>
        <Button type="primary">新建</Button>
        <Button>导入</Button>
      </>
    }
    topRight={
      <>
        <Button>导出</Button>
        <Button>设置</Button>
      </>
    }
  />
);
```

## API

### ToolBar (PisellToolBar) Props

| 参数        | 说明             | 类型            | 默认值 | 必填 |
| ----------- | ---------------- | --------------- | ------ | ---- |
| className   | 自定义类名       | `string`        | -      | ❌   |
| style       | 自定义样式       | `CSSProperties` | -      | ❌   |
| tabs        | 标签页区域内容   | `ReactNode`     | -      | ❌   |
| topLeft     | 上方左侧区域内容 | `ReactNode`     | -      | ❌   |
| topRight    | 上方右侧区域内容 | `ReactNode`     | -      | ❌   |
| bottomLeft  | 下方左侧区域内容 | `ReactNode`     | -      | ❌   |
| bottomRight | 下方右侧区域内容 | `ReactNode`     | -      | ❌   |

## 进阶用法

### 带标签页的工具栏

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

export default () => (
  <PisellToolBar
      tabs={
        <Tabs
          items={[
            { key: '1', label: '全部' },
            { key: '2', label: '已发布' },
            { key: '3', label: '草稿' },
          ]}
        />
      }
      topLeft={
        <>
          <Button type="primary">新建</Button>
          <Button>批量操作</Button>
        </>
      }
    topRight={
      <>
        <Button>刷新</Button>
        <Button>设置</Button>
      </>
    }
  />
);
```

### 多行复杂布局

```tsx
import React from 'react';
import { PisellToolBar } from '@pisell/materials';
import { Button, Input, Select, Space } from 'antd';

export default () => (
  <PisellToolBar
      topLeft={
        <Space>
          <Button type="primary">新建</Button>
          <Button>导入</Button>
          <Button>批量删除</Button>
        </Space>
      }
      topRight={
        <Space>
          <Input.Search placeholder="搜索..." style={{ width: 200 }} />
          <Button>导出</Button>
        </Space>
      }
      bottomLeft={
        <Space>
          <Select
            placeholder="状态筛选"
            style={{ width: 120 }}
            options={[
              { label: '全部', value: 'all' },
              { label: '启用', value: 'active' },
              { label: '禁用', value: 'inactive' },
            ]}
          />
          <Select
            placeholder="分类筛选"
            style={{ width: 120 }}
            options={[
              { label: '全部分类', value: 'all' },
              { label: '分类A', value: 'a' },
              { label: '分类B', value: 'b' },
            ]}
          />
        </Space>
      }
    bottomRight={
      <Space>
        <Button>高级筛选</Button>
        <Button>重置</Button>
      </Space>
    }
  />
);
```

### 仅使用部分插槽

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

export default () => (
  <PisellToolBar
    topLeft={
      <Space>
        <Button type="primary">新建</Button>
        <Button>编辑</Button>
      </Space>
    }
  />
);
```

### 自定义样式

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

export default () => (
  <PisellToolBar
      className="custom-toolbar"
      style={{
        background: '#f5f5f5',
        padding: '16px',
        borderRadius: '8px',
      }}
    topLeft={<Button type="primary">操作按钮</Button>}
  />
);
```

## 布局说明

ToolBar 组件采用三行布局结构：

```
┌─────────────────────────────────────────┐
│  tabs (完整行)                           │
├─────────────────────────────────────────┤
│  topLeft          │         topRight    │
├─────────────────────────────────────────┤
│  bottomLeft       │      bottomRight    │
└─────────────────────────────────────────┘
```

- **tabs 行**: 独占一行，通常用于放置标签页组件
- **top 行**: 左右分栏布局
  - `topLeft`: 左侧区域，flex: 1，支持多个元素，gap: 8px
  - `topRight`: 右侧区域，flex-shrink: 0，支持多个元素，gap: 12px
- **bottom 行**: 左右分栏布局
  - `bottomLeft`: 左侧区域，flex: 1，支持多个元素，gap: 8px
  - `bottomRight`: 右侧区域，flex-shrink: 0，支持多个元素，gap: 12px

## 设计原则

1. **灵活性优先**: 虽然使用位置命名，但不限制插槽内容类型
2. **响应式**: 左侧区域自适应，右侧区域固定宽度
3. **间距统一**: 组件内部统一使用 8px、12px 的间距规范
4. **按需渲染**: 只有当插槽有内容时，才会渲染对应的行

## 注意事项

1. **命名约定**: 虽然使用了 topLeft、topRight 等位置命名，但实际使用时可以放置任意内容，不必拘泥于命名含义
2. **间距控制**: 如果需要更细粒度的间距控制，建议使用 `Space` 组件包裹子元素
3. **响应式**: 在小屏幕下，建议合理控制每个插槽的内容数量，避免溢出
4. **性能优化**: 如果插槽内容较复杂，建议使用 `React.memo` 优化子组件

## 设计指南

详见 [设计文档](./ToolBar.$tab-design.md)

## 开发指南

详见 [开发文档](./ToolBar.$tab-dev.md)

## 测试文档

详见 [测试文档](./ToolBar.$tab-test.md)
