syncfusion-javascript-ribbon

Syncfusion JavaScript 功能区控件

概览

Syncfusion JavaScript 功能区控件是一种分层导航组件，可将命令组织为：

• 选项卡：顶层类别（Home、Insert、View）
• 组：选项卡中的相关命令集（Clipboard、Font、Tables）
• 集合：组内用于组织内容的容器
• 项：单个控件（按钮、下拉列表、图库等）

主要功能：

• 8 种内置项类型，提供丰富的配置选项
• 2 种布局模式：经典布局（多行）和简化布局（单行）
• 高级功能：文件菜单、Backstage、上下文选项卡、图库项
• 支持键盘导航，可自定义按键提示
• 自动响应式调整大小，并处理溢出
• 丰富的用户交互事件系统
• 基于模块的架构，可按需加载功能

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装 Ribbon 包
• 基本功能区设置与初始化
• 模块注入（默认模块和选择性模块）
• 创建选项卡、组、集合和项
• CSS 导入与主题配置
• 包含多个选项卡的首个可运行示例

功能区架构

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

• 添加带有自定义标题的选项卡
• 定义带有标题和图标的组
• 组方向（行布局与列布局）
• 添加集合并组织项
• 组启动器图标（showLauncherIcon、用于自定义的 launcherIconCss）
• 可折叠组和优先级顺序
• 组溢出行为

内置项

📄 阅读： references/built-in-items.md

• 按钮项（标准按钮和切换按钮）
• 复选框项（标签、选中状态、标签位置）
• 下拉列表项（目标内容、项自定义、按需弹出）
• 分割按钮项（主要操作 + 下拉菜单）
• 组合框项（数据绑定、筛选、模板）
• 颜色选取器项（颜色选择和预设）
• 组按钮项（单选/多选）
• 比较不同项类型及其适用场景

图库项

📄 阅读： references/gallery-items.md

• 图库概览和使用场景
• 将项组织成组
• 定义项内容、图标和属性
• 自定义图库项外观（cssClass）
• 禁用特定图库项
• 设置组标题和项尺寸
• 配置显示的项数
• 预选项（selectedItemIndex）
• 设置弹出窗口尺寸
• 为项和弹出窗口使用自定义模板

布局与显示

📄 阅读： references/layouts.md

• 经典布局（多行显示）
• 简化布局（单行显示）
• 定义项尺寸（大、中、小）
• 设置项允许使用的尺寸
• 项方向（行与列）
• 组图标和自定义
• 启用启动器图标
• 组的可折叠状态和优先级
• 启用组溢出弹出窗口
• 最小化状态（折叠/展开）
• 显示/隐藏布局切换器
• 选项卡动画配置

注意： 如需处理布局更改，请参阅 references/events-and-api.md 中的 ribbonLayoutSwitched 事件

文件菜单

📄 阅读： references/file-menu.md

• 文件菜单的可见性和配置
• 添加带图标的菜单项
• 单击时显示子菜单（showItemOnClick）
• 自定义文件菜单标题文本
• 菜单项模板
• 文件菜单事件（beforeOpen、select、close）

Backstage 菜单

📄 阅读： references/backstage.md

• Backstage 概览和使用场景
• 添加带内容的 Backstage 项
• 页脚项（isFooter 属性）
• 在项之间添加分隔符
• 自定义返回按钮（文本、图标）
• 设置 Backstage 目标元素
• 使用模板创建自定义布局
• 配置宽度和高度
• Backstage 事件（项单击、打开、关闭）

上下文选项卡

📄 阅读： references/contextual-tabs.md

• 上下文选项卡概述
• 控制选项卡的可见性
• 动态添加上下文选项卡
• 设置选中的上下文选项卡（isSelected）
• 使用场景（表格编辑、图像编辑、图表工具）

按键提示

📄 阅读： references/keytips.md

• 启用按键提示导航
• 为选项卡、组和项目分配按键提示
• 按键提示显示（Alt + Windows/Command 键）
• 自定义按键提示内容
• 按键提示导航流程

工具提示和帮助窗格

📄 阅读： references/tooltip-and-help.md

• 为项目添加工具提示标题
• 使用说明设置工具提示内容
• 为工具提示添加图标
• 自定义工具提示外观（cssClass）
• 配置帮助窗格模板
• 帮助窗格的位置和内容

调整大小行为

📄 阅读： references/resizing.md

• Classic 模式下自动调整大小
• Simplified 模式下自动调整大小
• 定义固定的项目尺寸（allowedSizes）
• 设置初始项目尺寸（activeSize）
• 了解项目尺寸的变化

事件和 API

📄 阅读： references/events-and-api.md

• 选项卡选择事件（tabSelected、tabSelecting）
• 功能区展开/折叠事件
• 布局切换事件（ribbonLayoutSwitched — 响应 Classic/Simplified 模式更改）
• 启动器图标点击事件
• 溢出弹出窗口事件（打开、关闭）
• Button、CheckBox 和 DropDown 项目事件
• SplitButton、ColorPicker 和 Gallery 事件
• ComboBox 筛选和选择事件
• 常用 API 方法（addTab、removeTab、addGroup、addItem 等）
• 高级 API 方法（selectTab、getItem、getRootElement、refreshLayout、updateTab/Group/Item/Collection）

快速入门示例

import { Ribbon, RibbonTabModel, RibbonItemType, RibbonFileMenu } from "@syncfusion/ej2-ribbon";
import { MenuItemModel } from "@syncfusion/ej2-navigations";

// Inject required modules
Ribbon.Inject(RibbonFileMenu);

// Define tabs with groups and items
let tabs: RibbonTabModel[] = [{
    header: "Home",
    groups: [{
        header: "Clipboard",
        collections: [{
            items: [{
                type: RibbonItemType.SplitButton,
                splitButtonSettings: {
                    iconCss: "e-icons e-paste",
                    content: "Paste",
                    items: [
                        { text: "Keep Source Format" },
                        { text: "Merge Format" },
                        { text: "Keep Text Only" }
                    ]
                }
            }]
        }, {
            items: [{
                type: RibbonItemType.Button,
                buttonSettings: {
                    content: "Cut",
                    iconCss: "e-icons e-cut"
                }
            }, {
                type: RibbonItemType.Button,
                buttonSettings: {
                    content: "Copy",
                    iconCss: "e-icons e-copy"
                }
            }]
        }]
    }]
}, {
    header: "Insert",
    groups: [{
        header: "Tables",
        collections: [{
            items: [{
                type: RibbonItemType.DropDown,
                dropDownSettings: {
                    iconCss: "e-icons e-table",
                    content: "Table",
                    items: [
                        { text: "Insert Table" },
                        { text: "Draw Table" }
                    ]
                }
            }]
        }]
    }]
}];

// Define file menu items
let fileMenuItems: MenuItemModel[] = [
    { text: "New", iconCss: "e-icons e-file-new", id: "new" },
    { text: "Open", iconCss: "e-icons e-folder-open", id: "open" },
    { text: "Save", iconCss: "e-icons e-save", id: "save" }
];

// Create Ribbon instance
let ribbon: Ribbon = new Ribbon({
    tabs: tabs,
    fileMenu: {
        menuItems: fileMenuItems,
        visible: true
    }
});

// Render to element
ribbon.appendTo("#ribbon");

常见模式

动态添加新选项卡

// Add a new tab to existing ribbon
ribbon.addTab({
    header: "View",
    groups: [{
        header: "Views",
        collections: [{
            items: [{
                type: RibbonItemType.Button,
                buttonSettings: {
                    content: "Print Layout",
                    iconCss: "e-icons e-print"
                }
            }]
        }]
    }]
});

在不同布局之间切换

// Switch to Simplified layout
ribbon.activeLayout = "Simplified";

// Switch to Classic layout
ribbon.activeLayout = "Classic";

处理项目点击事件

let tabs: RibbonTabModel[] = [{
    header: "Home",
    groups: [{
        header: "Actions",
        collections: [{
            items: [{
                type: RibbonItemType.Button,
                buttonSettings: {
                    content: "Save",
                    iconCss: "e-icons e-save",
                    clicked: () => {
                        console.log("Save button clicked");
                        // Your save logic here
                    }
                }
            }]
        }]
    }]
}];

启用上下文选项卡

let ribbon: Ribbon = new Ribbon({
    tabs: tabs,
    contextualTabs: [{
        visible: true,
        isSelected: true,
        tabs: [{
            header: "Table Design",
            groups: [{
                header: "Styles",
                collections: [{
                    items: [{
                        type: RibbonItemType.Gallery,
                        gallerySettings: {
                            groups: [{
                                header: "Table Styles",
                                items: [
                                    { content: "Light" },
                                    { content: "Dark" }
                                ]
                            }]
                        }
                    }]
                }]
            }]
        }]
    }]
});

关键属性

• tabs：选项卡配置数组（必需）
• activeLayout："Classic" | "Simplified"（默认值："Classic"）
• fileMenu：包含菜单项的文件菜单配置
• backStageMenu：包含项目和内容的 Backstage 配置
• contextualTabs：上下文选项卡配置数组
• enableKeyTips：启用/禁用按键提示导航（默认值：false）
• isMinimized：为 true 时仅显示选项卡标题（默认值：false）
• hideLayoutSwitcher：显示/隐藏布局切换按钮（默认值：false）
• helpPaneTemplate：用于右侧帮助窗格的自定义模板
• launcherIconCss：组启动器图标的 CSS 类
• selectedTab：当前选中选项卡的索引（默认值：0）

常见使用场景

使用场景 1：文档编辑器功能区

当用户需要功能齐全的文档编辑器来设置文本格式时：

• 创建包含 Font、Paragraph 和 Styles 组的 Home 选项卡
• 使用 ComboBox 选择字体系列和字号
• 添加用于文本格式设置的 GroupButton（粗体、斜体、下划线）
• 添加用于文本颜色和突出显示颜色的 ColorPicker
• 实现包含 Tables 和 Pictures 组的 Insert 选项卡
• 添加用于 New、Open、Save 操作的 File 菜单

使用场景 2：数据网格应用程序

当用户需要以数据为中心的功能区界面时：

• 创建包含基本操作（Add、Edit、Delete）的 Home 选项卡
• 添加包含 Import/Export、Filter 和 Sort 组的 Data 选项卡
• 使用 Gallery 项目提供预定义的数据模板
• 实现包含显示选项（网格样式、缩放）的 View 选项卡
• 在选中行时添加上下文选项卡
• 使用 Simplified 布局实现紧凑显示

使用场景 3：带上下文选项卡的设计工具

当用户需要特定对象的命令时：

• 为常用工具创建基础选项卡（Home、Insert、View）
• 为选中的对象添加上下文选项卡（Image Tools、Shape Tools）
• 使用 Gallery 提供样式预设和模板
• 实现用于文件操作和设置的 backstage
• 为键盘高级用户启用按键提示
• 添加包含撤销/重做按钮的帮助窗格

用例 4：移动端响应式应用

当用户需要功能区在较小屏幕上正常工作时：

• 默认使用简化布局
• 启用组溢出弹出窗口（enableGroupOverflow: true）
• 设置项目优先级，以便智能折叠
• 为关键项目定义 allowedSizes
• 使用最小化状态以最大限度地腾出内容空间
• 实现溢出弹出窗口事件以进行分析

用例 5：键盘驱动的工作流

当用户优先考虑键盘导航时：

• 启用键提示（enableKeyTips: true）
• 为所有选项卡、组和项目分配符合逻辑的键提示
• 添加带有键盘快捷键提示的工具提示
• 实现选项卡选择事件，以提供键盘操作反馈
• 使用 CheckBox 项目表示可切换的选项
• 添加包含键盘快捷键参考的帮助窗格