syncfusion-react-toolbar

实现 Syncfusion React 工具栏

组件概览

Syncfusion React 工具栏组件提供了灵活的命令栏，可用于组织和执行命令。它支持多种项目类型（按钮、分隔符、输入框）、响应式溢出模式以及完善的无障碍功能。

主要功能：

• 多种项目类型：Button、Separator、Input
• 响应式溢出模式：Scrollable、Popup、MultiRow、Extended
• 内置键盘导航和 ARIA 支持
• 在工具栏项目中渲染组件
• 可自定义外观和行为
• 支持 Tab 键导航
• 动态项目管理（添加/移除/启用/禁用）
• 丰富的事件系统（beforeCreate、clicked、keyDown、created、destroyed）
• 全面的 RTL 和区域设置支持
• 无状态模板渲染

---

完整目录

1. 入门

文件： references/getting-started.md

• 依赖项设置
• 项目初始化（Vite/CRA）
• 安装软件包
• CSS 主题导入（Tailwind、Bootstrap、Fluent、Material）
• 基本实现示例
• 全局配置：
  • 用于国际化的区域设置支持
  • RTL（从右到左）布局
  • 持久化设置
  • 碰撞检测
  • HTML 清理器
• 开发服务器设置

2. 项目配置

文件： references/item-configuration.md

• ItemModel API 参考：
  • 完整的接口结构
  • 全部 16 个属性及其类型
  • 带说明的属性参考
  • Items 数组配置模式
  • 配置示例（简单、分组、条件、无障碍）
• 按钮项目类型及其属性：
  • text - 显示文本
  • id - 唯一标识符
  • prefixIcon / suffixIcon - 图标位置
  • width - 自定义宽度
  • align - 对齐方式（Left/Center/Right）
  • disabled - 禁用状态
  • visible - 可见性控制
  • cssClass - 自定义 CSS 类
  • htmlAttributes - HTML 属性
  • overflow - 优先级显示（Show/Hide/None）
  • showAlwaysInPopup - 强制在弹出框中显示
  • showTextOn - 文本显示模式（Both/Overflow/Toolbar）
• 分隔符项目类型
• 用于组件的输入项目类型
• 使用 tabIndex 进行 Tab 导航
• 完整的可运行示例

3. 响应式模式

文件： references/responsive-modes.md

• Scrollable 模式（默认）
  • 使用导航箭头进行水平滚动
  • 支持触摸滑动
  • 使用键盘方向键导航
  • 适用场景：项目较多、大屏幕
• Popup 模式
  • 下拉溢出容器
  • 控制命令优先级
  • 外观紧凑
  • 适用场景：空间有限、移动设备
• MultiRow 模式
  • 项目换行显示为多行
  • 无需滚动
  • 所有项目均可见
  • 适用场景：响应式宽度容器
• Extended 模式
  • 多行显示并支持水平滚动
  • 按行导航
  • 适用场景：有限宽度内项目较多
• 命令优先级（Show/Hide/None）
• 文本显示选项（Both/Overflow/Toolbar）
• 模式对比表
• 各模式的实用示例

4. 无障碍与键盘支持

文件： references/accessibility.md

• 合规标准：
  • WCAG 2.2 AA 级
  • 符合 Section 508 标准
  • 屏幕阅读器支持（NVDA、JAWS、VoiceOver）
• ARIA 属性：
  • role="toolbar"
  • aria-label、aria-orientation
  • aria-expanded、aria-haspopup
• 键盘导航：
  • allowKeyboard 属性控制
  • 方向键（左/右）导航
  • Home/End 键
  • 使用 Tab/Shift+Tab 移动焦点
  • 使用 Enter/Space 激活
  • 使用 Escape 关闭弹出框
• keyDown 事件处理：
  • 事件参数（currentItem、nextItem、originalEvent）
  • 自定义键盘快捷键
  • 阻止默认导航
  • 特定按键操作
• 屏幕阅读器支持和测试
• 符合 WCAG 的颜色对比度
• 移动设备/触摸无障碍
• RTL 支持
• ARIA 最佳实践
• 测试清单和工具

5. 项目配置（续）

文件： references/item-configuration.md

• 按钮属性参考
• 分隔符样式
• 输入组件（NumericTextBox、DropDownList、CheckBox、RadioButton）
• 标签页导航控件
• 完整工具栏示例

6. 样式与自定义

文件： references/styling-customization.md

• CSS 类结构：
  • .e-toolbar - 容器
  • .e-toolbar-item - 项目包装器
  • .e-tbar-btn - 按钮
  • .e-icons - 图标元素
  • .e-separator - 分隔符
  • .e-toolbar-pop - 弹出窗口
• 工具栏容器样式
• 项目和按钮样式
• 图标样式与自定义
• 状态样式（悬停、焦点、活动、禁用）
• 主题集成（Tailwind、Bootstrap、Fluent、Material）
• 弹出窗口自定义 CSS 类：
  • .e-toolbar-pop - 弹出窗口容器
  • .e-overflow-button - 下拉切换按钮
  • .e-overflow-show - 显示优先级项目
  • .e-overflow-hide - 隐藏优先级项目
  • .e-popup-text - 弹出窗口文本样式
  • .e-toolbar-text - 工具栏文本样式
• 自定义样式示例
• 性能优化
• 完整样式示例

7. 高级功能与模板

文件： references/advanced-features.md

• 模板配置：
  • 模板基础知识（函数/JSX）
  • 模板属性
  • 何时使用模板
• 逐项自定义模板：
  • 单个项目模板
  • 多个不同模板
  • 模板内的状态
  • 模板样式
• 无状态模板：
  • 性能优化
  • CSS 类自定义
  • 弹出窗口自定义对应项
• 切换按钮：
  • 单个切换状态
  • 切换按钮组（类似单选按钮）
  • CSS 样式
• 链接项目：
  • 导航链接
  • 外部链接
  • 面包屑模式
• 工具提示：
  • HTML title 属性
  • 自定义工具提示组件
  • 样式与位置
• 渲染其他组件：
  • Syncfusion 组件（DropDownList、NumericTextBox、ColorPicker）
  • React 组件
  • 自定义组件
• 命令自定义：
  • 点击处理程序
  • 上下文菜单
  • 自定义操作
• 动态项目管理：
  • addItems() - 运行时添加项目
  • removeItems() - 按索引或 ID 移除
  • enableItems() - 启用/禁用项目
  • hideItem() - 显示/隐藏项目
  • disable() - 禁用整个工具栏
  • destroy() - 清理
  • refreshOverflow() - 重新计算布局
• 事件处理：
  • beforeCreate - 初始化前自定义
  • created - 初始化后回调
  • clicked - 项目点击事件，包含 ClickEventArgs
  • keyDown - 键盘事件，包含 KeyDownEventArgs
  • destroyed - 清理事件
• 滚动步长自定义：
  • 控制滚动距离
  • 动态滚动步长
  • 触摸滑动行为
• 完整高级示例

---

文档与导航指南

快速入门

📄 阅读： references/getting-started.md

• 软件包安装与依赖项
• 使用 Vite 和 React 进行设置
• CSS 导入与主题配置
• 使用 ItemsDirective 创建基本工具栏
• HTML 元素初始化
• 运行开发服务器

项目配置与类型

📄 阅读： references/item-configuration.md

• 带属性的按钮项目类型（文本、图标、宽度、对齐方式）
• 分隔符项目类型
• 用于组件的输入项目类型
• 使用 tabIndex 进行 Tab 键导航
• 完整的可运行示例

响应模式

📄 阅读： references/responsive-modes.md

• 可滚动模式（默认行为）
• 弹出窗口溢出模式
• 命令优先级（显示、隐藏、无）
• 文本显示选项
• 导航与交互模式

无障碍功能与键盘支持

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• ARIA 属性和角色
• 键盘导航键
• 屏幕阅读器支持
• 移动设备无障碍功能

样式与自定义

📄 阅读： references/styling-customization.md

• CSS 自定义模式
• 工具栏和项目样式
• 图标和按钮自定义
• 悬停和聚焦状态
• 主题集成

高级功能与模板

📄 阅读： references/advanced-features.md

• 模板配置和模式
• 按项目自定义模板
• 切换按钮
• 链接项目
• 工具提示
• 渲染其他 Syncfusion 组件
• 命令和滚动自定义

---

快速入门示例

import { ItemDirective, ItemsDirective, ToolbarComponent } from '@syncfusion/ej2-react-navigations';
import './App.css';

const App = () => {
  return (
    <ToolbarComponent id='toolbar'>
      <ItemsDirective>
        <ItemDirective text="Cut" prefixIcon="e-cut-icon" />
        <ItemDirective text="Copy" prefixIcon="e-copy-icon" />
        <ItemDirective text="Paste" prefixIcon="e-paste-icon" />
        <ItemDirective type="Separator" />
        <ItemDirective text="Bold" prefixIcon="e-bold-icon" />
        <ItemDirective text="Italic" prefixIcon="e-italic-icon" />
        <ItemDirective text="Underline" prefixIcon="e-underline-icon" />
      </ItemsDirective>
    </ToolbarComponent>
  );
};

export default App;

App.css 中必需的 CSS 导入：

@import '../node_modules/@syncfusion/ej2-base/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-react-navigations/styles/tailwind3.css';

---

常见模式

包含按钮和分隔符的基本工具栏

创建一个简单的工具栏，其中包含按钮命令，并在各组之间添加视觉分隔符：

<ToolbarComponent>
  <ItemsDirective>
    {/* Edit commands */}
    <ItemDirective text="Cut" />
    <ItemDirective text="Copy" />
    <ItemDirective type="Separator" />
    {/* Format commands */}
    <ItemDirective text="Bold" />
    <ItemDirective text="Italic" />
  </ItemsDirective>
</ToolbarComponent>

带图标的工具栏

使用 prefixIcon 为按钮添加图标，以获得更好的视觉效果：

<ItemDirective text="Save" prefixIcon="e-save-icon" />
<ItemDirective text="Print" prefixIcon="e-print-icon" />

响应式溢出处理

选择 Scrollable（默认）以连续显示，或选择 Popup 以紧凑方式显示溢出内容：

{/* Scrollable mode with navigation arrows */}
<ToolbarComponent overflowMode="Scrollable">
  {/* items */}
</ToolbarComponent>

{/* Popup mode with dropdown */}
<ToolbarComponent overflowMode="Popup">
  {/* items */}
</ToolbarComponent>

带输入组件的工具栏

在工具栏项目中包含下拉菜单等交互组件：

<ItemDirective type="Input" template={<DropDownComponent {...props} />} />

---

主要属性

属性	类型	描述
id	string	工具栏的唯一标识符
overflowMode	"Scrollable" | "Popup"	溢出项目的处理方式
width	string	工具栏容器的宽度
items	ItemModel[]	工具栏项目数组
text	string	按钮项目的显示文本
prefixIcon	string	前缀位置的图标类
suffixIcon	string	后缀位置的图标类
type	"Button" | "Separator" | "Input"	项目类型
align	"Left" | "Center" | "Right"	项目对齐方式
overflow	"Show" | "Hide" | "None"	Popup 模式的优先级
tabIndex	number	Tab 导航顺序
template	function	项目的自定义模板

---

常见用例

1. 文本编辑器工具栏

   • 格式按钮（粗体、斜体、下划线）
   • 对齐选项
   • 颜色和字体选择器
   • 参见：responsive-modes.md、advanced-features.md

2. 文件操作工具栏

   • 新建、打开、保存、另存为按钮
   • 打印功能
   • 撤销/重做命令
   • 参见：item-configuration.md、advanced-features.md

3. 响应式移动工具栏

   • 使用 Popup 溢出模式实现紧凑显示
   • 使用 Scrollable 模式实现连续访问
   • 参见：responsive-modes.md

4. 无障碍命令栏

   • 支持键盘导航
   • ARIA 属性
   • 便于屏幕阅读器使用
   • 参见：accessibility.md

5. 自定义品牌工具栏

   • 自定义 CSS 样式
   • 主题集成
   • 公司专属图标
   • 参见：styling-customization.md

---

总结

Toolbar 组件为 React 应用中的命令组织和执行提供了全面的解决方案。请从 getting-started.md 开始进行基本设置，然后根据需求探索特定功能。对于模板自定义和复杂场景，请使用 advanced-features.md。

导航路径：

1. 入门 → 设置基本工具栏
2. 项目配置 → 添加不同类型的项目
3. 响应式模式 → 处理溢出
4. 无障碍功能 → 确保支持键盘操作
5. 样式 → 自定义外观
6. 高级功能 → 模板和自定义组件