Back to Details

syncfusion-blazor-toolbar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syncfusion Blazor Toolbar Component

Syncfusion Blazor Toolbar组件

The Syncfusion Blazor Toolbar is a versatile component for creating interactive command bars with buttons, separators, and custom controls. It provides built-in responsive behavior and flexible item configuration.
Syncfusion Blazor Toolbar是一款多功能组件，可用于创建包含按钮、分隔符和自定义控件的交互式命令栏。它提供内置的响应式行为和灵活的项配置。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Create toolbars with buttons, icons, and custom controls
  • Build text editors with formatting toolbars (bold, italic, alignment, etc.)
  • Implement command bars or action bars in applications
  • Add responsive toolbars that adapt to different screen sizes
  • Configure item overflow behavior (scrollable, popup, multirow)
  • Create navigation toolbars with alignment and spacing
  • Add toggle buttons or stateful toolbar items
  • Implement dynamic toolbars with add/remove item functionality
  • Customize toolbar appearance and styling
  • Enable RTL support for right-to-left languages
当您需要以下功能时使用本技能：
  • 创建带有按钮、图标和自定义控件的工具栏
  • 构建带有格式工具栏（加粗、斜体、对齐等）的文本编辑器
  • 在应用中实现命令栏或操作栏
  • 添加可适配不同屏幕尺寸的响应式工具栏
  • 配置项溢出行为（滚动式、弹出式、多行）
  • 创建带有对齐和间距的导航工具栏
  • 添加切换按钮或有状态的工具栏项
  • 实现支持添加/移除项功能的动态工具栏
  • 自定义工具栏外观和样式
  • 为从右到左的语言启用RTL支持

Component Overview

组件概述

The Blazor Toolbar component features:
  • Item Types: Buttons, separators, spacers, and custom templates
  • Responsive Modes: Scrollable, popup, multirow, and extended overflow handling
  • Alignment: Left, center, right alignment with spacer support
  • Customization: Icons, tooltips, styling, templates, and RTL support
  • Dynamic Management: Add, remove, enable, disable, show, hide items programmatically
Blazor Toolbar组件具备以下特性：
  • 项类型：按钮、分隔符、间距器和自定义模板
  • 响应模式：滚动式、弹出式、多行和扩展式溢出处理
  • 对齐方式：支持左、中、右对齐及间距器
  • 自定义功能：图标、工具提示、样式、模板和RTL支持
  • 动态管理：以编程方式添加、移除、启用、禁用、显示、隐藏项

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
When the user needs to:
  • Install and configure the Toolbar component
  • Add NuGet packages and register services
  • Create a basic toolbar with items
  • Understand the fundamental ToolbarItems structure
  • Set up CSS themes and script references
📄 阅读： references/getting-started.md
当用户需要：
  • 安装和配置Toolbar组件
  • 添加NuGet包并注册服务
  • 创建带有项的基础工具栏
  • 理解基础ToolbarItems结构
  • 设置CSS主题和脚本引用

Item Configuration and Properties

项配置与属性

📄 Read: references/item-configuration.md
When the user needs to:
  • Configure item properties (Text, PrefixIcon, SuffixIcon, Width, etc.)
  • Set item alignment (Left, Center, Right)
  • Define item types (Button, Separator, Input, Spacer)
  • Control item visibility and enabled state
  • Add tooltips to toolbar items
  • Use custom CSS classes or HTML attributes
  • Configure overflow behavior for individual items
  • Integrate other Syncfusion components (DropDownList, NumericTextBox, etc.)
  • Understand all 18 item properties in detail
📄 阅读： references/item-configuration.md
当用户需要：
  • 配置项属性（Text、PrefixIcon、SuffixIcon、Width等）
  • 设置项对齐方式（左、中、右）
  • 定义项类型（Button、Separator、Input、Spacer）
  • 控制项的可见性和启用状态
  • 为工具栏项添加工具提示
  • 使用自定义CSS类或HTML属性
  • 配置单个项的溢出行为
  • 集成其他Syncfusion组件（DropDownList、NumericTextBox等）
  • 详细了解全部18项属性

Practical How-To Guides

实用操作指南

📄 Read: references/how-to-guides.md
When the user needs to:
  • Add or remove toolbar items dynamically
  • Enable or disable toolbar items programmatically
  • Show or hide toolbar items based on conditions
  • Create toggle buttons with state management
  • Customize items with HtmlAttributes and CssClass
  • Set item-wise custom templates
  • Add tooltips using the SfTooltip component
  • Enable tab key navigation with TabIndex
  • Customize the scrolling distance
📄 阅读： references/how-to-guides.md
当用户需要：
  • 动态添加或移除工具栏项
  • 以编程方式启用或禁用工具栏项
  • 根据条件显示或隐藏工具栏项
  • 创建带有状态管理的切换按钮
  • 使用HtmlAttributes和CssClass自定义项
  • 设置基于项的自定义模板
  • 使用SfTooltip组件添加工具提示
  • 通过TabIndex启用Tab键导航
  • 自定义滚动距离

Responsive Behavior and Overflow Modes

响应式行为与溢出模式

📄 Read: references/responsive-mode.md
When the user needs to:
  • Configure toolbar overflow behavior (Scrollable, Popup, MultiRow, Extended)
  • Set item priority for overflow handling
  • Control text display in toolbar vs popup (ShowTextOn)
  • Implement scrollable toolbars with navigation arrows
  • Create popup toolbars with dropdown overflow
  • Configure multirow or extended overflow layouts
  • Handle touch gestures for scrolling
📄 阅读： references/responsive-mode.md
当用户需要：
  • 配置工具栏溢出行为（Scrollable、Popup、MultiRow、Extended）
  • 设置溢出处理的项优先级
  • 控制工具栏与弹出框中的文本显示（ShowTextOn）
  • 实现带有导航箭头的滚动式工具栏
  • 创建带有下拉溢出的弹出式工具栏
  • 配置多行或扩展式溢出布局
  • 处理滚动的触摸手势

Alignment and Spacing with Spacer

使用间距器进行对齐与间距设置

📄 Read: references/alignment-spacer.md
When the user needs to:
  • Use Spacer to align items left, center, and right
  • Create left and right alignment patterns
  • Implement right-only alignment
  • Understand when to use Spacer vs Align property
  • Apply flexible spacing between toolbar items
📄 阅读： references/alignment-spacer.md
当用户需要：
  • 使用Spacer将项左对齐、居中对齐和右对齐
  • 创建左对齐和右对齐模式
  • 实现仅右对齐布局
  • 理解何时使用Spacer vs Align属性
  • 在工具栏项之间应用灵活间距

Styling and Customization

样式与自定义

📄 Read: references/styling.md
When the user needs to:
  • Customize toolbar container styling
  • Style toolbar items and buttons
  • Modify icon appearance
  • Customize hover and focus states
  • Apply custom themes
  • Override default CSS classes
  • Enable RTL (right-to-left) support for Arabic, Hebrew, or Urdu languages
📄 阅读： references/styling.md
当用户需要：
  • 自定义工具栏容器样式
  • 设置工具栏项和按钮的样式
  • 修改图标外观
  • 自定义悬停和聚焦状态
  • 应用自定义主题
  • 覆盖默认CSS类
  • 为阿拉伯语、希伯来语或乌尔都语启用RTL（从右到左）支持

Quick Start Example

快速入门示例

Basic toolbar with common formatting buttons:
razor
@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>
带有常用格式按钮的基础工具栏：
razor
@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>

Common Patterns

常见模式

Pattern 1: Text Editor Toolbar

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

Formatting toolbar with alignment and spacing:
razor
<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>
带有对齐和间距的格式工具栏：
razor
<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>

Pattern 2: Responsive Toolbar with Popup

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

Toolbar that moves overflow items to a popup:
razor
<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>
将溢出项移至弹出框的工具栏：
razor
<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>

Pattern 3: Dynamic Toolbar with Add/Remove

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

Toolbar with programmatic item management:
razor
<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; }
    }
}
具备编程式项管理的工具栏：
razor
<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; }
    }
}

Pattern 4: Toolbar with Custom Alignment

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

Left-aligned, center-aligned, and right-aligned items using Spacer:
razor
<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>
使用Spacer实现左对齐、居中对齐和右对齐项：
razor
<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>

Key Properties Reference

关键属性参考

SfToolbar Component Properties

SfToolbar组件属性

PropertyTypeDescription
Width
stringSets the toolbar width (e.g., "600px", "100%")
Height
stringSets the toolbar height
OverflowMode
OverflowModeDefines overflow behavior: Scrollable, Popup, MultiRow, Extended
ScrollStep
intScrolling distance in pixels when using navigation arrows
EnableRtl
boolEnables right-to-left layout
CssClass
stringCustom CSS class for the toolbar container
属性类型描述
Width
string设置工具栏宽度（例如："600px"、"100%"）
Height
string设置工具栏高度
OverflowMode
OverflowMode定义溢出行为：Scrollable、Popup、MultiRow、Extended
ScrollStep
int使用导航箭头时的滚动距离（像素）
EnableRtl
bool启用从右到左布局
CssClass
string工具栏容器的自定义CSS类

ToolbarItem Properties

ToolbarItem属性

PropertyTypeDescription
Text
stringButton text content
PrefixIcon
stringIcon CSS class displayed before text
SuffixIcon
stringIcon CSS class displayed after text
TooltipText
stringTooltip displayed on hover
Type
ItemTypeButton, Separator, Input, or Spacer
Align
ItemAlignLeft, Center, or Right alignment
Disabled
boolDisables the item when true
Visible
boolControls item visibility
Width
stringSets item width
CssClass
stringCustom CSS classes for the item
HtmlAttributes
DictionaryCustom HTML attributes (id, style, role, etc.)
Overflow
OverflowOptionShow (priority), Hide (secondary), or None
ShowAlwaysInPopup
boolAlways displays item in popup (Popup mode)
ShowTextOn
DisplayModeControls text display: Toolbar, Overflow, or Both
TabIndex
intEnables tab key navigation
Template
RenderFragmentCustom content template
Id
stringUnique identifier for the item
属性类型描述
Text
string按钮文本内容
PrefixIcon
string文本前显示的图标CSS类
SuffixIcon
string文本后显示的图标CSS类
TooltipText
string悬停时显示的工具提示
Type
ItemType按钮、分隔符、输入框或间距器
Align
ItemAlign左、中或右对齐
Disabled
bool设置为true时禁用该项
Visible
bool控制项的可见性
Width
string设置项宽度
CssClass
string项的自定义CSS类
HtmlAttributes
Dictionary自定义HTML属性（id、style、role等）
Overflow
OverflowOptionShow（优先显示）、Hide（次要显示）或None
ShowAlwaysInPopup
bool在弹出模式下始终显示该项
ShowTextOn
DisplayMode控制文本显示：Toolbar、Overflow或Both
TabIndex
int启用Tab键导航
Template
RenderFragment自定义内容模板
Id
string项的唯一标识符

Implementation Guidelines

实施指南

When Configuring Items

配置项时

  1. Use appropriate item types: Button for actions, Separator for visual dividers, Spacer for alignment, Input for custom controls
  2. Add icons for better UX: Use PrefixIcon for icon-only or icon-with-text buttons
  3. Provide tooltips: Set TooltipText for icon-only buttons to improve accessibility
  4. Consider responsive behavior: Choose appropriate OverflowMode based on target devices
  5. Set overflow priorities: Use Overflow property to control which items move to popup first
  1. 使用合适的项类型：按钮用于操作，分隔符用于视觉分隔，间距器用于对齐，输入框用于自定义控件
  2. 添加图标提升用户体验：对仅图标或图标加文本的按钮使用PrefixIcon
  3. 提供工具提示：为仅图标按钮设置TooltipText以提升无障碍性
  4. 考虑响应式行为：根据目标设备选择合适的OverflowMode
  5. 设置溢出优先级：使用Overflow属性控制哪些项优先移至弹出框

When Handling Overflow

处理溢出时

  1. Scrollable mode (default): Best for desktop applications with horizontal space
  2. Popup mode: Ideal for mobile or limited-width containers
  3. MultiRow mode: Good for toolbars with many related items
  4. Extended mode: Similar to MultiRow but with different layout behavior
  1. 滚动模式（默认）：最适合有水平空间的桌面应用
  2. 弹出模式：适用于移动设备或宽度有限的容器
  3. 多行模式：适合包含多个相关项的工具栏
  4. 扩展模式：与多行模式类似，但布局行为不同

When Customizing Appearance

自定义外观时

  1. Use built-in icons: Leverage Syncfusion icon library with 
    e-icons
    class
  2. Apply themes consistently: Use CssClass for custom styling
  3. Consider accessibility: Maintain sufficient color contrast and focus indicators
  4. Test responsive behavior: Verify toolbar appearance at different widths
  1. 使用内置图标：借助
    e-icons
    类使用Syncfusion图标库
  2. 一致应用主题：使用CssClass进行自定义样式设置
  3. 考虑无障碍性：保持足够的颜色对比度和聚焦指示器
  4. 测试响应式行为：在不同宽度下验证工具栏外观

When Implementing Dynamic Behavior

实现动态行为时

  1. Use data binding: Bind ToolbarItems to a collection for dynamic updates
  2. Handle events: Use OnClick for button actions
  3. Update state conditionally: Toggle Disabled or Visible properties based on application state
  4. Manage item lifecycle: Add or remove items from the bound collection to update the toolbar
  1. 使用数据绑定：将ToolbarItems绑定到集合以实现动态更新
  2. 处理事件：使用OnClick处理按钮操作
  3. 根据条件更新状态：根据应用状态切换Disabled或Visible属性
  4. 管理项生命周期：通过添加或移除绑定集合中的项来更新工具栏

Common Use Cases

常见用例

  1. Rich Text Editors: Formatting toolbars with bold, italic, alignment, lists
  2. File Managers: Action bars with upload, download, delete, rename buttons
  3. Data Grids: Command toolbars for add, edit, delete, export operations
  4. Image Editors: Tool palettes with drawing, cropping, filter tools
  5. Navigation Menus: Top-level navigation with menu items and search
  6. Dashboard Controls: Action buttons for refresh, filter, settings
  7. Form Builders: Component palettes with draggable controls
  1. 富文本编辑器：包含加粗、斜体、对齐、列表的格式工具栏
  2. 文件管理器：包含上传、下载、删除、重命名按钮的操作栏
  3. 数据网格：用于添加、编辑、删除、导出操作的命令工具栏
  4. 图像编辑器：包含绘图、裁剪、滤镜工具的工具面板
  5. 导航菜单：包含菜单项和搜索的顶级导航栏
  6. 仪表板控件：用于刷新、筛选、设置的操作按钮
  7. 表单构建器：包含可拖拽控件的组件面板

Tips and Best Practices

技巧与最佳实践

  • Icon-only buttons: Always provide TooltipText for accessibility
  • Responsive design: Test toolbar at various widths to verify overflow behavior
  • Keyboard navigation: Enable TabIndex for better keyboard accessibility
  • Visual grouping: Use Separator to create logical groups of related items
  • Performance: When using many items, consider Popup mode to reduce initial render size
  • Custom templates: Use Template property for complex controls beyond standard buttons
  • Alignment flexibility: Prefer Spacer over Align property for more dynamic layouts
  • 仅图标按钮：始终提供TooltipText以保障无障碍性
  • 响应式设计：在各种宽度下测试工具栏以验证溢出行为
  • 键盘导航：启用TabIndex以提升键盘无障碍性
  • 视觉分组：使用Separator创建相关项的逻辑分组
  • 性能优化：当项较多时，考虑使用Popup模式减少初始渲染尺寸
  • 自定义模板：对标准按钮之外的复杂控件使用Template属性
  • 灵活对齐：优先使用Spacer属性而非Align属性实现更动态的布局

Next Steps

后续步骤

After implementing the basic toolbar:
  1. Explore responsive modes to handle different screen sizes
  2. Add keyboard navigation with TabIndex for accessibility
  3. Customize styling to match your application theme
  4. Implement dynamic item management for interactive toolbars
  5. Add toggle buttons or custom controls using templates
  6. Integrate with other Syncfusion components (DropDownList, ColorPicker, etc.)
实现基础工具栏后：
  1. 探索响应模式以适配不同屏幕尺寸
  2. 添加TabIndex实现键盘导航以提升无障碍性
  3. 自定义样式以匹配应用主题
  4. 实现动态项管理以打造交互式工具栏
  5. 使用模板添加切换按钮或自定义控件
  6. 与其他Syncfusion组件（DropDownList、ColorPicker等）集成