syncfusion-aspnetcore-ribbon

Syncfusion ASP.NET Core Ribbon 控件

概述

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

• 将命令组织到选项卡和组中 - 采用选项卡式界面，进行逻辑分组
• 支持 7 种项目类型 - Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton
• 提供文件菜单和后台视图 - 传统文件菜单或现代后台视图
• 按需显示上下文选项卡 - 在需要时显示选项卡（例如，选择图像或表格时）
• 图库项目 - 以可视化方式选择样式、模板或选项
• 响应式布局 - 经典（多行）和简化（紧凑）模式
• 键盘导航 - 使用 KeyTips 通过 Alt+键进行快捷操作
• 符合 WCAG 2.1 标准 - 通过 ARIA 提供全面的无障碍支持
• 内置主题 - Material、Bootstrap、Fluent、Tailwind、Fabric

导航指南

入门

📄 阅读： references/getting-started.md

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

Ribbon 结构

📄 阅读： references/ribbon-structure.md

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

项目和组配置

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

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

选项卡和组管理

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

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

布局和显示模式

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

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

文件菜单和后台视图

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

• 文件菜单基础（<e-ribbon-filemenusettings>）
• 使用 MenuItem 列表配置菜单项
• 后台视图（<e-ribbon-backstagemenusettings>）
• 包含内容的后台项目
• 页脚项目和分隔符
• 自定义返回按钮

上下文选项卡和图库

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

• 按需显示上下文选项卡
• 使用条件控制可见性
• 图库项目（type=Gallery）
• 带标题的图库组
• 图库项目属性（content、iconCss、disabled）
• 可视化选择模式

事件与无障碍功能

📄 阅读： references/events-accessibility.md

• 功能区事件（tabSelected、tabSelecting、itemClick 等）
• KeyTips 配置（enableKeyTips、keyTip 属性）
• 键盘导航
• 符合 WCAG 2.1 标准
• 支持 ARIA 属性
• 支持 RTL（enableRtl）

自定义与主题

📄 阅读： references/customization-theming.md

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

工具提示与帮助

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

• 使用 RibbonTooltipSettings 设置项目工具提示
• 标题与内容属性
• 自定义工具提示 HTML
• 帮助窗格组件模式
• 上下文帮助实现

方法与属性

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

• 功能区方法（getComponent、destroy）
• 关键事件与回调
• 属性访问模式
• 编程式控制
• 状态管理

故障排除

📄 阅读： references/troubleshooting.md

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

关键属性与事件

重要属性：

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

关键事件：

• created - 组件创建后触发
• tabSelected - 选中选项卡后触发（args.selectedIndex、args.previousIndex、args.isContextual）
• tabSelecting - 选中选项卡前触发（可通过 args.cancel 阻止，可检查 args.isInteracted）
• ribbonCollapsing - 功能区折叠前触发（可通过 args.cancel 阻止）
• ribbonExpanding - 功能区展开前触发（可通过 args.cancel 阻止）
• ribbonLayoutSwitched - 切换布局后触发（args.activeLayout）
• launcherIconClick - 点击组启动器图标时触发（args.groupId）
• overflowPopupOpen - 溢出弹出窗口打开时触发（args.element、args.cancel）
• overflowPopupClose - 溢出弹出窗口关闭时触发（args.element、args.cancel）

快速开始

包含选项卡和组的基本功能区

@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>

带文件菜单

@{
    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>
        
    </e-ribbon-tabs>
</ejs-ribbon>

常见模式

模式：包含多个组的多选项卡功能区

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

模式：组中包含多种项目类型

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

<e-ribbon-group header="Formatting">
    <e-ribbon-collections>
        <e-ribbon-collection>
            <e-ribbon-items>
                
                <e-ribbon-item type=ComboBox>
                    <e-ribbon-comboboxsettings dataSource=fontOptions index=0 width="120px"></e-ribbon-comboboxsettings>
                </e-ribbon-item>
                
                <e-ribbon-item type=ColorPicker allowedSizes=Small>
                    <e-ribbon-colorpickersettings value="#123456"></e-ribbon-colorpickersettings>
                </e-ribbon-item>
                
                <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>

模式：事件处理

<ejs-ribbon id="ribbon"
    tabSelected="onTabSelected"
    tabSelecting="onTabSelecting"
    ribbonLayoutSwitched="onLayoutSwitched"
    launcherIconClick="onLauncherClick">
    
</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>

工作流模式

当用户需要功能区功能时：

1. 确定范围：选项卡组织方式、项目类型、文件菜单以及所需事件
2. 从入门指南开始：安装与基本设置
3. 根据功能选择参考文档：
   • 项目配置 → items-and-groups.md
   • 布局/响应式 → layouts-display-modes.md
   • 文件菜单 → file-menu-backstage.md
   • 键盘/无障碍功能 → events-accessibility.md
   • 外观与风格 → customization-theming.md
4. 按照可复制粘贴的示例实现模式
5. 排查问题 → troubleshooting.md

---