syncfusion-aspnetcore-ribbon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion ASP.NET Core Ribbon Control

Syncfusion ASP.NET Core Ribbon 控件

Overview

概述

A comprehensive skill for implementing the Syncfusion EJ2 Ribbon component in ASP.NET Core applications using Razor Tag Helpers. This skill covers installation, setup, component structure, all item types, events, theming, and advanced features. The Ribbon component is a feature-rich navigation control that:

Organizes commands in tabs and groups - Tabbed interface with logical grouping
Supports 7 item types - Button, CheckBox, DropDown, SplitButton, ComboBox, ColorPicker, GroupButton
Provides file menu & backstage - Traditional file menu or modern backstage view
Contextual tabs on demand - Tabs appear when needed (e.g., on image/table selection)
Gallery items - Visual selection of styles, templates, or options
Responsive layouts - Classic (multi-row) and Simplified (compact) modes
Keyboard navigation - KeyTips for Alt+key shortcuts
WCAG 2.1 compliant - Full accessibility support with ARIA
Built-in themes - Material, Bootstrap, Fluent, Tailwind, Fabric

本技能全面介绍如何在ASP.NET Core应用中使用Razor Tag Helpers实现Syncfusion EJ2 Ribbon组件，涵盖安装、配置、组件结构、所有项类型、事件、主题及高级功能。Ribbon组件是一款功能丰富的导航控件，具备以下特性：

在tabs和groups中组织命令 - 采用逻辑分组的选项卡式界面
支持7种项类型 - Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton
提供文件菜单与backstage视图 - 传统文件菜单或现代backstage视图
按需显示上下文选项卡 - 在需要时显示选项卡（例如选中图片/表格时）
Gallery项 - 可视化选择样式、模板或选项
响应式布局 - 经典（多行）和简化（紧凑）模式
键盘导航 - 支持Alt+快捷键的KeyTips
符合WCAG 2.1标准 - 完整的无障碍访问支持，包含ARIA
内置主题 - Material、Bootstrap、Fluent、Tailwind、Fabric

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

NuGet package installation
Tag Helper registration in _ViewImports.cshtml
CSS and script setup in _Layout.cshtml
First working example with complete setup
Available themes (Material, Bootstrap, Fluent, Tailwind, Fabric)
Advanced feature registration (no separate module injection needed in ASP.NET Core)
Localization with
```
locale
```
property
State persistence with
```
enablePersistence
```

📄 阅读： references/getting-started.md

NuGet包安装
在_ViewImports.cshtml中注册Tag Helper
在_Layout.cshtml中配置CSS和脚本
包含完整配置的首个可用示例
可用主题（Material、Bootstrap、Fluent、Tailwind、Fabric）
高级功能注册（ASP.NET Core中无需单独注入模块）
使用
```
locale
```
属性实现本地化
使用
```
enablePersistence
```
实现状态持久化

Ribbon Structure

Ribbon 结构

📄 Read: references/ribbon-structure.md

Component hierarchy (Ribbon → Tab → Group → Collection → Item)
Adding tabs with
```
<e-ribbon-tab>
```
Adding groups with
```
<e-ribbon-group>
```
Adding collections and items
Organizing ribbon content
Best practices for structure

📄 阅读： references/ribbon-structure.md

组件层级结构（Ribbon → Tab → Group → Collection → Item）
使用
```
<e-ribbon-tab>
```
添加选项卡
使用
```
<e-ribbon-group>
```
添加组
添加集合和项
组织Ribbon内容
结构设计最佳实践

Items & Groups Configuration

项与组配置

📄 Read: references/items-and-groups.md

All 7 item types (Button, CheckBox, DropDown, SplitButton, ComboBox, ColorPicker, GroupButton, Template)
Exact
```
RibbonXxxSettings
```
configuration for each type
Group properties (header, collapsibility, priority, overflow)
Item sizing (Large, Medium, Small)
Display options (Auto, Classic, Simplified, Overflow)
Disabled states

📄 阅读： references/items-and-groups.md

全部7种项类型（Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton、Template）
每种类型对应的
```
RibbonXxxSettings
```
精确配置
组属性（标题、可折叠性、优先级、溢出）
项尺寸（Large、Medium、Small）
显示选项（Auto、Classic、Simplified、Overflow）
禁用状态

Tabs & Groups Management

选项卡与组管理

📄 Read: references/tabs-and-groups.md

Tab management patterns
Multi-tab setup examples
Group organization
Collapsibility control (
```
isCollapsible
```
)
Priority handling (higher = collapses first)
Launcher icons
Group overflow behavior

📄 阅读： references/tabs-and-groups.md

选项卡管理模式
多选项卡配置示例
组组织方式
可折叠性控制（
```
isCollapsible
```
）
优先级处理（优先级越高，越先折叠）
启动器图标
组溢出行为

Layouts & Display Modes

布局与显示模式

📄 Read: references/layouts-display-modes.md

Classic layout (default, multi-row)
Simplified layout (compact, single-row)
Layout switching
Responsive resizing behavior
Item sizing progression (Large → Medium → Small)
Minimized state
Hide layout switcher option

📄 阅读： references/layouts-display-modes.md

经典布局（默认，多行）
简化布局（紧凑，单行）
布局切换
响应式调整行为
项尺寸递进（Large → Medium → Small）
最小化状态
隐藏布局切换器选项

File Menu & Backstage

文件菜单与Backstage

📄 Read: references/file-menu-backstage.md

File menu basics (
```
<e-ribbon-filemenusettings>
```
)
Menu item configuration with
```
MenuItem
```
list
Backstage view (
```
<e-ribbon-backstagemenusettings>
```
)
Backstage items with content
Footer items and separators
Back button customization

📄 阅读： references/file-menu-backstage.md

文件菜单基础（
```
<e-ribbon-filemenusettings>
```
）
使用
```
MenuItem
```
列表配置菜单项
Backstage视图（
```
<e-ribbon-backstagemenusettings>
```
）
带内容的Backstage项
页脚项与分隔符
返回按钮自定义

Contextual Tabs & Gallery

上下文选项卡与Gallery

📄 Read: references/contextual-tabs-gallery.md

Contextual tabs on demand
Visibility control with conditions
Gallery items (
```
type=Gallery
```
)
Gallery groups with headers
Gallery item properties (content, iconCss, disabled)
Visual selection patterns

📄 阅读： references/contextual-tabs-gallery.md

按需显示上下文选项卡
通过条件控制可见性
Gallery项（
```
type=Gallery
```
）
带标题的Gallery组
Gallery项属性（内容、iconCss、禁用状态）
可视化选择模式

Events & Accessibility

事件与无障碍访问

📄 Read: references/events-accessibility.md

Ribbon events (tabSelected, tabSelecting, itemClick, etc.)
KeyTips configuration (
```
enableKeyTips
```
,
```
keyTip
```
property)
Keyboard navigation
WCAG 2.1 compliance
ARIA attributes support
RTL support (
```
enableRtl
```
)

📄 阅读： references/events-accessibility.md

Ribbon事件（tabSelected、tabSelecting、itemClick等）
KeyTips配置（
```
enableKeyTips
```
、
```
keyTip
```
属性）
键盘导航
WCAG 2.1合规性
ARIA属性支持
RTL支持（
```
enableRtl
```
）

Customization & Theming

自定义与主题

📄 Read: references/customization-theming.md

Built-in themes table (5 themes)
Theme CSS import paths
Theme switching implementation
CSS customization classes
Dark mode support
Custom icons and styling

📄 阅读： references/customization-theming.md

内置主题表格（5种主题）
主题CSS导入路径
主题切换实现
CSS自定义类
深色模式支持
自定义图标与样式

Tooltips & Help

工具提示与帮助面板

📄 Read: references/tooltips-help-pane.md

Item tooltips with
```
RibbonTooltipSettings
```
Title and content properties
Custom tooltip HTML
Help pane component patterns
Contextual help implementation

📄 阅读： references/tooltips-help-pane.md

使用
```
RibbonTooltipSettings
```
配置项工具提示
标题与内容属性
自定义工具提示HTML
帮助面板组件模式
上下文帮助实现

Methods & Properties

方法与属性

📄 Read: references/methods-and-properties.md

Ribbon methods (getComponent, destroy)
Key events and callbacks
Property access patterns
Programmatic control
State management

📄 阅读： references/methods-and-properties.md

Ribbon方法（getComponent、destroy）
关键事件与回调
属性访问模式
程序化控制
状态管理

Troubleshooting

故障排除

📄 Read: references/troubleshooting.md

Common issues and solutions
Tag helper registration problems
Data binding issues
Event handling troubleshooting
Performance optimization
Styling problems
ASP.NET Core-specific gotchas

📄 阅读： references/troubleshooting.md

常见问题与解决方案
Tag Helper注册问题
数据绑定问题
事件处理故障排除
性能优化
样式问题
ASP.NET Core特有注意事项

Key Properties & Events

关键属性与事件

Essential Properties:

```
id
```
- Unique identifier for the ribbon
```
activeLayout
```
- Set to
```
Classic
```
or
```
Simplified
```
```
isMinimized
```
- Collapse/expand the ribbon (true/false)
```
enableKeyTips
```
- Enable keyboard shortcuts (true/false)
```
enableRtl
```
- Right-to-left support (true/false)
```
hideLayoutSwitcher
```
- Hide layout switcher button (true/false)
```
layoutSwitcherKeyTip
```
- KeyTip character for the layout switcher button
```
helpPaneTemplate
```
- CSS selector or HTML string for the right-side help pane
```
enablePersistence
```
- Persist ribbon state across page reloads (true/false)
```
locale
```
- Locale string for built-in UI text (e.g.,
```
"en-us"
```
,
```
"fr-FR"
```
)

Key Events:

```
created
```
- Triggered after component creation

tabSelected

- Triggered after tab selection (

args.selectedIndex

args.previousIndex

args.isContextual

)

```
tabSelecting
```
- Triggered before tab selection (
```
args.cancel
```
to prevent,
```
args.isInteracted
```
)
```
ribbonCollapsing
```
- Triggered before ribbon collapses (
```
args.cancel
```
to prevent)
```
ribbonExpanding
```
- Triggered before ribbon expands (
```
args.cancel
```
to prevent)
```
ribbonLayoutSwitched
```
- Triggered after layout switch (
```
args.activeLayout
```
)
```
launcherIconClick
```
- Triggered when a group launcher icon is clicked (
```
args.groupId
```
)
```
overflowPopupOpen
```
- Triggered when overflow popup opens (
```
args.element
```
,
```
args.cancel
```
)
```
overflowPopupClose
```
- Triggered when overflow popup closes (
```
args.element
```
,
```
args.cancel
```
)

核心属性：

```
id
```
- Ribbon的唯一标识符
```
activeLayout
```
- 设置为
```
Classic
```
或
```
Simplified
```
```
isMinimized
```
- 折叠/展开Ribbon（true/false）
```
enableKeyTips
```
- 启用键盘快捷键（true/false）
```
enableRtl
```
- 从右到左支持（true/false）
```
hideLayoutSwitcher
```
- 隐藏布局切换器按钮（true/false）
```
layoutSwitcherKeyTip
```
- 布局切换器按钮的KeyTip字符
```
helpPaneTemplate
```
- 右侧帮助面板的CSS选择器或HTML字符串
```
enablePersistence
```
- 在页面重载时持久化Ribbon状态（true/false）
```
locale
```
- 内置UI文本的区域设置字符串（例如
```
"en-us"
```
、
```
"fr-FR"
```
）

关键事件：

```
created
```
- 组件创建后触发

tabSelected

- 选项卡选中后触发（

args.selectedIndex

、

args.previousIndex

、

args.isContextual

）

```
tabSelecting
```
- 选项卡选中前触发（可通过
```
args.cancel
```
阻止选中，
```
args.isInteracted
```
）
```
ribbonCollapsing
```
- Ribbon折叠前触发（可通过
```
args.cancel
```
阻止折叠）
```
ribbonExpanding
```
- Ribbon展开前触发（可通过
```
args.cancel
```
阻止展开）
```
ribbonLayoutSwitched
```
- 布局切换后触发（
```
args.activeLayout
```
）
```
launcherIconClick
```
- 组启动器图标点击时触发（
```
args.groupId
```
）

overflowPopupOpen

- 溢出弹窗打开时触发（

args.element

、

args.cancel

）

overflowPopupClose

- 溢出弹窗关闭时触发（

args.element

、

args.cancel

）

Quick Start

快速开始

Basic Ribbon with Tabs & Groups

带选项卡与组的基础Ribbon

razor

@using Syncfusion.EJ2
@using Syncfusion.EJ2.Ribbon
@using Syncfusion.EJ2.Navigations

<ejs-ribbon id="ribbon">
    <e-ribbon-tabs>
        <e-ribbon-tab header="Home">
            <e-ribbon-groups>
                <e-ribbon-group header="Clipboard">
                    <e-ribbon-collections>
                        <e-ribbon-collection>
                            <e-ribbon-items>
                                <e-ribbon-item type=Button>
                                    <e-ribbon-buttonsettings iconCss="e-icons e-paste" content="Paste"></e-ribbon-buttonsettings>
                                </e-ribbon-item>
                            </e-ribbon-items>
                        </e-ribbon-collection>
                    </e-ribbon-collections>
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
        <e-ribbon-tab header="Insert">
            <e-ribbon-groups>
                <e-ribbon-group header="Tables">
                    <e-ribbon-collections>
                        <e-ribbon-collection>
                            <e-ribbon-items>
                                <e-ribbon-item type=Button>
                                    <e-ribbon-buttonsettings iconCss="e-icons e-table" content="Table"></e-ribbon-buttonsettings>
                                </e-ribbon-item>
                            </e-ribbon-items>
                        </e-ribbon-collection>
                    </e-ribbon-collections>
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
    </e-ribbon-tabs>
</ejs-ribbon>

razor

@using Syncfusion.EJ2
@using Syncfusion.EJ2.Ribbon
@using Syncfusion.EJ2.Navigations

<ejs-ribbon id="ribbon">
    <e-ribbon-tabs>
        <e-ribbon-tab header="Home">
            <e-ribbon-groups>
                <e-ribbon-group header="Clipboard">
                    <e-ribbon-collections>
                        <e-ribbon-collection>
                            <e-ribbon-items>
                                <e-ribbon-item type=Button>
                                    <e-ribbon-buttonsettings iconCss="e-icons e-paste" content="Paste"></e-ribbon-buttonsettings>
                                </e-ribbon-item>
                            </e-ribbon-items>
                        </e-ribbon-collection>
                    </e-ribbon-collections>
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
        <e-ribbon-tab header="Insert">
            <e-ribbon-groups>
                <e-ribbon-group header="Tables">
                    <e-ribbon-collections>
                        <e-ribbon-collection>
                            <e-ribbon-items>
                                <e-ribbon-item type=Button>
                                    <e-ribbon-buttonsettings iconCss="e-icons e-table" content="Table"></e-ribbon-buttonsettings>
                                </e-ribbon-item>
                            </e-ribbon-items>
                        </e-ribbon-collection>
                    </e-ribbon-collections>
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
    </e-ribbon-tabs>
</ejs-ribbon>

With File Menu

带文件菜单的Ribbon

razor

@{
    List<MenuItem> fileOptions = new List<MenuItem>() {
        new MenuItem { Text = "New", IconCss = "e-icons e-file-new" },
        new MenuItem { Text = "Open", IconCss = "e-icons e-folder-open" },
        new MenuItem { Text = "Save", IconCss = "e-icons e-save" }
    };
}

<ejs-ribbon id="ribbon">
    <e-ribbon-filemenusettings visible="true" menuItems=fileOptions></e-ribbon-filemenusettings>
    <e-ribbon-tabs>
        <!-- tabs -->
    </e-ribbon-tabs>
</ejs-ribbon>

razor

@{
    List<MenuItem> fileOptions = new List<MenuItem>() {
        new MenuItem { Text = "New", IconCss = "e-icons e-file-new" },
        new MenuItem { Text = "Open", IconCss = "e-icons e-folder-open" },
        new MenuItem { Text = "Save", IconCss = "e-icons e-save" }
    };
}

<ejs-ribbon id="ribbon">
    <e-ribbon-filemenusettings visible="true" menuItems=fileOptions></e-ribbon-filemenusettings>
    <e-ribbon-tabs>
        <!-- tabs -->
    </e-ribbon-tabs>
</ejs-ribbon>

Common Patterns

常见模式

Pattern: Multi-Tab Ribbon with Multiple Groups

模式：带多组的多选项卡Ribbon

razor

<ejs-ribbon id="ribbon">
    <e-ribbon-tabs>
        <e-ribbon-tab header="Home">
            <e-ribbon-groups>
                <e-ribbon-group header="Clipboard" orientation=Row>
                    <!-- Items -->
                </e-ribbon-group>
                <e-ribbon-group header="Font" orientation=Row enableGroupOverflow=true>
                    <!-- Items -->
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
        <e-ribbon-tab header="View">
            <e-ribbon-groups>
                <e-ribbon-group header="Views" orientation=Row>
                    <!-- Items -->
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
    </e-ribbon-tabs>
</ejs-ribbon>

razor

<ejs-ribbon id="ribbon">
    <e-ribbon-tabs>
        <e-ribbon-tab header="Home">
            <e-ribbon-groups>
                <e-ribbon-group header="Clipboard" orientation=Row>
                    <!-- Items -->
                </e-ribbon-group>
                <e-ribbon-group header="Font" orientation=Row enableGroupOverflow=true>
                    <!-- Items -->
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
        <e-ribbon-tab header="View">
            <e-ribbon-groups>
                <e-ribbon-group header="Views" orientation=Row>
                    <!-- Items -->
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
    </e-ribbon-tabs>
</ejs-ribbon>

Pattern: Multiple Item Types in Groups

模式：组内包含多种项类型

razor

@{
    List<string> fontOptions = new List<string>() { "Arial", "Calibri", "Cambria", "Georgia" };
}

<e-ribbon-group header="Formatting">
    <e-ribbon-collections>
        <e-ribbon-collection>
            <e-ribbon-items>
                <!-- ComboBox -->
                <e-ribbon-item type=ComboBox>
                    <e-ribbon-comboboxsettings dataSource=fontOptions index=0 width="120px"></e-ribbon-comboboxsettings>
                </e-ribbon-item>
                <!-- ColorPicker -->
                <e-ribbon-item type=ColorPicker allowedSizes=Small>
                    <e-ribbon-colorpickersettings value="#123456"></e-ribbon-colorpickersettings>
                </e-ribbon-item>
                <!-- Toggle Button -->
                <e-ribbon-item type=Button allowedSizes=Small>
                    <e-ribbon-buttonsettings iconCss="e-icons e-bold" isToggle=true></e-ribbon-buttonsettings>
                </e-ribbon-item>
            </e-ribbon-items>
        </e-ribbon-collection>
    </e-ribbon-collections>
</e-ribbon-group>

razor

@{
    List<string> fontOptions = new List<string>() { "Arial", "Calibri", "Cambria", "Georgia" };
}

<e-ribbon-group header="Formatting">
    <e-ribbon-collections>
        <e-ribbon-collection>
            <e-ribbon-items>
                <!-- ComboBox -->
                <e-ribbon-item type=ComboBox>
                    <e-ribbon-comboboxsettings dataSource=fontOptions index=0 width="120px"></e-ribbon-comboboxsettings>
                </e-ribbon-item>
                <!-- ColorPicker -->
                <e-ribbon-item type=ColorPicker allowedSizes=Small>
                    <e-ribbon-colorpickersettings value="#123456"></e-ribbon-colorpickersettings>
                </e-ribbon-item>
                <!-- Toggle Button -->
                <e-ribbon-item type=Button allowedSizes=Small>
                    <e-ribbon-buttonsettings iconCss="e-icons e-bold" isToggle=true></e-ribbon-buttonsettings>
                </e-ribbon-item>
            </e-ribbon-items>
        </e-ribbon-collection>
    </e-ribbon-collections>
</e-ribbon-group>

Pattern: Event Handling

模式：事件处理

razor

<ejs-ribbon id="ribbon"
    tabSelected="onTabSelected"
    tabSelecting="onTabSelecting"
    ribbonLayoutSwitched="onLayoutSwitched"
    launcherIconClick="onLauncherClick">
    <!-- ribbon content -->
</ejs-ribbon>

<script>
    function onTabSelected(args) {
        console.log('Tab selected:', args.selectedIndex);
        console.log('Previous tab:', args.previousIndex);
        console.log('Is contextual:', args.isContextual);
    }

    function onTabSelecting(args) {
        console.log('Tab selecting:', args.selectedIndex);
        // args.cancel = true; // Prevent selection if needed
    }

    function onLayoutSwitched(args) {
        console.log('Layout changed to:', args.activeLayout); // 'Classic' or 'Simplified'
    }

    function onLauncherClick(args) {
        console.log('Launcher clicked for group:', args.groupId);
    }
</script>

razor

<ejs-ribbon id="ribbon"
    tabSelected="onTabSelected"
    tabSelecting="onTabSelecting"
    ribbonLayoutSwitched="onLayoutSwitched"
    launcherIconClick="onLauncherClick">
    <!-- ribbon content -->
</ejs-ribbon>

<script>
    function onTabSelected(args) {
        console.log('Tab selected:', args.selectedIndex);
        console.log('Previous tab:', args.previousIndex);
        console.log('Is contextual:', args.isContextual);
    }

    function onTabSelecting(args) {
        console.log('Tab selecting:', args.selectedIndex);
        // args.cancel = true; // Prevent selection if needed
    }

    function onLayoutSwitched(args) {
        console.log('Layout changed to:', args.activeLayout); // 'Classic' or 'Simplified'
    }

    function onLauncherClick(args) {
        console.log('Launcher clicked for group:', args.groupId);
    }
</script>

Workflow Pattern

工作流模式

When a user needs Ribbon functionality:

Identify scope: Tab organization, item types, file menu, events needed
Start with Getting Started: Installation and basic setup
Choose references based on features:
- Items configuration → items-and-groups.md
- Layout/responsive → layouts-display-modes.md
- File menu → file-menu-backstage.md
- Keyboard/accessibility → events-accessibility.md
- Look & feel → customization-theming.md
Implement patterns following copy-paste examples
Debug issues → troubleshooting.md

当用户需要Ribbon功能时：

确定范围：选项卡组织、项类型、文件菜单、所需事件
从快速入门开始：安装与基础配置
根据功能选择参考文档：
- 项配置 → items-and-groups.md
- 布局/响应式 → layouts-display-modes.md
- 文件菜单 → file-menu-backstage.md
- 键盘/无障碍访问 → events-accessibility.md
- 外观 → customization-theming.md
遵循复制粘贴示例实现模式
调试问题 → troubleshooting.md