# 工具栏 · Toolbar

- 页面: https://jiguang132.com/zh/resources/astryx/docs/toolbar
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

工具栏用于操作场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **工具栏 · 交互示例 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **工具栏 · 交互示例 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **工具栏 · 交互示例 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **工具栏 · 尺寸变化 / 尺寸 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **工具栏 · 筛选 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **工具栏 · 交互示例 6**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Toolbar

Toolbar is a horizontal bar with left, center, and right areas. Use it for contextual actions within a content area (above a table, inside a card, or in a panel), not as a page-level header. Set the size once on the toolbar and all buttons, inputs, and tabs inside it match automatically.

### 使用建议

- Put secondary actions like "Back" on the left, and primary actions like "Save" on the right.
- Make temporary toolbars like bulk selection visually distinct so users can tell they're contextual, for example with a background color or border.
- Visually separate the toolbar from the content below it, with a divider, a background variant, or both.
- Use Toolbar as a card header when the header has interactive actions like filter or add; it gives you slot layout, keyboard navigation, and size cascading. If the header is just a title with no actions, a LayoutHeader or Section is enough.
- 避免：Put too many actions in one toolbar; move less common items into a MoreMenu.
- 避免：Set size on individual child buttons; set it once on the toolbar and it cascades automatically.
- 避免：Use Toolbar for app-wide navigation like main menu links or sign out; use TopNav or LayoutHeader for that.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-toolbar",
      "states": [
        "size"
      ]
    }
  ]
}
```

## Toolbar

通用工具栏容器，提供三个内容插槽和循环 Tab。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string |  | 工具栏的无障碍标签，作为 aria-label 应用。 |
| startContent | ReactNode |  | 起始内容（LTR 中靠左对齐）。 |
| centerContent | ReactNode |  | 居中内容。切换为 CSS grid（1fr auto 1fr）。 |
| endContent | ReactNode |  | 结束内容（LTR 中靠右对齐）。 |
| size | 'sm' \| 'md' \| 'lg' | 'md' | 工具栏尺寸。控制最小高度，子组件通过 SizeContext 继承此尺寸作为默认值。 |
| gap | 0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10 | 1 | 插槽内项目间距。 |
| orientation | 'horizontal' \| 'vertical' | 'horizontal' | 键盘导航方向。控制方向键方向。 |
| variant | SectionVariant | 'transparent' | 传递给 Section 的视觉变体。 |
| dividers | Array<'top' \| 'bottom' \| 'start' \| 'end'> |  | Borders/dividers rendered around the toolbar. |
| xstyle | StyleXStyles |  | 用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。 |

### 组件结构

- **Outer chrome**: Section-owned container that supplies the toolbar surface, padding, and selected divider edges.
- **Toolbar**: Named toolbar row that owns toolbar semantics and the start, optional center, and end layout.


## 完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

```bash
npm install @heroicons/react@2.2.0 lucide-react@1.24.0
```

## 示例的 StyleX 编译要求

ToolbarTableFilter 包含 stylex.create，需要配置 StyleX 源码编译流程。仅引入 Core 预编译 CSS 不足以运行这些示例样式，复制前请阅读[样式与 Tailwind](/resources/astryx/docs/styling)。

---

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