syncfusion-blazor-toolbar

Syncfusion Blazor 工具栏组件

Syncfusion Blazor 工具栏是一个多功能组件，可用于创建包含按钮、分隔符和自定义控件的交互式命令栏。它提供内置的响应式行为和灵活的项目配置。

何时使用此技能

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

• 创建包含按钮、图标和自定义控件的工具栏
• 构建带格式工具栏（粗体、斜体、对齐等）的文本编辑器
• 在应用程序中实现命令栏或操作栏
• 添加可适应不同屏幕尺寸的响应式工具栏
• 配置项目溢出行为（可滚动、弹出、多行）
• 创建具有对齐和间距功能的导航工具栏
• 添加切换按钮或有状态的工具栏项目
• 实现支持添加和移除项目功能的动态工具栏
• 自定义工具栏外观和样式
• 启用从右向左书写语言的 RTL 支持

组件概述

Blazor 工具栏组件的功能包括：

• 项目类型：按钮、分隔符、间隔项和自定义模板
• 响应模式：可滚动、弹出、多行和扩展溢出处理
• 对齐方式：支持间隔项的左对齐、居中对齐和右对齐
• 自定义：图标、工具提示、样式、模板和 RTL 支持
• 动态管理：以编程方式添加、移除、启用、禁用、显示和隐藏项目

文档和导航指南

入门

📄 阅读： references/getting-started.md

当用户需要：

• 安装和配置工具栏组件
• 添加 NuGet 包并注册服务
• 创建包含项目的基本工具栏
• 了解基本的 ToolbarItems 结构
• 设置 CSS 主题和脚本引用

项目配置和属性

📄 阅读： references/item-configuration.md

当用户需要：

• 配置项目属性（Text、PrefixIcon、SuffixIcon、Width 等）
• 设置项目对齐方式（左、居中、右）
• 定义项目类型（Button、Separator、Input、Spacer）
• 控制项目的可见性和启用状态
• 为工具栏项目添加工具提示
• 使用自定义 CSS 类或 HTML 属性
• 配置各个项目的溢出行为
• 集成其他 Syncfusion 组件（DropDownList、NumericTextBox 等）
• 详细了解全部 18 个项目属性

实用操作指南

📄 阅读： references/how-to-guides.md

当用户需要：

• 动态添加或移除工具栏项目
• 以编程方式启用或禁用工具栏项目
• 根据条件显示或隐藏工具栏项目
• 创建带状态管理的切换按钮
• 使用 HtmlAttributes 和 CssClass 自定义项目
• 为每个项目设置自定义模板
• 使用 SfTooltip 组件添加工具提示
• 使用 TabIndex 启用 Tab 键导航
• 自定义滚动距离

响应式行为和溢出模式

📄 阅读： references/responsive-mode.md

当用户需要：

• 配置工具栏溢出行为（Scrollable、Popup、MultiRow、Extended）
• 设置溢出处理的项目优先级
• 控制工具栏与弹出窗口中的文本显示方式（ShowTextOn）
• 实现带导航箭头的可滚动工具栏
• 创建带下拉溢出菜单的弹出工具栏
• 配置多行或扩展溢出布局
• 处理滚动的触摸手势

使用 Spacer 设置对齐和间距

📄 阅读： references/alignment-spacer.md

当用户需要：

• 使用 Spacer 将项目分别左对齐、居中对齐和右对齐
• 创建左对齐和右对齐模式
• 实现仅右对齐
• 了解何时使用 Spacer 而不是 Align 属性
• 在工具栏项目之间应用灵活间距

样式与自定义

📄 阅读： references/styling.md

用户需要：

• 自定义工具栏容器样式
• 设置工具栏项和按钮的样式
• 修改图标外观
• 自定义悬停和焦点状态
• 应用自定义主题
• 覆盖默认 CSS 类
• 为阿拉伯语、希伯来语或乌尔都语启用 RTL（从右到左）支持

快速入门示例

包含常用格式设置按钮的基础工具栏：

@using Syncfusion.Blazor.Navigations

<SfToolbar>
    <ToolbarItems>
        <ToolbarItem Text="Cut" PrefixIcon="e-icons e-cut"></ToolbarItem>
        <ToolbarItem Text="Copy" PrefixIcon="e-icons e-copy"></ToolbarItem>
        <ToolbarItem Text="Paste" PrefixIcon="e-icons e-paste"></ToolbarItem>
        <ToolbarItem Type="ItemType.Separator"></ToolbarItem>
        <ToolbarItem Text="Bold" PrefixIcon="e-icons e-bold"></ToolbarItem>
        <ToolbarItem Text="Italic" PrefixIcon="e-icons e-italic"></ToolbarItem>
        <ToolbarItem Text="Underline" PrefixIcon="e-icons e-underline"></ToolbarItem>
    </ToolbarItems>
</SfToolbar>

常见模式

模式 1：文本编辑器工具栏

包含对齐和间距设置的格式工具栏：

<SfToolbar Width="600">
    <ToolbarItems>
        <ToolbarItem Text="Bold" PrefixIcon="e-icons e-bold"></ToolbarItem>
        <ToolbarItem Text="Italic" PrefixIcon="e-icons e-italic"></ToolbarItem>
        <ToolbarItem Type="ItemType.Separator"></ToolbarItem>
        <ToolbarItem Type="ItemType.Spacer"></ToolbarItem>
        <ToolbarItem Text="Left" PrefixIcon="e-icons e-align-left"></ToolbarItem>
        <ToolbarItem Text="Center" PrefixIcon="e-icons e-align-center"></ToolbarItem>
        <ToolbarItem Text="Right" PrefixIcon="e-icons e-align-right"></ToolbarItem>
    </ToolbarItems>
</SfToolbar>

模式 2：带弹出菜单的响应式工具栏

将溢出项移至弹出菜单的工具栏：

<SfToolbar Width="400" OverflowMode="OverflowMode.Popup">
    <ToolbarItems>
        <ToolbarItem Text="Cut" PrefixIcon="e-icons e-cut" Overflow="OverflowOption.Show"></ToolbarItem>
        <ToolbarItem Text="Copy" PrefixIcon="e-icons e-copy" Overflow="OverflowOption.Show"></ToolbarItem>
        <ToolbarItem Text="Paste" PrefixIcon="e-icons e-paste"></ToolbarItem>
        <ToolbarItem Type="ItemType.Separator"></ToolbarItem>
        <ToolbarItem Text="Bold" PrefixIcon="e-icons e-bold"></ToolbarItem>
        <ToolbarItem Text="Italic" PrefixIcon="e-icons e-italic"></ToolbarItem>
    </ToolbarItems>
</SfToolbar>

模式 3：支持动态添加和移除项的工具栏

支持以编程方式管理项的工具栏：

<SfToolbar>
    <ToolbarItems>
        @foreach (var item in ToolbarItems)
        {
            <ToolbarItem Text="@item.Text" PrefixIcon="@item.Icon"></ToolbarItem>
        }
    </ToolbarItems>
</SfToolbar>

@code {
    private List<ToolbarItemData> ToolbarItems = new()
    {
        new() { Text = "Cut", Icon = "e-icons e-cut" },
        new() { Text = "Copy", Icon = "e-icons e-copy" }
    };
    
    private void AddItem()
    {
        ToolbarItems.Add(new() { Text = "Paste", Icon = "e-icons e-paste" });
    }
    
    private void RemoveItem()
    {
        if (ToolbarItems.Count > 0)
            ToolbarItems.RemoveAt(0);
    }
    
    public class ToolbarItemData
    {
        public string Text { get; set; }
        public string Icon { get; set; }
    }
}

模式 4：自定义对齐方式的工具栏

使用 Spacer 实现左对齐、居中对齐和右对齐项：

<SfToolbar>
    <ToolbarItems>
        <ToolbarItem Text="File"></ToolbarItem>
        <ToolbarItem Text="Edit"></ToolbarItem>
        <ToolbarItem Type="ItemType.Spacer"></ToolbarItem>
        <ToolbarItem Text="Help"></ToolbarItem>
        <ToolbarItem Type="ItemType.Spacer"></ToolbarItem>
        <ToolbarItem Text="Settings" PrefixIcon="e-icons e-settings"></ToolbarItem>
        <ToolbarItem Text="Profile" PrefixIcon="e-icons e-user"></ToolbarItem>
    </ToolbarItems>
</SfToolbar>

关键属性参考

SfToolbar 组件属性

属性	类型	描述
Width	string	设置工具栏宽度（例如，“600px”、“100%”）
Height	string	设置工具栏高度
OverflowMode	OverflowMode	定义溢出行为：Scrollable、Popup、MultiRow、Extended
ScrollStep	int	使用导航箭头时的滚动距离（像素）
EnableRtl	bool	启用从右到左的布局
CssClass	string	工具栏容器的自定义 CSS 类

ToolbarItem 属性

属性	类型	描述
Text	string	按钮文本内容
PrefixIcon	string	显示在文本前的图标 CSS 类
SuffixIcon	string	显示在文本后的图标 CSS 类
TooltipText	string	悬停时显示的工具提示
Type	ItemType	Button、Separator、Input 或 Spacer
Align	ItemAlign	左对齐、居中对齐或右对齐
Disabled	bool	为 true 时禁用此项
Visible	bool	控制此项是否可见
Width	string	设置项宽度
CssClass	string	此项的自定义 CSS 类
HtmlAttributes	Dictionary	自定义 HTML 属性（id、style、role 等）
Overflow	OverflowOption	Show（优先）、Hide（次要）或 None
ShowAlwaysInPopup	bool	始终在弹出菜单中显示此项（Popup 模式）
ShowTextOn	DisplayMode	控制文本显示位置：Toolbar、Overflow 或 Both
TabIndex	int	启用 Tab 键导航
Template	RenderFragment	自定义内容模板
Id	string	此项的唯一标识符

实现指南

配置项时

1. 使用合适的项类型：操作使用 Button，视觉分隔使用 Separator，对齐使用 Spacer，自定义控件使用 Input
2. 添加图标以改善用户体验：对于纯图标按钮或带文本的图标按钮，使用 PrefixIcon
3. 提供工具提示：为纯图标按钮设置 TooltipText，以提升可访问性
4. 考虑响应式行为：根据目标设备选择合适的 OverflowMode
5. 设置溢出优先级：使用 Overflow 属性控制哪些项优先移至弹出菜单

处理溢出时

1. Scrollable 模式（默认）：最适合有充足横向空间的桌面应用
2. Popup 模式：适用于移动设备或宽度受限的容器
3. MultiRow 模式：适合包含多个相关项的工具栏
4. Extended 模式：与 MultiRow 类似，但布局行为不同

自定义外观时

1. 使用内置图标：搭配 e-icons 类使用 Syncfusion 图标库
2. 统一应用主题：使用 CssClass 进行自定义样式设置
3. 考虑可访问性：保持足够的颜色对比度并提供焦点指示器
4. 测试响应式行为：检查工具栏在不同宽度下的显示效果

实现动态行为时

1. 使用数据绑定：将 ToolbarItems 绑定到集合，以支持动态更新
2. 处理事件：使用 OnClick 处理按钮操作
3. 有条件地更新状态：根据应用程序状态切换 Disabled 或 Visible 属性
4. 管理项的生命周期：从绑定集合中添加或移除项，以更新工具栏

常见用例

1. 富文本编辑器：提供粗体、斜体、对齐和列表等格式设置工具栏
2. 文件管理器：提供上传、下载、删除和重命名按钮的操作栏
3. 数据网格：提供用于添加、编辑、删除和导出操作的命令工具栏
4. 图像编辑器：提供包含绘图、裁剪和滤镜工具的工具面板
5. 导航菜单：提供包含菜单项和搜索功能的顶级导航
6. 仪表板控件：提供用于刷新、筛选和设置的操作按钮
7. 表单构建器：提供包含可拖动控件的组件面板

提示和最佳实践

• 仅图标按钮：始终提供 TooltipText，以确保无障碍访问
• 响应式设计：在不同宽度下测试工具栏，确认溢出行为
• 键盘导航：启用 TabIndex，以提升键盘无障碍体验
• 视觉分组：使用 Separator 将相关项划分为逻辑组
• 性能：使用大量项时，可考虑使用 Popup 模式，以减小初始渲染大小
• 自定义模板：复杂控件超出标准按钮的能力时，使用 Template 属性
• 灵活对齐：对于更灵活的布局，优先使用 Spacer，而非 Align 属性

后续步骤

实现基本工具栏后：

1. 探索响应式模式，以适应不同的屏幕尺寸
2. 使用 TabIndex 添加键盘导航，以提升无障碍体验
3. 自定义样式，使其与应用程序主题相匹配
4. 实现动态项管理，构建交互式工具栏
5. 使用模板添加切换按钮或自定义控件
6. 与其他 Syncfusion 组件（DropDownList、ColorPicker 等）集成