syncfusion-blazor-ribbon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion Blazor Ribbon Component

Syncfusion Blazor Ribbon 组件

Build professional Office-style ribbon interfaces with the Syncfusion Blazor Ribbon component. This skill provides comprehensive guidance on implementing, configuring, and customizing the Ribbon for Blazor applications.

使用Syncfusion Blazor Ribbon组件构建专业的Office风格功能区界面。本技能为Blazor应用中Ribbon的实现、配置和自定义提供全面指导。

Component Overview

组件概述

The Ribbon is a Microsoft Office-style UI component that organizes commands and tools into tabs, groups, and collections. It provides an intuitive interface for application functionality with support for multiple item types, file menus, and extensive customization options.

Ribbon是Microsoft Office风格的UI组件，将命令和工具组织到选项卡、组和集合中。它为应用功能提供直观的界面，支持多种项类型、文件菜单和丰富的自定义选项。

Key Concepts

核心概念

Tabs: Top-level navigation containers (Home, Insert, Design, etc.)
Groups: Logical groupings of related items within a tab (Clipboard, Font, Alignment)
Collections: Organize items within a group (vertical or horizontal)
Items: Individual controls (buttons, dropdowns, checkboxes, color pickers, etc.)
File Menu: Special dropdown menu for file operations (New, Open, Save)
Gallery: Display visual collections of related items (styles, themes, designs)
Contextual Tabs: Dynamic tabs that appear based on selected objects or context
Backstage View: Full-screen menu for file operations and application settings
KeyTips: Keyboard shortcuts for accessibility and productivity

选项卡（Tabs）：顶级导航容器（如开始、插入、设计等）
组（Groups）：选项卡内相关项的逻辑分组（如剪贴板、字体、对齐方式）
集合（Collections）：组内的项组织方式（垂直或水平）
项（Items）：单个控件（按钮、下拉框、复选框、颜色选择器等）
文件菜单（File Menu）：用于文件操作的特殊下拉菜单（新建、打开、保存）
图库（Gallery）：显示相关项的视觉集合（样式、主题、设计）
上下文选项卡（Contextual Tabs）：根据选中对象或上下文动态显示的选项卡
后台视图（Backstage View）：用于文件操作和应用设置的全屏菜单
KeyTips：提升可访问性和生产力的键盘快捷键

Ribbon Structure

Ribbon 结构

SfRibbon (Main Container)
├── RibbonFileMenuSettings (Optional File Menu)
└── RibbonTabs
    └── RibbonTab (Home, Insert, Design...)
        └── RibbonGroups
            └── RibbonGroup (Clipboard, Font...)
                └── RibbonCollections
                    └── RibbonCollection (Row/Column Layout)
                        └── RibbonItems
                            └── RibbonItem (Button, Dropdown, etc.)

SfRibbon (主容器)
├── RibbonFileMenuSettings (可选文件菜单)
└── RibbonTabs
    └── RibbonTab (开始、插入、设计...)
        └── RibbonGroups
            └── RibbonGroup (剪贴板、字体...)
                └── RibbonCollections
                    └── RibbonCollection (行/列布局)
                        └── RibbonItems
                            └── RibbonItem (Button、Dropdown等)

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and NuGet package setup
Namespace imports and service registration
Theme configuration
Basic ribbon initialization with first tab and group
Minimal working example

📄 阅读： references/getting-started.md

安装与NuGet包设置
命名空间导入与服务注册
主题配置
带首个选项卡和组的基础Ribbon初始化
最简运行示例

Ribbon Structure and Layout

Ribbon 结构与布局

📄 Read: references/ribbon-structure.md

Tab organization and configuration
Group creation with orientation control
Collection hierarchy and row/column layouts
Item definition basics
Organizational best practices

📄 阅读： references/ribbon-structure.md

选项卡组织与配置
带方向控制的组创建
集合层级与行/列布局
项定义基础
组织最佳实践

Ribbon Items: Basic Types

Ribbon 项：基础类型

📄 Read: references/ribbon-items-basic.md

Button items with click handlers
Checkbox items with toggle state
DropDown items with menu options
SplitButton items combining button and menu
Disabled items and item sizing

📄 阅读： references/ribbon-items-basic.md

带点击处理程序的按钮项
带切换状态的复选框项
带菜单选项的下拉框项
结合按钮与菜单的SplitButton项
禁用项与项尺寸设置

Ribbon Items: Advanced Types

Ribbon 项：高级类型

📄 Read: references/ribbon-items-advanced.md

ComboBox items with data binding and filtering
ColorPicker items for color selection
GroupButton items with multiple/single selection modes
Template items for custom HTML content
DisplayOptions for layout-specific visibility

📄 阅读： references/ribbon-items-advanced.md

带数据绑定与过滤的ComboBox项
用于颜色选择的ColorPicker项
带多/单选模式的GroupButton项
用于自定义HTML内容的模板项
针对特定布局可见性的DisplayOptions

File Menu Configuration

文件菜单配置

📄 Read: references/file-menu.md

Enabling and configuring the file menu
Adding menu items and nested submenus
Submenu behavior (hover vs click)
Custom header text
File menu events

📄 阅读： references/file-menu.md

启用与配置文件菜单
添加菜单项和嵌套子菜单
子菜单行为（悬停 vs 点击）
自定义标题文本
文件菜单事件

Events and Interactions

事件与交互

📄 Read: references/events.md

Component-level events (Created, TabSelecting, TabSelected)
Ribbon state events (Expanding, Collapsing)
Item click and selection events
Launcher icon and overflow popup events
Event handler patterns and examples

📄 阅读： references/events.md

组件级事件（Created、TabSelecting、TabSelected）
Ribbon状态事件（Expanding、Collapsing）
项点击与选择事件
启动器图标与溢出弹窗事件
事件处理程序模式与示例

Gallery Items

图库项

📄 Read: references/gallery.md

Gallery view for displaying collections of related items
Gallery groups with custom headers
Item dimensions and styling
Item count configuration
Selected item index management
Popup dimensions customization
Template customization for gallery items

📄 阅读： references/gallery.md

用于显示相关项集合的图库视图
带自定义标题的图库组
项尺寸与样式
项数量配置
选中项索引管理
弹窗尺寸自定义
图库项的模板自定义

Contextual Tabs

上下文选项卡

📄 Read: references/contextual-tabs.md

Dynamic tab visibility control
Contextual tab configuration
Tab selection state management
Show and hide tab methods
Context-aware UI elements

📄 阅读： references/contextual-tabs.md

动态选项卡可见性控制
上下文选项卡配置
选项卡选择状态管理
显示与隐藏选项卡的方法
上下文感知UI元素

Backstage View

后台视图

📄 Read: references/backstage.md

Backstage menu configuration
Menu item and footer items
Backstage separators
Back button customization
Backstage template customization
Width and height configuration
Backstage events

📄 阅读： references/backstage.md

后台菜单配置
菜单项与页脚项
后台分隔符
返回按钮自定义
后台模板自定义
宽高配置
后台事件

Keyboard Navigation and KeyTips

键盘导航与KeyTips

📄 Read: references/keytips.md

KeyTips for ribbon items
File menu keytips
Backstage menu keytips
Layout switcher keytips
Launcher icon keytips
ShowKeyTips and HideKeyTips methods
KeyTip best practices and guidelines

📄 阅读： references/keytips.md

Ribbon项的KeyTips
文件菜单的KeyTips
后台菜单的KeyTips
布局切换器的KeyTips
启动器图标的KeyTips
ShowKeyTips与HideKeyTips方法
KeyTips最佳实践与指南

Customization and Styling

自定义与样式

📄 Read: references/customization.md

Theme selection and application
Item sizing and layout options
CSS customization and class application
RTL (Right-to-Left) support
Overflow handling and group collapsing

📄 阅读： references/customization.md

主题选择与应用
项尺寸与布局选项
CSS自定义与类应用
RTL（从右到左）支持
溢出处理与组折叠

Accessibility

辅助功能

📄 Read: references/accessibility.md

WCAG 2.1 compliance and standards
Keyboard navigation (Tab, Enter, Space, Arrow keys)
ARIA attributes and semantic markup
Screen reader support
Focus management and visual indicators

📄 阅读： references/accessibility.md

WCAG 2.1合规性与标准
键盘导航（Tab、Enter、Space、方向键）
ARIA属性与语义化标记
屏幕阅读器支持
焦点管理与视觉指示器

Quick Start Example

快速入门示例

razor

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Ribbon
@using Syncfusion.Blazor.SplitButtons

<div style="width: 100%">
    <SfRibbon>
        <RibbonTabs>
            <RibbonTab HeaderText="Home">
                <RibbonGroups>
                    <RibbonGroup HeaderText="Clipboard" Orientation="Orientation.Row">
                        <RibbonCollections>
                            <RibbonCollection>
                                <RibbonItems>
                                    <RibbonItem Type="RibbonItemType.SplitButton">
                                        <RibbonSplitButtonSettings Content="Paste" IconCss="e-icons e-paste" Items="@pasteOptions">
                                        </RibbonSplitButtonSettings>
                                    </RibbonItem>
                                </RibbonItems>
                            </RibbonCollection>
                            <RibbonCollection>
                                <RibbonItems>
                                    <RibbonItem Type="RibbonItemType.Button">
                                        <RibbonButtonSettings Content="Cut" IconCss="e-icons e-cut" OnClick="@OnCut">
                                        </RibbonButtonSettings>
                                    </RibbonItem>
                                    <RibbonItem Type="RibbonItemType.Button">
                                        <RibbonButtonSettings Content="Copy" IconCss="e-icons e-copy" OnClick="@OnCopy">
                                        </RibbonButtonSettings>
                                    </RibbonItem>
                                </RibbonItems>
                            </RibbonCollection>
                        </RibbonCollections>
                    </RibbonGroup>
                </RibbonGroups>
            </RibbonTab>
        </RibbonTabs>
    </SfRibbon>
</div>

@code {
    private List<DropDownMenuItem> pasteOptions = new List<DropDownMenuItem>()
    {
        new DropDownMenuItem{ Text = "Keep Source Format" },
        new DropDownMenuItem{ Text = "Merge Format" },
        new DropDownMenuItem{ Text = "Keep Text Only" }
    };

    private void OnCut(MouseEventArgs args) { /* Handle cut action */ }
    private void OnCopy(MouseEventArgs args) { /* Handle copy action */ }
}

razor

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Ribbon
@using Syncfusion.Blazor.SplitButtons

<div style="width: 100%">
    <SfRibbon>
        <RibbonTabs>
            <RibbonTab HeaderText="Home">
                <RibbonGroups>
                    <RibbonGroup HeaderText="Clipboard" Orientation="Orientation.Row">
                        <RibbonCollections>
                            <RibbonCollection>
                                <RibbonItems>
                                    <RibbonItem Type="RibbonItemType.SplitButton">
                                        <RibbonSplitButtonSettings Content="Paste" IconCss="e-icons e-paste" Items="@pasteOptions">
                                        </RibbonSplitButtonSettings>
                                    </RibbonItem>
                                </RibbonItems>
                            </RibbonCollection>
                            <RibbonCollection>
                                <RibbonItems>
                                    <RibbonItem Type="RibbonItemType.Button">
                                        <RibbonButtonSettings Content="Cut" IconCss="e-icons e-cut" OnClick="@OnCut">
                                        </RibbonButtonSettings>
                                    </RibbonItem>
                                    <RibbonItem Type="RibbonItemType.Button">
                                        <RibbonButtonSettings Content="Copy" IconCss="e-icons e-copy" OnClick="@OnCopy">
                                        </RibbonButtonSettings>
                                    </RibbonItem>
                                </RibbonItems>
                            </RibbonCollection>
                        </RibbonCollections>
                    </RibbonGroup>
                </RibbonGroups>
            </RibbonTab>
        </RibbonTabs>
    </SfRibbon>
</div>

@code {
    private List<DropDownMenuItem> pasteOptions = new List<DropDownMenuItem>()
    {
        new DropDownMenuItem{ Text = "Keep Source Format" },
        new DropDownMenuItem{ Text = "Merge Format" },
        new DropDownMenuItem{ Text = "Keep Text Only" }
    };

    private void OnCut(MouseEventArgs args) { /* Handle cut action */ }
    private void OnCopy(MouseEventArgs args) { /* Handle copy action */ }
}

Common Patterns

常见模式

1. Multi-Tab Ribbon

1. 多选项卡Ribbon

Organize related functionality into separate tabs with different commands:

razor

<SfRibbon>
    <RibbonTabs>
        <RibbonTab HeaderText="Home"><!-- Home commands --></RibbonTab>
        <RibbonTab HeaderText="Insert"><!-- Insert commands --></RibbonTab>
        <RibbonTab HeaderText="Design"><!-- Design commands --></RibbonTab>
    </RibbonTabs>
</SfRibbon>

将相关功能组织到不同选项卡中，包含不同命令：

razor

<SfRibbon>
    <RibbonTabs>
        <RibbonTab HeaderText="Home"><!-- Home commands --></RibbonTab>
        <RibbonTab HeaderText="Insert"><!-- Insert commands --></RibbonTab>
        <RibbonTab HeaderText="Design"><!-- Design commands --></RibbonTab>
    </RibbonTabs>
</SfRibbon>

2. Grouped Commands

2. 分组命令

Group related items for better organization and UI layout:

razor

<RibbonTab HeaderText="Home">
    <RibbonGroups>
        <RibbonGroup HeaderText="Clipboard"><!-- Copy/Paste items --></RibbonGroup>
        <RibbonGroup HeaderText="Font"><!-- Font items --></RibbonGroup>
        <RibbonGroup HeaderText="Paragraph"><!-- Alignment items --></RibbonGroup>
    </RibbonGroups>
</RibbonTab>

将相关项分组，优化组织与UI布局：

razor

<RibbonTab HeaderText="Home">
    <RibbonGroups>
        <RibbonGroup HeaderText="Clipboard"><!-- Copy/Paste items --></RibbonGroup>
        <RibbonGroup HeaderText="Font"><!-- Font items --></RibbonGroup>
        <RibbonGroup HeaderText="Paragraph"><!-- Alignment items --></RibbonGroup>
    </RibbonGroups>
</RibbonTab>

3. File Menu Integration

3. 文件菜单集成

Include file operations menu:

razor

<SfRibbon>
    <RibbonFileMenuSettings Visible="true" MenuItems="@fileMenuItems">
    </RibbonFileMenuSettings>
    <RibbonTabs><!-- tabs here --></RibbonTabs>
</SfRibbon>

包含文件操作菜单：

razor

<SfRibbon>
    <RibbonFileMenuSettings Visible="true" MenuItems="@fileMenuItems">
    </RibbonFileMenuSettings>
    <RibbonTabs><!-- tabs here --></RibbonTabs>
</SfRibbon>

4. Data-Bound ComboBox

4. 数据绑定ComboBox

Bind dropdown to data source:

razor

<RibbonItem Type="RibbonItemType.ComboBox">
    <RibbonComboBoxSettings DataSource="@fontFamilies" 
                             FieldSettings="@fieldSettings"
                             AllowFiltering="true">
    </RibbonComboBoxSettings>
</RibbonItem>

将下拉框绑定到数据源：

razor

<RibbonItem Type="RibbonItemType.ComboBox">
    <RibbonComboBoxSettings DataSource="@fontFamilies" 
                             FieldSettings="@fieldSettings"
                             AllowFiltering="true">
    </RibbonComboBoxSettings>
</RibbonItem>

5. Toggle Buttons

5. 切换按钮

Create buttons with selected/unselected state:

razor

<RibbonItem Type="RibbonItemType.GroupButton">
    <RibbonGroupButtonSettings Selection="GroupButtonSelection.Single" Items="@alignmentOptions">
    </RibbonGroupButtonSettings>
</RibbonItem>

创建带选中/未选中状态的按钮：

razor

<RibbonItem Type="RibbonItemType.GroupButton">
    <RibbonGroupButtonSettings Selection="GroupButtonSelection.Single" Items="@alignmentOptions">
    </RibbonGroupButtonSettings>
</RibbonItem>

Key Properties and Configuration

核心属性与配置

Component-Level

组件级

Tabs: Collection of
```
RibbonTab
```
objects
FileMenuSettings: Configure file menu visibility and items
Created: Event fired when ribbon initializes

Tabs：
```
RibbonTab
```
对象集合
FileMenuSettings：配置文件菜单可见性与项
Created：Ribbon初始化时触发的事件

Tab-Level

选项卡级

HeaderText: Tab name displayed to users
Visible: Show/hide tabs dynamically

HeaderText：显示给用户的选项卡名称
Visible：动态显示/隐藏选项卡

Group-Level

组级

HeaderText: Group label
Orientation:
```
Row
```
or
```
Column
```
layout
PopupHeaderText: Text in overflow popup (if EnableGroupOverflow=true)

HeaderText：组标签
Orientation：
```
Row
```
或
```
Column
```
布局
PopupHeaderText：溢出弹窗中的文本（若EnableGroupOverflow=true）

Item-Level

项级

Type:

Button

Checkbox

DropDown

SplitButton

ComboBox

ColorPicker

GroupButton

Template

Disabled: Disable individual items
DisplayOptions:
```
Auto
```
,
```
Classic
```
,
```
Simplified
```
,
```
Overflow
```
AllowedSizes:
```
Small
```
,
```
Medium
```
,
```
Large
```

Type：

Button

、

Checkbox

、

DropDown

、

SplitButton

、

ComboBox

、

ColorPicker

、

GroupButton

、

Template

Disabled：禁用单个项
DisplayOptions：
```
Auto
```
、
```
Classic
```
、
```
Simplified
```
、
```
Overflow
```
AllowedSizes：
```
Small
```
、
```
Medium
```
、
```
Large
```

Common Use Cases

常见使用场景

1. Document Editor

1. 文档编辑器

Build a word processor ribbon with file operations, formatting, and style controls.

构建包含文件操作、格式设置和样式控件的文字处理器功能区。

2. Spreadsheet Application

2. 电子表格应用

Create a spreadsheet ribbon with formulas, data analysis, and cell formatting.

创建包含公式、数据分析和单元格格式设置的电子表格功能区。

3. Design Tool

3. 设计工具

Implement a design application ribbon with drawing tools, colors, and object manipulation.

实现包含绘图工具、颜色和对象操作的设计应用功能区。

4. Content Management System

4. 内容管理系统

Design a CMS ribbon with publishing options, content organization, and workflow controls.

设计包含发布选项、内容组织和工作流控件的CMS功能区。

5. Admin Dashboard

5. 管理后台

Create admin tools ribbon with user management, settings, and system controls.

创建包含用户管理、设置和系统控件的管理工具功能区。

6. Email Client

6. 邮件客户端

Build email ribbon with message actions (Reply, Forward, Delete, Archive).

构建包含消息操作（回复、转发、删除、归档）的邮件功能区。

7. Media Editor

7. 媒体编辑器

Implement image/video editor ribbon with editing tools, effects, and export options.

实现包含编辑工具、效果和导出选项的图像/视频编辑器功能区。

Installation Prerequisites

安装前提

.NET 6.0 or higher
Blazor Server or WebAssembly project
Syncfusion.Blazor.Ribbon NuGet package
Syncfusion.Blazor.Themes NuGet package

.NET 6.0 或更高版本
Blazor Server 或 WebAssembly 项目
Syncfusion.Blazor.Ribbon NuGet包
Syncfusion.Blazor.Themes NuGet包

Theming Support

主题支持

Available themes:

Bootstrap 5 (default)
Material Design
Fluent UI (Microsoft)
Tailwind CSS
Fabric Office
Material Dark

Themes are applied via CSS imports in

index.html

App.razor

可用主题：

Bootstrap 5（默认）
Material Design
Fluent UI（Microsoft）
Tailwind CSS
Fabric Office
Material Dark

主题通过

index.html

或

App.razor

中的CSS导入应用。

Performance Considerations

性能注意事项

Use DisplayOptions to hide items not needed in specific layouts
Implement lazy loading for complex item configurations
Consider overflow handling for small screen sizes
Use templates judiciously to avoid excessive rendering

使用DisplayOptions隐藏特定布局中不需要的项
为复杂项配置实现懒加载
针对小屏幕尺寸考虑溢出处理
谨慎使用模板以避免过度渲染

Browser Support

浏览器支持

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
Mobile browsers (responsive)

Chrome（最新版）
Firefox（最新版）
Safari（最新版）
Edge（最新版）
移动浏览器（响应式）

Keyboard Navigation

键盘导航

Tab: Navigate between tabs
Enter/Space: Select items or open menus
Arrow Keys: Navigate within groups and items
Escape: Close open menus and popups

Tab：在选项卡间导航
Enter/Space：选择项或打开菜单
方向键：在组和项内导航
Escape：关闭打开的菜单和弹窗

Related Components

Troubleshooting Tips

故障排除技巧

Ribbon not appearing:

Verify NuGet packages are installed
Check namespace imports in
```
_Imports.razor
```
Confirm service registration in
```
Program.cs
```

Items not visible:

Check
```
Visible
```
property on tabs and items
Verify
```
DisplayOptions
```
configuration
Check
```
Disabled
```
property not set to
```
true
```

Styling issues:

Confirm theme CSS is referenced in
```
index.html
```
Check for conflicting CSS rules
Verify
```
CssClass
```
property syntax

Events not firing:

Confirm event handler is bound with
```
@
```
Check parameter types match event args
Verify component lifecycle (use
```
Created
```
event for initialization)

Ribbon未显示：

验证NuGet包已安装
检查
```
_Imports.razor
```
中的命名空间导入
确认
```
Program.cs
```
中的服务已注册

项不可见：

检查选项卡和项的
```
Visible
```
属性
验证
```
DisplayOptions
```
配置
确认
```
Disabled
```
属性未设置为
```
true
```

样式问题：

确认主题CSS已在
```
index.html
```
中引用
检查是否存在冲突的CSS规则
验证
```
CssClass
```
属性语法

事件未触发：

确认事件处理程序已用
```
@
```
绑定
检查参数类型与事件参数匹配
验证组件生命周期（使用
```
Created
```
事件进行初始化）

Next Steps

下一步

Start with Getting Started to install and set up the component
Learn Ribbon Structure to understand tab/group/item organization
Explore Item Types (Basic and Advanced) for different control options
Add File Menu for file operations
Implement Events for user interactions
Customize with Styling and Accessibility for production apps

For more information, visit the official Syncfusion Blazor Ribbon documentation.

从快速入门开始，安装并设置组件
学习Ribbon结构，理解选项卡/组/项的组织方式
探索项类型（基础与高级），了解不同控件选项
添加文件菜单以实现文件操作
实现事件以响应用户交互
通过样式和辅助功能自定义，完成生产应用开发

如需更多信息，请访问官方Syncfusion Blazor Ribbon文档。