syncfusion-react-toolbar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Toolbar

实现Syncfusion React Toolbar

Component Overview

组件概述

The Syncfusion React Toolbar component provides a flexible command bar for organizing and executing commands. It supports multiple item types (buttons, separators, inputs), responsive overflow modes, and comprehensive accessibility features.

Key Capabilities:

Multiple item types: Button, Separator, Input
Responsive overflow modes: Scrollable, Popup, MultiRow, Extended
Built-in keyboard navigation and ARIA support
Component rendering within toolbar items
Customizable appearance and behavior
Tab key navigation support
Dynamic item management (add/remove/enable/disable)
Rich event system (beforeCreate, clicked, keyDown, created, destroyed)
Full RTL and locale support
Stateless template rendering

Syncfusion React Toolbar组件为组织和执行命令提供了灵活的命令栏。它支持多种项类型（按钮、分隔符、输入框）、响应式溢出模式以及全面的无障碍功能。

核心功能：

多种项类型：按钮、分隔符、输入框
响应式溢出模式：滚动式、弹出式、多行式、扩展式
内置键盘导航和ARIA支持
工具栏项内渲染组件
可自定义外观与行为
Tab键导航支持
动态项管理（添加/移除/启用/禁用）
丰富的事件系统（beforeCreate、clicked、keyDown、created、destroyed）
完整的RTL（从右到左）和本地化支持
无状态模板渲染

Complete Table of Contents

完整目录

1. Getting Started

1. 快速入门

File: references/getting-started.md

Dependencies setup
Project initialization (Vite/CRA)
Package installation
CSS theme imports (Tailwind, Bootstrap, Fluent, Material)
Basic implementation examples
Global configuration:
- Locale support for internationalization
- RTL (Right-to-Left) layout
- Persistence settings
- Collision detection
- HTML sanitizer
Development server setup

文件： references/getting-started.md

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

2. Item Configuration

2. 项配置

File: references/item-configuration.md

ItemModel API Reference:
- Complete interface structure
- All 16 properties with types
- Property reference with descriptions
- Items array configuration patterns
- Configuration examples (simple, grouped, conditional, accessible)
Button item type with properties:
- ```
text
```
  - Display text
- ```
id
```
  - Unique identifier
- ```
prefixIcon
```
  /
```
suffixIcon
```
  - Icons positioning
- ```
width
```
  - Custom width
- ```
align
```
  - Alignment (Left/Center/Right)
- ```
disabled
```
  - Disabled state
- ```
visible
```
  - Visibility control
- ```
cssClass
```
  - Custom CSS classes
- ```
htmlAttributes
```
  - HTML attributes
- ```
overflow
```
  - Priority display (Show/Hide/None)
- ```
showAlwaysInPopup
```
  - Force popup display
- ```
showTextOn
```
  - Text display mode (Both/Overflow/Toolbar)
Separator item type
Input item type for components
Tab navigation with
```
tabIndex
```
Complete working examples

文件： references/item-configuration.md

ItemModel API参考：
- 完整接口结构
- 全部16个属性及类型
- 属性参考及描述
- 项数组配置模式
- 配置示例（简单、分组、条件化、无障碍）
按钮项类型及属性：
- ```
text
```
  - 显示文本
- ```
id
```
  - 唯一标识符
- ```
prefixIcon
```
  /
```
suffixIcon
```
  - 图标位置
- ```
width
```
  - 自定义宽度
- ```
align
```
  - 对齐方式（左/中/右）
- ```
disabled
```
  - 禁用状态
- ```
visible
```
  - 可见性控制
- ```
cssClass
```
  - 自定义CSS类
- ```
htmlAttributes
```
  - HTML属性
- ```
overflow
```
  - 优先级显示（显示/隐藏/无）
- ```
showAlwaysInPopup
```
  - 强制在弹出框中显示
- ```
showTextOn
```
  - 文本显示模式（两者/溢出时/工具栏）
分隔符项类型
用于组件的输入项类型
使用
```
tabIndex
```
进行Tab导航
完整可运行示例

3. Responsive Modes

3. 响应式模式

File: references/responsive-modes.md

Scrollable Mode (default)
- Horizontal scrolling with navigation arrows
- Touch swipe support
- Keyboard arrow navigation
- Use cases: many items, large screens
Popup Mode
- Dropdown overflow container
- Command priority control
- Compact appearance
- Use cases: limited space, mobile
MultiRow Mode
- Item wrapping to multiple rows
- No scrolling needed
- All items visible
- Use cases: responsive width containers
Extended Mode
- Multi-row with horizontal scrolling
- Row-level navigation
- Use cases: many items in limited width
Command priority (Show/Hide/None)
Text display options (Both/Overflow/Toolbar)
Mode comparison table
Practical examples for each mode

文件： references/responsive-modes.md

滚动模式（默认）
- 带导航箭头的水平滚动
- 触摸滑动支持
- 键盘箭头导航
- 使用场景：项数量多、大屏幕
弹出模式
- 下拉溢出容器
- 命令优先级控制
- 紧凑外观
- 使用场景：空间有限、移动端
多行模式
- 项自动换行到多行
- 无需滚动
- 所有项可见
- 使用场景：响应式宽度容器
扩展模式
- 多行+水平滚动
- 行级导航
- 使用场景：有限宽度内包含多项
命令优先级（显示/隐藏/无）
文本显示选项（两者/溢出时/工具栏）
模式对比表
每种模式的实用示例

4. Accessibility & Keyboard Support

4. 无障碍与键盘支持

File: references/accessibility.md

Compliance standards:
- WCAG 2.2 Level AA
- Section 508 compliance
- Screen reader support (NVDA, JAWS, VoiceOver)

ARIA attributes:

```
role="toolbar"
```
```
aria-label
```
,
```
aria-orientation
```
```
aria-expanded
```
,
```
aria-haspopup
```

Keyboard navigation:
- allowKeyboard property control
- Arrow keys (Left/Right) navigation
- Home/End keys
- Tab/Shift+Tab for focus
- Enter/Space for activation
- Escape to close popups
keyDown Event handling:
- Event parameters (currentItem, nextItem, originalEvent)
- Custom keyboard shortcuts
- Preventing default navigation
- Key-specific actions
Screen reader support and testing
Color contrast WCAG compliance
Mobile/touch accessibility
RTL support
ARIA best practices
Testing checklist and tools

文件： references/accessibility.md

合规标准：
- WCAG 2.2 Level 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. Item Configuration (Continued)

5. 项配置（续）

File: references/item-configuration.md

Button properties reference
Separator styling
Input components (NumericTextBox, DropDownList, CheckBox, RadioButton)
Tab navigation control
Complete toolbar examples

文件： references/item-configuration.md

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

6. Styling & Customization

6. 样式与自定义

File: references/styling-customization.md

CSS class structure:
- ```
.e-toolbar
```
  - Container
- ```
.e-toolbar-item
```
  - Item wrapper
- ```
.e-tbar-btn
```
  - Button
- ```
.e-icons
```
  - Icon element
- ```
.e-separator
```
  - Separator
- ```
.e-toolbar-pop
```
  - Popup
Toolbar container styling
Item & button styling
Icon styling and customization
State styling (hover, focus, active, disabled)
Theme integration (Tailwind, Bootstrap, Fluent, Material)
Popup customization CSS classes:
- ```
.e-toolbar-pop
```
  - Popup container
- ```
.e-overflow-button
```
  - Dropdown toggle
- ```
.e-overflow-show
```
  - Show priority items
- ```
.e-overflow-hide
```
  - Hide priority items
- ```
.e-popup-text
```
  - Popup text styling
- ```
.e-toolbar-text
```
  - Toolbar text styling
Custom styling examples
Performance optimization
Complete styled examples

文件： 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. Advanced Features & Templates

7. 高级功能与模板

File: references/advanced-features.md

Template Configuration:
- Template basics (functions/JSX)
- Template properties
- When to use templates
Item-Wise Custom Templates:
- Single item templates
- Multiple different templates
- State within templates
- Template styling
Stateless Templates:
- Performance optimization
- CSS class customization
- Popup customization equivalents
Toggle Buttons:
- Single toggle state
- Toggle groups (radio-like)
- CSS styling
Link Items:
- Navigation links
- External links
- Breadcrumb patterns
Tooltips:
- HTML title attribute
- Custom tooltip components
- Styling and positioning
Rendering Other Components:
- Syncfusion components (DropDownList, NumericTextBox, ColorPicker)
- React components
- Custom components
Command Customization:
- Click handlers
- Context menus
- Custom actions
Dynamic Item Management:
- ```
addItems()
```
  - Add items at runtime
- ```
removeItems()
```
  - Remove by index or ID
- ```
enableItems()
```
  - Enable/disable items
- ```
hideItem()
```
  - Show/hide items
- ```
disable()
```
  - Disable entire toolbar
- ```
destroy()
```
  - Cleanup
- ```
refreshOverflow()
```
  - Recalculate layout
Event Handling:
- ```
beforeCreate
```
  - Pre-initialization customization
- ```
created
```
  - Post-initialization callback
- ```
clicked
```
  - Item click events with ClickEventArgs
- ```
keyDown
```
  - Keyboard events with KeyDownEventArgs
- ```
destroyed
```
  - Cleanup event
Scroll Step Customization:
- Control scroll distance
- Dynamic scroll step
- Touch swipe behavior
Complete advanced example

文件： 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
```
  - 清理事件
滚动步长自定义：
- 控制滚动距离
- 动态滚动步长
- 触摸滑动行为
完整高级示例

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Package installation and dependencies
Setup with Vite and React
CSS imports and theme configuration
Basic toolbar with ItemsDirective
HTML element initialization
Running the development server

📄 阅读： references/getting-started.md

包安装与依赖项
Vite与React环境搭建
CSS导入与主题配置
使用ItemsDirective的基础工具栏
HTML元素初始化
运行开发服务器

Item Configuration & Types

项配置与类型

📄 Read: references/item-configuration.md

Button item type with properties (text, icons, width, align)
Separator item type
Input item type for components
Tab key navigation with tabIndex
Complete working examples

📄 阅读： references/item-configuration.md

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

Responsive Modes

响应式模式

📄 Read: references/responsive-modes.md

Scrollable mode (default behavior)
Popup overflow mode
Command priority (show, hide, none)
Text display options
Navigation and interaction patterns

📄 阅读： references/responsive-modes.md

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

Accessibility & Keyboard Support

无障碍与键盘支持

📄 Read: references/accessibility.md

WCAG 2.2 and Section 508 compliance
ARIA attributes and roles
Keyboard navigation keys
Screen reader support
Mobile device accessibility

📄 阅读： references/accessibility.md

WCAG 2.2与Section 508合规
ARIA属性与角色
键盘导航按键
屏幕阅读器支持
移动设备无障碍

Styling & Customization

样式与自定义

📄 Read: references/styling-customization.md

CSS customization patterns
Toolbar and item styling
Icon and button customization
Hover and focus states
Theme integration

📄 阅读： references/styling-customization.md

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

Advanced Features & Templates

高级功能与模板

📄 Read: references/advanced-features.md

Template configuration and patterns
Item-wise custom templates
Toggle buttons
Link items
Tooltips
Rendering other Syncfusion components
Command and scroll customization

📄 阅读： references/advanced-features.md

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

Quick Start Example

快速开始示例

jsx

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;

Required CSS imports in 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';

jsx

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导入：

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';

Common Patterns

常见模式

Basic Toolbar with Buttons and Separators

带按钮和分隔符的基础工具栏

Create a simple toolbar with button commands and visual separators between groups:

jsx

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

创建包含按钮命令和组间视觉分隔符的简单工具栏：

jsx

<ToolbarComponent>
  <ItemsDirective>
    {/* 编辑命令 */}
    <ItemDirective text="Cut" />
    <ItemDirective text="Copy" />
    <ItemDirective type="Separator" />
    {/* 格式命令 */}
    <ItemDirective text="Bold" />
    <ItemDirective text="Italic" />
  </ItemsDirective>
</ToolbarComponent>

Toolbar with Icons

带图标的工具栏

Use prefixIcon to add icons to buttons for better visual representation:

jsx

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

使用prefixIcon为按钮添加图标，提升视觉表现力：

jsx

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

Responsive Overflow Handling

响应式溢出处理

Choose between Scrollable (default) for continuous display or Popup for compact overflow:

jsx

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

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

在滚动式（默认）连续显示和弹出式紧凑溢出之间选择：

jsx

{/* 带导航箭头的滚动模式 */}
<ToolbarComponent overflowMode="Scrollable">
  {/* 项 */}
</ToolbarComponent>

{/* 带下拉框的弹出模式 */}
<ToolbarComponent overflowMode="Popup">
  {/* 项 */}
</ToolbarComponent>

Toolbar with Input Components

带输入组件的工具栏

Include interactive components like dropdowns within toolbar items:

jsx

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

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

jsx

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

Key Props

核心属性

Property	Type	Description
`id`	string	Unique identifier for the toolbar
`overflowMode`	"Scrollable" \| "Popup"	How to handle overflow items
`width`	string	Width of the toolbar container
`items`	ItemModel[]	Array of toolbar items
`text`	string	Display text for button items
`prefixIcon`	string	Icon class for prefix position
`suffixIcon`	string	Icon class for suffix position
`type`	"Button" \| "Separator" \| "Input"	Item type
`align`	"Left" \| "Center" \| "Right"	Item alignment
`overflow`	"Show" \| "Hide" \| "None"	Priority for popup mode
`tabIndex`	number	Tab navigation order
`template`	function	Custom template for items

属性	类型	描述
`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"	弹出模式下的优先级
`tabIndex`	number	Tab导航顺序
`template`	function	项的自定义模板

Common Use Cases

常见使用场景

Text Editor Toolbar
- Format buttons (Bold, Italic, Underline)
- Alignment options
- Color and font pickers
- See: responsive-modes.md, advanced-features.md
File Operations Toolbar
- New, Open, Save, Save As buttons
- Print functionality
- Undo/Redo commands
- See: item-configuration.md, advanced-features.md
Responsive Mobile Toolbar
- Popup overflow mode for compact display
- Scrollable mode for continuous access
- See: responsive-modes.md
Accessible Command Bar
- Keyboard navigation support
- ARIA attributes
- Screen reader friendly
- See: accessibility.md
Customized Branded Toolbar
- Custom CSS styling
- Theme integration
- Company-specific icons
- See: styling-customization.md

文本编辑器工具栏
- 格式按钮（粗体、斜体、下划线）
- 对齐选项
- 颜色和字体选择器
- 参考：responsive-modes.md、advanced-features.md
文件操作工具栏
- 新建、打开、保存、另存为按钮
- 打印功能
- 撤销/重做命令
- 参考：item-configuration.md、advanced-features.md
响应式移动端工具栏
- 弹出溢出模式实现紧凑显示
- 滚动模式实现连续访问
- 参考：responsive-modes.md
无障碍命令栏
- 键盘导航支持
- ARIA属性
- 屏幕阅读器友好
- 参考：accessibility.md
定制品牌工具栏
- 自定义CSS样式
- 主题集成
- 企业专属图标
- 参考：styling-customization.md

Summary

总结

The Toolbar component provides a comprehensive solution for command organization and execution in React applications. Start with getting-started.md for basic setup, then explore specific features based on your needs. Use advanced-features.md for template customization and complex scenarios.

Navigation Path:

Getting Started → Basic toolbar setup
Item Configuration → Add different item types
Responsive Modes → Handle overflow
Accessibility → Ensure keyboard support
Styling → Customize appearance
Advanced Features → Templates and custom components

Toolbar组件为React应用中的命令组织与执行提供了全面的解决方案。从getting-started.md开始进行基础搭建，然后根据需求探索特定功能。复杂场景下可参考advanced-features.md进行模板定制。

导航路径：

快速入门 → 基础工具栏搭建
项配置 → 添加不同类型的项
响应式模式 → 处理溢出
无障碍 → 确保键盘支持
样式 → 自定义外观
高级功能 → 模板与自定义组件