syncfusion-angular-ribbon

Syncfusion Angular Ribbon 组件

组件概述

Syncfusion Angular Ribbon 是一款专业的命令界面组件，可将应用程序命令组织成选项卡式功能区，类似于 Microsoft Office。其功能包括：

• 分层命令组织： 选项卡 → 组 → 集合 → 项目，实现清晰的命令结构
• 7 种内置项目类型： 按钮、复选框、下拉列表、分割按钮、组合框、颜色选取器、组按钮和图库
• 双布局模式： 经典（多行）和简化（可折叠）布局，并支持自动调整大小
• 文件菜单和后台视图： 传统文件菜单或现代后台界面，用于文档操作
• 上下文选项卡： 根据用户选择或上下文动态显示的选项卡
• 响应式调整大小： 根据可用宽度自动调整项目大小（大、中、小）
• 键盘导航： 全面支持键盘提示，适用于键盘优先的工作流
• 无障碍功能： 符合 WCAG 标准，支持 ARIA 属性和屏幕阅读器
• RTL 支持： 为阿拉伯语、希伯来语、波斯语和乌尔都语提供从右到左的布局
• 图库项目： 用于主题、样式和配色方案的可视化选择面板
• 帮助窗格： 支持模板的可自定义帮助窗格
• 高级事件系统： 为选项卡选择、折叠/展开、启动器点击和项目交互提供全面的事件
• 高度可配置： 提供丰富的 API，包含 20 多个功能区属性、30 多个项目属性和 10 多个事件

核心概念与层级结构

重要概念：

• 选项卡： 组织主要功能类别（开始、插入、视图）
• 组： 在选项卡内对相关命令进行分组（剪贴板、字体、对齐方式）
• 集合： 在组内对项目进行可视化分组，以便更好地组织
• 项目： 具有 7 种类型的独立命令（按钮、下拉列表、颜色选取器等）
• 布局： 经典（多行）或简化（可折叠），并支持自动切换
• 文件菜单/后台视图： 应用程序级别的操作（新建、打开、保存、打印）

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和包设置（Ivy 与 ngcc）
• CSS 主题导入和依赖项
• 创建第一个 Ribbon
• 添加选项卡和组
• 基本项目和运行应用程序

选项卡、组和项目结构

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

• 选项卡层级和属性
• 在选项卡中添加组
• Ribbon 集合和项目
• 项目大小配置（大、中、小）
• 方向设置（行/列）
• 多个选项卡和组的示例

项目类型和配置

📄 阅读： references/item-types.md

• 全部 7 种内置项目类型
• 按钮项目（切换、禁用状态）
• 复选框、下拉列表、分割按钮项目
• 组合框、颜色选取器、组按钮项目
• 每种类型的完整代码示例
• 项目设置模型和属性

Ribbon 布局和调整大小

📄 阅读： references/layouts.md

• 经典布局（默认多行格式）
• 简化布局（支持折叠）
• 在不同布局间切换
• 项目大小限制和配置
• 响应式调整大小行为
• 布局示例和最佳实践

文件菜单和后台视图

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

• 文件菜单配置和可见性
• 添加带图标和操作的菜单项
• 将后台视图用作文件菜单的替代项
• 后台视图项目和内容
• 页脚项目和分隔符
• 自定义返回按钮
• 目标元素定位
• 完整的文件菜单和后台视图示例

高级功能

📄 阅读： references/advanced-features.md

• 上下文选项卡（动态创建选项卡）
• 用于键盘导航的 Keytips
• 用于可视化选择的图库项
• 帮助窗格模板
• 工具提示配置
• 调整大小行为和响应式设计
• 支持从右向左书写的语言
• 无障碍功能和 WCAG 合规性

事件与交互

📄 阅读： references/events.md

• 选项卡选择事件（tabSelected、tabSelecting）
• 功能区折叠/展开事件
• Backstage 项目点击事件
• 事件参数与取消
• 事件处理模式
• 完整的事件示例

自定义与样式

📄 阅读： references/customization-and-styling.md

• CSS 类自定义
• 主题集成与切换
• 用于样式设置的 CSS 变量
• 自定义样式示例
• 组图标自定义
• 项目自定义与外观
• 启动器图标用法

快速入门示例

下面是一个包含“主页”和“插入”选项卡的最简功能区：

import { Component } from "@angular/core";
import { RibbonModule } from '@syncfusion/ej2-angular-ribbon';
import { RibbonButtonSettingsModel, RibbonSplitButtonSettingsModel } from '@syncfusion/ej2-angular-ribbon';

@Component({
  imports: [ RibbonModule ],
  standalone: true,
  selector: "app-root",
  template: `
    <ejs-ribbon id="ribbon">
      <e-ribbon-tabs>
        <e-ribbon-tab header="Home">
          <e-ribbon-groups>
            <e-ribbon-group header="Clipboard" orientation="Row">
              <e-ribbon-collections>
                <e-ribbon-collection>
                  <e-ribbon-items>
                    <e-ribbon-item type="SplitButton" [splitButtonSettings]="pasteSettings"></e-ribbon-item>
                  </e-ribbon-items>
                </e-ribbon-collection>
                <e-ribbon-collection>
                  <e-ribbon-items>
                    <e-ribbon-item type="Button" [buttonSettings]="cutButton"></e-ribbon-item>
                    <e-ribbon-item type="Button" [buttonSettings]="copyButton"></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="Illustrations" orientation="Row">
              <e-ribbon-collections>
                <e-ribbon-collection>
                  <e-ribbon-items>
                    <e-ribbon-item type="Button" [buttonSettings]="chartButton"></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>
  `,
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  public pasteSettings = { 
    iconCss: "e-icons e-paste", 
    items: [{ text: "Keep Source Format" }, { text: "Merge format" }], 
    content: "Paste" 
  };
  public cutButton: RibbonButtonSettingsModel = { iconCss: "e-icons e-cut", content: "Cut" };
  public copyButton: RibbonButtonSettingsModel = { iconCss: "e-icons e-copy", content: "Copy" };
  public chartButton: RibbonButtonSettingsModel = { iconCss: "e-icons e-chart", content: "Chart" };
}

---

常见模式

模式 1：多选项卡命令界面

1. 为主要功能定义多个选项卡（主页、插入、视图、格式）
2. 在每个选项卡中添加组，以归类相关命令
3. 配置集合，以可视化方式组织项目
4. 使用适当的项目类型（Button、DropDown、ColorPicker）
5. 将 activeLayout 设为 Classic 或 Simplified
6. 处理 tabSelected 事件以执行特定于选项卡的操作

模式 2：将文件菜单与 Backstage 集成

1. 配置 fileMenu 或 backStageMenu 以处理文档操作
2. 添加“新建”“打开”“保存”“打印”“导出”等菜单项
3. 使用 iconCss 设置图标，并为 Backstage 设置内容区域
4. 使用事件处理程序处理菜单项点击
5. 使用页脚项设置选项或账户选项
6. 配置返回按钮以便在 Backstage 中导航

模式 3：使用尺寸优先级实现响应式调整

1. 为项目设置 allowedSizes 数组（Large、Medium、Small）
2. 配置 activeSize 以设置初始显示尺寸
3. 功能区会根据宽度自动调整项目尺寸
4. 主要命令使用 Large，次要命令使用 Small
5. 处理 ribbonCollapsing 事件以实现自定义调整大小逻辑
6. 在不同视口宽度下测试响应式行为

模式 4：使用上下文选项卡提供动态命令

1. 定义包含选项卡配置的 contextualTabs 数组
2. 根据用户选择或上下文设置 visible 属性
3. 使用 isSelected 以编程方式激活上下文选项卡
4. 为上下文命令添加特定于选项卡的组和项目
5. 处理 tabSelected 以检测上下文选项卡是否已激活
6. 根据用户操作动态切换可见性

模式 5：使用 Keytips 进行键盘导航

1. 在功能区组件上启用 enableKeyTips
2. 为选项卡分配 keyTip 属性（主页对应 Alt+H）
3. 为组和单个项目添加 Keytips
4. 配置 layoutSwitcherKeyTip 以切换布局
5. 为文件菜单和 Backstage 项目设置 Keytips
6. 遵循一致的 Keytip 模式（Alt+字母组合）

模式 6：使用图库项进行可视化选择

1. 为可视化面板配置 type="Gallery" 的项目
2. 使用组和项目定义 gallerySettings
3. 设置 itemCount、popupWidth、popupHeight 以控制显示
4. 使用模板自定义图库项的渲染方式
5. 处理图库项点击的选择事件
6. 常见用例：主题、样式、颜色、表格设计

---

关键属性与事件

核心功能区配置

属性	类型	默认值	使用场景
tabs	RibbonTabModel[]	[]	定义包含组和项目的功能区选项卡
activeLayout	LayoutType	'Classic'	设置布局模式（Classic 或 Simplified）
selectedTab	number	0	设置或获取当前活动选项卡的索引
isMinimized	boolean	false	控制功能区的最小化状态

布局与外观

属性	类型	默认值	使用场景
width	string | number	'100%'	设置功能区容器宽度
cssClass	string	''	应用自定义 CSS 类以设置样式和主题
hideLayoutSwitcher	boolean	false	隐藏经典/简化布局切换按钮
tabAnimation	object	null	配置选项卡切换动画设置

键盘与无障碍功能

属性	类型	默认值	使用场景
enableKeyTips	boolean	false	启用键盘导航键提示（Alt+ 快捷键）
layoutSwitcherKeyTip	string	''	设置布局切换按钮的键提示
launcherIconCss	string	''	所有组中启动器图标的默认 CSS 类

文件菜单与后台视图

属性	类型	默认值	使用场景
fileMenu	FileMenuSettingsModel	null	配置传统文件菜单（新建、打开、保存、打印）
backStageMenu	BackStageMenuModel	null	配置现代后台视图（替代文件菜单）

高级功能

属性	类型	默认值	使用场景
contextualTabs	RibbonContextualTabModel[]	[]	定义根据上下文或选择内容显示的选项卡
helpPaneTemplate	string	''	帮助窗格内容的自定义模板

本地化

属性	类型	默认值	使用场景
locale	string	'en-US'	设置本地化语言/区域
enableRtl	boolean	false	启用从右到左的布局（阿拉伯语、希伯来语、波斯语、乌尔都语）
enablePersistence	boolean	false	在页面重新加载时保存功能区状态

选项卡配置

属性	类型	默认值	使用场景
header	string	''	选项卡显示文本（主页、插入、视图）
groups	RibbonGroupModel[]	[]	选项卡内的组数组
id	string	''	选项卡的唯一标识符
keyTip	string	''	键盘快捷键键提示（H 表示主页）

组配置

属性	类型	默认值	使用场景
header	string	''	组显示文本（剪贴板、字体、对齐方式）
orientation	ItemOrientation	'Column'	布局方向（行或列）
enableGroupOverflow	boolean	false	组无法容纳时显示溢出下拉菜单
isCollapsible	boolean	true	允许组在简化布局中折叠
showLauncherIcon	boolean	false	显示用于启动对话框/窗格的启动器图标
groupIconCss	string	''	溢出/启动器中组图标的 CSS 类

项目配置

属性	类型	默认值	使用场景
type	RibbonItemType	'Button'	项目类型：Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton、Gallery
id	string	''	项目的唯一标识符
allowedSizes	RibbonItemSize[]	['Large', 'Medium', 'Small']	项目可调整到的尺寸（响应式行为）
activeSize	RibbonItemSize	'Medium'	项目的当前显示尺寸
disabled	boolean	false	禁用项目，阻止用户交互
displayOptions	DisplayMode	'Auto'	控制显示方式（Auto、Classic、Simplified、Overflow）
cssClass	string	''	用于项目样式的自定义 CSS 类
keyTip	string	''	项目的键盘快捷键提示
ribbonTooltipSettings	TooltipSettingsModel	null	工具提示配置（id、title、content、iconCss、cssClass）
itemTemplate	string	''	用于渲染项目的自定义模板
buttonSettings	RibbonButtonSettingsModel	null	Button 专属设置（iconCss、content、clicked）
dropDownSettings	RibbonDropDownSettingsModel	null	DropDown 专属设置（iconCss、content、items）
splitButtonSettings	RibbonSplitButtonSettingsModel	null	SplitButton 专属设置（iconCss、items、clicked）
checkBoxSettings	RibbonCheckBoxSettingsModel	null	CheckBox 专属设置（label、checked、change）
colorPickerSettings	RibbonColorPickerSettingsModel	null	ColorPicker 专属设置（value、change）
comboBoxSettings	RibbonComboBoxSettingsModel	null	ComboBox 专属设置（dataSource、value、fields）
groupButtonSettings	RibbonGroupButtonSettingsModel	null	GroupButton 专属设置（items、selected）
gallerySettings	RibbonGallerySettingsModel	null	Gallery 配置（groups、items、itemCount、popupWidth、popupHeight、template）

文件菜单配置

属性	类型	默认值	使用场景
visible	boolean	false	显示/隐藏文件菜单按钮
text	string	'File'	文件菜单按钮文本
menuItems	FileMenuItemModel[]	[]	菜单项数组（New、Open、Save、Print）
itemTemplate	string	''	菜单项的自定义模板
popupTemplate	string	''	整个弹出窗口的自定义模板
keyTip	string	''	文件菜单的按键提示（F 表示 File）
ribbonTooltipSettings	TooltipSettingsModel	null	文件菜单按钮的工具提示设置

Backstage 配置

属性	类型	默认值	使用场景
visible	boolean	false	显示/隐藏 Backstage 视图
text	string	'File'	Backstage 按钮文本
items	BackStageItemModel[]	[]	Backstage 项（id、text、iconCss、content、separator、isFooter）
backButton	BackButtonModel	null	返回按钮配置（text、iconCss、visible）
width	string	'auto'	Backstage 宽度
height	string	'auto'	Backstage 高度
target	HTMLElement	null	用于定位 Backstage 的元素
template	string	''	Backstage 内容的自定义模板
keyTip	string	''	Backstage 按钮的按键提示
ribbonTooltipSettings	TooltipSettingsModel	null	Backstage 按钮的工具提示设置

上下文选项卡配置

属性	类型	默认值	使用场景
visible	boolean	false	显示/隐藏上下文选项卡组
isSelected	boolean	false	上下文选项卡是否处于激活状态
tabs	RibbonTabModel[]	[]	上下文组中的选项卡数组

关键事件

事件	参数	使用时机
(tabSelected)	TabSelectedEventArgs	选中选项卡后（获取选项卡索引和数据）
(tabSelecting)	TabSelectingEventArgs	选中选项卡前（可取消，用于验证选择）
(ribbonCollapsing)	RibbonCollapsingEventArgs	功能区折叠前（可取消）
(ribbonExpanded)	RibbonExpandedEventArgs	功能区展开后
(launcherClick)	LauncherClickEventArgs	单击启动器图标时（打开对话框/窗格）
(overflowPopupOpen)	OverflowPopupEventArgs	溢出弹出窗口打开前（可取消）
(overflowPopupClose)	OverflowPopupEventArgs	溢出弹出窗口关闭前（可取消）
(layoutSwitched)	LayoutSwitchedEventArgs	在经典/简化布局之间切换时
(backStageItemClick)	BackStageItemClickEventArgs	单击 Backstage 项目时

文件菜单事件

事件	参数	使用时机
beforeOpen	BeforeOpenCloseMenuEventArgs	文件菜单打开前（可取消）
open	OpenCloseMenuEventArgs	文件菜单打开后
beforeClose	BeforeOpenCloseMenuEventArgs	文件菜单关闭前（可取消）
close	OpenCloseMenuEventArgs	文件菜单关闭后
beforeItemRender	MenuEventArgs	菜单项渲染前（自定义渲染）
select	MenuEventArgs	选中菜单项时

---