# Toolbar 工具栏 · HeroUI

> 用于承载可交互控件的容器，并支持方向键导航。

- 页面: https://jiguang132.com/zh/systems/heroui/docs/components/toolbar
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## 引入

```tsx
import { Toolbar } from '@heroui/react';
```

### 用法


> 示例 `toolbar-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/toolbar


### 垂直方向


> 示例 `toolbar-vertical`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/toolbar


### 与 ButtonGroup 组合


> 示例 `toolbar-with-button-group`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/toolbar


### Attached


> 示例 `toolbar-attached`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/toolbar


## 样式

### 传入 Tailwind CSS 类

```tsx
import { Toolbar } from '@heroui/react';

function CustomToolbar() {
  return (
    <Toolbar
      aria-label="Actions"
      className="rounded-xl border border-default bg-surface p-2"
    >
      {/* toolbar content */}
    </Toolbar>
  );
}
```

### 自定义组件类

若要自定义 Toolbar 的组件类名，可使用 `@layer components` 指令。
  
[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

```css
@layer components {
  .toolbar {
    @apply gap-4 rounded-lg bg-surface p-3;
  }
}
```

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于定制。

### CSS 类

Toolbar 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toolbar.css)）：

- `.toolbar` - 基础容器
- `.toolbar--horizontal` - 水平方向（默认）
- `.toolbar--vertical` - 垂直方向
- `.toolbar--attached` - Attached 变体：surface 背景与完全圆角

## API 参考

### Toolbar Props

继承 [React Aria Toolbar](https://react-spectrum.adobe.com/react-aria/Toolbar.html)。

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `isAttached` | `boolean` | `false` | Toolbar 是否使用带完全圆角的 surface 背景 |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Toolbar 的方向 |
| `aria-label` | `string` | - | Toolbar 的无障碍标签 |
| `aria-labelledby` | `string` | - | 用于标注该 Toolbar 的元素 id |
| `children` | `React.ReactNode \| (values: ToolbarRenderProps) => React.ReactNode` | - | 内容或渲染 prop |
| `className` | `string \| (values: ToolbarRenderProps) => string` | - | 额外的 CSS 类名 |

### ToolbarRenderProps

使用渲染 prop 模式时，会提供以下值：

| Prop | 类型 | 描述 |
|------|------|------|
| `orientation` | `"horizontal" \| "vertical"` | 当前 Toolbar 的方向 |

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt