工具栏 · Toolbar
工具栏用于操作场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。
安装与前置条件
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。
示例与使用方式
- 工具栏 · 交互示例 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
{
"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.
完整示例的额外依赖
部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：
npm install @heroicons/react@2.2.0 lucide-react@1.24.0
示例的 StyleX 编译要求
ToolbarTableFilter 包含 stylex.create，需要配置 StyleX 源码编译流程。仅引入 Core 预编译 CSS 不足以运行这些示例样式，复制前请阅读样式与 Tailwind。