syncfusion-angular-toolbar

实现 Syncfusion Angular 工具栏

显示一组水平排列的命令按钮，并支持响应式溢出处理和丰富的自定义选项。

何时使用此技能

在以下情况下使用此技能：

• 创建水平工具栏布局中的操作按钮
• 在按钮组之间添加分隔符
• 嵌入输入组件（NumericTextBox、DropDownList、CheckBox）
• 使用 CSS 和 Font Awesome 图标自定义样式
• 处理点击事件和命令交互
• 在工具栏项中渲染自定义模板和组件
• 为工具栏命令设置工具提示
• 将路由链接添加为工具栏项
• 创建带状态管理的切换按钮
• 实现响应式滚动或弹出溢出模式
• 构建支持键盘导航的无障碍工具栏

工具栏概览

Syncfusion Angular 工具栏是一种容器组件，可水平显示一组命令按钮。它支持多种项类型（按钮、分隔符、输入项）、自定义模板、样式设置、响应式行为和无障碍功能。

主要功能：

• 按钮项： 默认项类型，支持文本、图标和样式
• 分隔符： 在命令组之间添加垂直分隔
• 输入组件： 嵌入 NumericTextBox、DropDownList、CheckBox、RadioButton
• 模板支持： 渲染 Angular 组件和自定义 HTML
• 响应式模式： 可滚动（默认）和弹出式溢出处理
• 自定义样式： CSS 自定义、Font Awesome 集成、主题
• 工具提示： 鼠标悬停时显示所有命令的提示文本
• 链接： 嵌入路由链接和锚点元素
• 切换按钮： 支持播放/暂停、显示/隐藏功能的有状态按钮
• 键盘导航： 支持 Tab 键和方向键导航
• RTL 支持： 支持从右到左的文本和布局方向
• 无障碍功能： 符合 WCAG 标准并支持 ARIA 属性

文档和导航指南

快速入门

📄 阅读： references/getting-started.md

• 安装 @syncfusion/ej2-angular-navigations 包
• 设置 Angular 环境和依赖项
• 在组件中导入 ToolbarModule
• 添加主题 CSS 导入
• 使用按钮项创建基本工具栏
• 运行并测试应用程序

项配置

📄 阅读： references/item-configuration.md

• 配置按钮项属性（text、id、prefixIcon、suffixIcon、width、align）
• 添加分隔符项以对命令分组
• 设置 Input 类型项（NumericTextBox、DropDownList、CheckBox、RadioButton）
• 使用 tabIndex 属性启用 Tab 键导航
• 动态管理和更新项

样式与自定义

📄 阅读： references/styling-customization.md

• 使用 CSS 自定义工具栏容器样式
• 设置工具栏项和按钮的样式
• 自定义图标和图标颜色
• 应用悬停和焦点状态样式
• 集成 Font Awesome 第三方图标
• CSS 类自定义（e-toolbar、e-toolbar-item、e-tbar-btn）
• 使用 e-icons 类设置图标位置

命令事件与自定义

📄 阅读： references/command-events.md

• 为工具栏项实现点击事件处理程序
• 使用 htmlAttributes 属性设置自定义 HTML 属性
• 使用 cssClass 属性应用多个 CSS 类
• 使用 id、class、style、role 属性自定义命令
• 使用事件驱动模式处理工具栏交互
• 处理特定项的操作和响应

项模板与组件

📄 阅读： references/item-templates.md

• 使用 template 属性自定义项的渲染方式
• 使用 ng-template 指令渲染 Angular 组件
• 将复选框和输入模板设为字符串字面量
• 使用查询选择器引用模板
• 在工具栏中集成 Menu 组件
• 渲染多个组件（NumericTextBox、DatePicker、Button）
• 自定义 HTML 模板结构

工具提示与链接

📄 阅读： references/tooltips-links.md

• 设置 tooltipText 属性，以便在悬停时显示提示文本
• 使用目标选择器导入并初始化 Tooltip 模块
• 使用 ng-template 添加锚点元素
• 在工具栏项中创建路由链接
• 实现具有状态变化的切换按钮
• 播放/暂停、显示/隐藏和筛选切换模式
• 确保链接和按钮状态的无障碍访问

响应式布局与滚动

📄 阅读： references/responsive-scrolling.md

• 可滚动溢出模式（默认），带导航箭头
• 在设备上使用触摸滑动手势进行滚动
• 使用弹出式溢出模式，实现针对移动设备优化的显示
• 自定义 scrollStep 属性以设置滚动距离
• 项目超出容器宽度时处理溢出
• 导航图标的禁用状态和行为
• 长按导航，实现连续滚动

高级功能

📄 阅读： references/advanced-features.md

• 将相关工具栏按钮分组
• 嵌套项和层级结构
• 使用方向键和 Tab 键进行键盘导航
• 符合 WCAG 无障碍访问规范并支持 ARIA 属性
• 支持 RTL（从右向左）语言
• 针对大型工具栏进行性能优化
• 内置对 WAI-ARIA 规范的支持

完整 API 参考

📄 阅读： references/api-reference.md

• 工具栏组件属性（12 个属性）
  • allowKeyboard、cssClass、enableCollision、enableHtmlSanitizer、enablePersistence
  • enableRtl、height、items、locale、overflowMode、scrollStep、width
• 工具栏事件（5 个事件）
  • beforeCreate (BeforeCreateArgs)、clicked (ClickEventArgs)、created、keyDown (KeyDownEventArgs)、destroyed
• 工具栏方法（7 个方法）
  • addItems、destroy、disable、enableItems、hideItem、refreshOverflow、removeItems
• 项配置属性（19 个以上属性）
  • align、cssClass、disabled、htmlAttributes、id、overflow、prefixIcon、suffixIcon
  • showAlwaysInPopup、showTextOn、tabIndex、template、text、tooltipText、type、visible、width
• 类型与枚举（5 个枚举）
  • ItemType、ItemAlign、OverflowMode、OverflowOption、DisplayMode
• 完整 API 示例
  • 包含所有功能的高级工具栏
  • 带动态配置的响应式工具栏

快速入门示例

import { ToolbarModule } from '@syncfusion/ej2-angular-navigations';
import { Component } from '@angular/core';

@Component({
  imports: [ToolbarModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-toolbar>
      <e-items>
        <e-item text='Cut'></e-item>
        <e-item text='Copy'></e-item>
        <e-item type='Separator'></e-item>
        <e-item text='Paste'></e-item>
        <e-item type='Separator'></e-item>
        <e-item text='Bold'></e-item>
        <e-item text='Italic'></e-item>
        <e-item text='Underline'></e-item>
      </e-items>
    </ejs-toolbar>
  `
})
export class AppComponent { }

在 styles.css 中添加 CSS 导入：

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

常见模式

模式 1：简单文本按钮

<e-item text='Cut'></e-item>
<e-item text='Copy'></e-item>
<e-item text='Paste'></e-item>

适用场景： 需要带文本标签的基本操作按钮时。

---

模式 2：带文本的图标按钮

<e-item text='Bold' prefixIcon='e-icons e-bold'></e-item>
<e-item text='Italic' prefixIcon='e-icons e-italic'></e-item>
<e-item text='Undo' suffixIcon='e-icons e-undo'></e-item>

适用场景： 希望在文本标签前后显示视觉图标时。

---

模式 3：带分隔符的分组命令

<e-item text='Cut'></e-item>
<e-item text='Copy'></e-item>
<e-item type='Separator'></e-item>
<e-item text='Paste'></e-item>
<e-item type='Separator'></e-item>
<e-item text='Bold'></e-item>
<e-item text='Italic'></e-item>

适用场景： 需要将相关命令进行视觉分组时。

---

模式 4：带输入组件的工具栏

<e-item type='Input'>
  <ng-template #template>
    <ejs-numerictextbox value="10" width="150"></ejs-numerictextbox>
  </ng-template>
</e-item>
<e-item type='Input'>
  <ng-template #template>
    <ejs-dropdownlist [dataSource]='data' width="120"></ejs-dropdownlist>
  </ng-template>
</e-item>

适用场景： 需要在工具栏中使用输入字段、下拉菜单或其他控件时。

---

模式 5：带复选框的自定义模板

<e-item>
  <ng-template #template>
    <input type='checkbox' id='check1' checked=''>
    <label for='check1'>Enable Feature</label>
  </ng-template>
</e-item>

适用场景： 需要使用复选框或自定义控件等自定义 HTML 元素时。

---

模式 6：工具栏中的链接

<e-item>
  <ng-template #template>
    <a href="url" target="_blank">Documentation</a>
  </ng-template>
</e-item>

适用场景： 需要将可点击链接添加为工具栏项时。

---

模式 7：悬停提示

<ejs-tooltip target='#Toolbar [title]'>
  <ejs-toolbar id='Toolbar'>
    <e-items>
      <e-item text='Cut' tooltipText='Cut selected content'></e-item>
      <e-item text='Paste' tooltipText='Paste copied content'></e-item>
    </e-items>
  </ejs-toolbar>
</ejs-tooltip>

适用场景： 希望在鼠标悬停时显示提示文本时。

---

模式 8：响应式可滚动工具栏

<ejs-toolbar width="300px">
  <e-items>
    <e-item text='Cut'></e-item>
    <e-item text='Copy'></e-item>
    
  </e-items>
</ejs-toolbar>

适用场景： 容器宽度小于内容总宽度，因而触发可滚动模式时。

---

模式 9：带状态的切换按钮

<ng-template #template>
  <button ejs-button class="e-btn" iconCss="e-play-icon" 
    isToggle="true" (click)="onPlayClick()"></button>
</ng-template>

适用场景： 需要切换状态的按钮（播放/暂停、显示/隐藏）时。

---

模式 10：Font Awesome 图标

<link rel="stylesheet" href="url" />

<e-item prefixIcon="fa fa-twitter"></e-item>
<e-item prefixIcon="fa fa-facebook"></e-item>

适用场景： 需要使用 Font Awesome 等第三方图标时。

---

关键属性

属性	类型	用途	示例
text	string	按钮显示文本	text='Cut'
type	string	项目类型（Button、Separator、Input）	type='Separator'
prefixIcon	string	文本前图标的 CSS 类	prefixIcon='e-icons e-cut'
suffixIcon	string	文本后图标的 CSS 类	suffixIcon='e-icons e-undo'
id	string	唯一项目标识符	id='item1'
width	string	按钮宽度	width='100px'
align	string	项目对齐方式（Left、Center、Right）	align='Right'
tooltipText	string	悬停时显示的提示文本	tooltipText='Cut'
cssClass	string	要应用的 CSS 类	cssClass='custom-btn'
htmlAttributes	object	自定义 HTML 属性	[htmlAttributes]='{class: "custom"}'
template	string|object	自定义模板内容	[template]='templateVar'
tabIndex	number	Tab 键导航顺序	tabIndex=1
scrollStep	number	滚动距离（像素）	scrollStep='50'

常见用例

1. 文本编辑器工具栏 - 粗体、斜体、下划线按钮及分隔符
2. 文件操作 - 剪切、复制、粘贴、撤销、重做按钮
3. 工具栏中的搜索栏 - 在容器宽度范围内用于搜索的输入框
4. 格式设置选项 - 字体大小、颜色选择器、对齐按钮
5. 导航工具栏 - 指向不同区域或页面的链接
6. 移动应用页眉 - 在紧凑、可滚动布局中显示带工具提示的图标
7. 文档查看器 - 放大/缩小、打印、下载切换项
8. 富文本编辑器 - 配有模板和输入框的完整格式设置工具栏
9. 仪表板控件 - 日期选择器、筛选器、排序选项
10. 社交媒体分享 - 工具栏中的 Font Awesome 社交图标