---
nav:
  title: 组件
  order: 1
group:
  title: Layout
  order: 3
title: ToolBar
order: 5
category: sub-component
---

# ToolBar - 工具栏组件

## 简介

ToolBar 是 PisellGridPro 的子组件，用于提供灵活的工具栏布局能力。它支持多行布局，可以在不同位置放置各种操作按钮、筛选器、标签页等内容。

## 特性

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

## 基础用法

```tsx
import { PisellToolBar as ToolBar } from '@pisell/materials';
import { Button } from 'antd';

const Demo = () => {
  return (
    <ToolBar
      topLeft={
        <>
          <Button type="primary">新建</Button>
          <Button>导入</Button>
        </>
      }
      topRight={
        <>
          <Button>导出</Button>
          <Button>设置</Button>
        </>
      }
    />
  );
};

export default Demo;
```

## API

### ToolBar Props

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

## 进阶用法

### 带标签页的工具栏

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

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

export default Demo;
```

### 多行复杂布局

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

const Demo = () => {
  return (
    <ToolBar
      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>
      }
    />
  );
};

export default Demo;
```

### 仅使用部分插槽

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

const Demo = () => {
  return (
    <ToolBar
      topLeft={
        <Space>
          <Button type="primary">新建</Button>
          <Button>编辑</Button>
        </Space>
      }
    />
  );
};

export default Demo;
```

### 自定义样式

```tsx
import { PisellToolBar as ToolBar } from '@pisell/materials';
import { Button } from 'antd';

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

export default Demo;
```

## 布局说明

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)
