syncfusion-javascript-toolbar

实现 Syncfusion TypeScript Toolbar

概述

Syncfusion TypeScript Toolbar 是一个导航组件，用于水平显示一组命令按钮。它基于 Essential JS 2 构建，提供专业级工具栏功能，具备响应式行为、模板支持和丰富的自定义选项。

主要功能一览

• 多种溢出模式：Scrollable、Popup、MultiRow 和 Extended 模式，灵活管理内容
• 响应式设计：提供多种布局选项，可自动适配不同屏幕尺寸
• 多种项目类型：按钮、分隔符和输入组件（NumericTextBox、DropDownList 等）
• 模板支持：从 HTML 元素或项目集合渲染工具栏
• 丰富的自定义选项：CSS 样式、图标、工具提示和模板
• 键盘支持：全面支持键盘导航并符合无障碍要求
• RTL 支持：内置从右向左语言支持
• 事件处理：支持 beforeCreate、clicked、keyDown 事件，并提供全面的事件参数
• 主题集成：适用于 Fluent2 和其他主题系统
• 安全功能：对用户提供的内容进行 HTML 清理和 XSS 防护

何时使用此技能

在以下需求中选择 Syncfusion Toolbar：

• 为编辑器、文档工具或应用菜单创建命令按钮界面
• 创建可适配移动设备和桌面尺寸的响应式导航
• 创建具有可自定义图标和样式的专业级工具栏
• 创建符合无障碍要求的导航组件
• 基于模板渲染工具栏
• 管理项目状态（启用/禁用、切换状态）
• 为工具栏项目提供工具提示支持

文档与导航指南

入门

📄 阅读： references/getting-started.md

从这里开始，完成你的第一个 Toolbar 实现：

• 安装和配置 NPM 包
• 配置 TypeScript 依赖项
• 导入 CSS 并设置主题
• 使用项目进行基本的 Toolbar 初始化
• 第一个可运行的代码示例
• 使用 webpack 配置

项目配置

📄 阅读： references/item-configuration.md

了解如何构建和配置单个工具栏项目：

• 带文本、图标和 prefixIcon/suffixIcon 的按钮项目
• 用于视觉分组的分隔符项目
• 用于集成组件（NumericTextBox、DropDownList）的输入项目
• 项目对齐和定位
• 项目 ID 和动态项目访问
• 宽度和尺寸属性

响应式和弹出模式

📄 阅读： references/responsive-and-popup.md

处理工具栏溢出和响应式行为：

• Scrollable 模式，支持导航箭头和触摸滑动
• 适用于紧凑布局的 Popup 模式
• 根据可用空间切换显示模式
• 自定义基于箭头滚动的滚动步长
• 触摸和键盘交互模式
• 响应式宽度配置

模板与自定义

📄 阅读： references/template-and-customization.md

创建自定义工具栏布局和样式：

• 基于 HTML 模板渲染工具栏
• 自定义项目级模板
• 应用 CSS 类进行样式设置
• 使用 HTML 内容创建自定义按钮模板
• 高级布局模式和示例
• 与主题集成样式

交互与命令

📄 阅读： references/interactivity-and-commands.md

处理用户交互和命令执行：

• 点击事件处理模式
• 自定义和执行命令
• 实现切换按钮
• 通过编程方式启用/禁用项目
• 事件绑定和事件参数
• 项目状态管理

高级功能

📄 阅读： references/advanced-features.md

实现高级工具栏功能：

• Font Awesome 图标集成
• 配置工具栏项的工具提示
• 支持从右向左（RTL）的语言
• 键盘导航模式
• 符合无障碍（WAI-ARIA）规范
• 工具栏项内的链接
• 多行工具栏布局

样式与无障碍

📄 阅读： references/styling-and-accessibility.md

掌握样式和无障碍功能的实现：

• 用于自定义工具栏的 CSS 结构
• 主题类（工具栏、项、按钮、图标）
• 自定义颜色和外观
• 符合 WCAG 规范的要求
• 键盘导航实现
• 屏幕阅读器支持和 ARIA 属性
• 无障碍工具栏的最佳实践

完整 API 参考

📄 阅读： references/api-reference.md

所有 Toolbar API 的完整参考：

• ToolbarModel 属性表（12 个以上属性及示例）
• ItemModel 属性表（15 个以上属性及示例）
• 事件参考（beforeCreate、clicked、created、destroyed、keyDown）
• 事件参数文档（BeforeCreateArgs、ClickEventArgs、KeyDownEventArgs）
• 枚举参考（ItemType、ItemAlign、OverflowOption、OverflowMode、DisplayMode）
• 常见场景的快速配置模式

快速入门示例

以下是一个最精简的可运行示例，助你快速上手：

import { Toolbar } from '@syncfusion/ej2-navigations';

// Create a basic toolbar with button items
let toolbar: Toolbar = new Toolbar({
    items: [
        { text: 'Cut' },
        { text: 'Copy' },
        { text: 'Paste' },
        { type: 'Separator' },
        { text: 'Bold' },
        { text: 'Italic' },
        { text: 'Underline' }
    ]
});

// Render to DOM element
toolbar.appendTo('#element');

HTML 容器：

<!DOCTYPE html>
<html>
<head>
    <link href="url" rel="stylesheet" />
</head>
<body>
    <div id="element"></div>
    <script src="app.js"></script>
</body>
</html>

常见模式

模式 1：带图标的工具栏

let toolbar: Toolbar = new Toolbar({
    items: [
        { prefixIcon: 'e-icons e-cut', text: 'Cut' },
        { prefixIcon: 'e-icons e-copy', text: 'Copy' },
        { prefixIcon: 'e-icons e-paste', text: 'Paste' },
        { type: 'Separator' },
        { prefixIcon: 'e-icons e-bold', text: 'Bold' }
    ]
});
toolbar.appendTo('#element');

模式 2：响应式工具栏（可滚动）

let toolbar: Toolbar = new Toolbar({
    width: 600,
    overflowMode: 'Scrollable',
    items: [
        { text: 'Cut', prefixIcon: 'e-cut-icon' },
        { text: 'Copy', prefixIcon: 'e-copy-icon' },
        { text: 'Paste', prefixIcon: 'e-paste-icon' },
        // ... more items
    ]
});
toolbar.appendTo('#element');

模式 3：项对齐控制

let toolbar: Toolbar = new Toolbar({
    items: [
        { text: 'Cut' },
        { text: 'Copy' },
        { type: 'Separator' },
        { text: 'Save', align: 'Right' },  // Push to right side
        { text: 'Help', align: 'Right' }
    ]
});
toolbar.appendTo('#element');

模式 4：事件处理

let toolbar: Toolbar = new Toolbar({
    items: [
        { id: 'cut-btn', text: 'Cut' },
        { id: 'copy-btn', text: 'Copy' }
    ],
    clicked: (args: ClickEventArgs) => {
        console.log(`Item ${args.item.id} clicked`);
    }
});
toolbar.appendTo('#element');

重要属性参考

属性	类型	用途
items	ItemModel[]	要显示的工具栏项数组
width	Number/String	工具栏宽度（像素或百分比）
overflowMode	'Scrollable' | 'Popup'	溢出内容的处理方式
scrollStep	Number	点击箭头时滚动的像素数（Scrollable 模式）
enableRtl	Boolean	为 RTL 语言启用从右向左的布局
clicked	Function	项点击事件的处理函数

常见使用场景

使用场景 1：文本编辑器工具栏

• 显示剪切、复制、粘贴、加粗、斜体、下划线按钮
• 使用 prefixIcon 属性设置图标
• 添加分隔符进行视觉分组
• 为每个命令实现点击处理函数

使用场景 2：适配移动设备的工具栏

• 在移动设备上将 overflowMode 设为 Popup
• 为桌面设备配置可滚动模式
• 使用响应式宽度（按百分比设置）
• 在不同屏幕尺寸上进行测试

使用场景 3：自定义外观

• 应用带有主题颜色的 CSS 类
• 使用 Font Awesome 图标，打造现代外观
• 添加工具提示以提升无障碍体验
• 为不同的工具栏项设置不同样式

安装先决条件

必需的软件包：

npm install @syncfusion/ej2-navigations
npm install @syncfusion/ej2-base
npm install @syncfusion/ej2-buttons
npm install @syncfusion/ej2-popups

对于 TypeScript 项目，请确保 webpack 和 TypeScript 已正确配置（建议使用 node v14.15.0 或更高版本）。

---

**注意：**如需了解任何主题的更多详情，请参阅上方导航指南中链接的相应参考文件。每份参考资料都提供完整的代码示例、边界情况和故障排除指南。