syncfusion-react-ribbon

Syncfusion React Ribbon

组件概述

Syncfusion React Ribbon 组件是一款专业且功能丰富的工具栏，旨在创建受 Microsoft Office 启发、以命令为中心的用户界面。它提供直观的层级结构，将相关命令组织到视觉上清晰区分的选项卡和组中，帮助用户快速查找并执行操作。

主要功能

• 选项卡式功能区界面：将命令组织到逻辑选项卡中，便于导航和分组
• 双布局模式：支持经典（多行）和简化（单行）布局，并可动态切换
• 多种项目类型：按钮、复选框、下拉菜单、分割按钮、组合框、颜色选取器、组按钮、图库和自定义模板
• 响应式调整大小：根据可用空间自动调整项目大小（大、中、小）
• 文件菜单和 Backstage 视图：提供完整的文件菜单，支持传统文件菜单或现代 Backstage 界面
• 上下文选项卡：根据用户选择或应用程序状态动态显示/隐藏选项卡
• 图库支持：提供可视化选择图库，支持分组、筛选和自定义项目模板
• KeyTips 和键盘导航：以无障碍访问为先，支持 KeyTip 的键盘导航
• 组溢出管理：控制组优先级，并提供专用溢出弹出窗口，以更好地利用空间
• 丰富的自定义选项：自定义 CSS 类、项目模板、图标和布局控制
• 全面的事件处理：支持 itemClick、tabSelected、fileMenuSelect 等事件，实现精确控制
• 多主题支持：支持 Material、Bootstrap、Fluent 和 Tailwind CSS 主题，并提供深色模式
• RTL 和无障碍访问：全面支持从右向左书写的语言，并通过 ARIA 属性符合 WCAG 标准
• 帮助窗格集成：内置帮助窗格，提供上下文相关的帮助和文档

层级结构：

• 功能区（根容器）- 主工具栏组件
  • 选项卡（例如 Home、Insert、View、Design）- 逻辑命令分组
    • 组（例如 Clipboard、Font、Styles）- 相关命令类别
      • 集合（逻辑项目容器）- 项目排列辅助工具
        • 项目（按钮、下拉菜单、图库、颜色选取器等）- 单个命令和控件

文档

入门指南

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 基本功能区组件实现
• CSS 导入和主题
• 第一个可运行示例
• TypeScript 配置

功能区结构

📄 阅读： references/ribbon-structure.md

• 创建和配置选项卡
• 组的组织和层级结构
• 集合和项目容器
• 选项卡标题属性
• 组标题和图标
• 项目大小和方向

项目和组

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

• 内置项目类型（Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton、Template）
• 项目属性和图标
• 项目大小（大、中、小）和活动大小控制
• 使用自定义类自定义项目 CSS
• 使用 RibbonTooltipSettings 设置项目工具提示
• 用于自定义呈现的项目模板
• 禁用状态和显示选项
• 组方向（行或列）
• 组溢出行为和优先级

选项卡和组配置

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

• 添加和管理选项卡
• 选项卡级别的配置和 CSS 自定义
• 使用自定义类和主题设置选项卡样式
• 组属性和组织
• 组标题和图标
• 组的可折叠性和启动器图标
• 动态管理选项卡/组

布局和显示模式

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

• 经典布局（传统多行格式）
• 简化布局（紧凑单行格式）
• 布局切换和布局切换按钮
• 项目显示选项（Auto、Classic、Simplified、Overflow）
• 响应式调整大小行为
• 调整大小时的项目尺寸适配
• 最小化状态（功能区折叠）

文件菜单和 Backstage

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

• 文件菜单配置和可见性
• 用于自定义渲染的文件菜单项目模板
• 文件菜单弹出窗口模板
• 文件菜单动画设置
• 文件菜单工具提示配置
• 完整的事件处理（beforeOpen、open、beforeClose、close、beforeItemRender、select）
• Backstage 视图实现
• 使用高级选项配置 Backstage 项目
• Backstage 尺寸（宽度、高度）和位置
• Backstage KeyTip 集成
• Backstage 工具提示设置
• 页脚项目和分隔符
• 自定义返回按钮
• 自定义 Backstage 模板
• 在 Backstage 中导航

上下文选项卡和图库

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

• 创建上下文选项卡
• 控制上下文选项卡的可见性
• 以编程方式显示/隐藏上下文选项卡
• 图库项目配置
• 图库组和项目
• 图库项目模板
• 图库筛选和选择
• 弹出窗口宽度和高度

事件和无障碍功能

📄 阅读： references/events-accessibility.md

• 功能区事件（itemClick、tabSelected 等）
• 事件处理和回调
• 使用 KeyTips 的键盘快捷键
• KeyTip 配置
• 无障碍合规性（WCAG）
• ARIA 属性
• 屏幕阅读器支持
• RTL 支持
• 焦点管理
• 键盘导航

自定义和主题

📄 阅读： references/customization-theming.md

• 可用的内置主题（Material、Bootstrap、Fluent、Tailwind）
• 导入和应用主题
• CSS 自定义
• 自定义图标字体
• Theme Studio 集成
• 深色模式支持
• 响应式设计注意事项
• 自定义 CSS 类

工具提示和帮助窗格

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

• 为项目实现工具提示
• 自定义工具提示模板
• 帮助窗格配置
• 帮助窗格模板和内容
• 上下文帮助集成

故障排除

📄 阅读： references/troubleshooting.md

• 常见问题和解决方案
• 性能优化提示
• 样式和显示问题
• 事件处理问题
• 模块注入故障排除
• 响应式行为问题

快速入门

带选项卡和组的基本功能区

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";
@import "@syncfusion/ej2-tailwind3-theme/styles/ribbon/index.css";

function App() {
  return (
    <RibbonComponent id="ribbon">
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-copy", content: "Copy" }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-paste", content: "Paste" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

带文件菜单的功能区

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective, RibbonFileMenu, Inject } from "@syncfusion/ej2-react-ribbon";
import { MenuItemModel } from '@syncfusion/ej2-navigations';

function App() {
  const fileOptions: 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" },
    { text: "Save as", iconCss: "e-icons e-save", id: "saveas" }
  ];

  return (
    <RibbonComponent id="ribbon" fileMenu={{ visible: true, menuItems: fileOptions }}>
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
      <Inject services={[RibbonFileMenu]} />
    </RibbonComponent>
  );
}

export default App;

常见模式

模式 1：包含多种项目类型的多选项卡功能区

构建专业的功能区，其中包含多个选项卡，每个选项卡包含不同类型的项目（按钮、下拉菜单、组合框）。

模式 2：采用经典和简化布局的响应式功能区

创建一个可根据屏幕尺寸或用户偏好，在经典（多行）和简化（单行）布局之间切换的功能区。

模式 3：上下文感知功能区

在用户选择特定对象或内容类型时，动态显示/隐藏上下文选项卡。

模式 4：带 Backstage 视图的文件菜单

将文件菜单与 Backstage 结合，用于全面管理文档和应用程序设置。

模式 5：基于图库的项目选择

使用图库，以可视化方式选择样式、模板或格式选项。

关键属性和功能

RibbonComponent：

• fileMenu - 配置文件菜单的可见性和菜单项
• backStageMenu - 启用并配置后台视图
• activeLayout - 设置布局模式（Classic、Simplified）
• isMinimized - 以编程方式最小化/展开功能区
• hideLayoutSwitcher - 隐藏布局切换按钮

RibbonTabDirective：

• header - 选项卡标题文本
• cssClass - 用于设置选项卡样式的自定义 CSS 类

RibbonGroupDirective：

• header - 组标题
• orientation - 项目对齐方式（Row、Column）
• groupIconCss - 用于组溢出菜单的自定义图标
• showLauncherIcon - 显示启动器图标
• enableGroupOverflow - 为组启用专用溢出弹出窗口
• isCollapsible - 允许组在调整大小时折叠
• priority - 折叠/展开优先级

RibbonItemDirective：

• type - 项目类型（Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton、Gallery、Template）
• allowedSizes - 允许的项目尺寸（Large、Medium、Small）
• activeSize - 项目的当前显示尺寸
• cssClass - 用于设置项目样式的自定义 CSS 类
• ribbonTooltipSettings - 包含标题和内容的工具提示配置
• itemTemplate - 用于渲染项目的自定义模板
• displayOptions - 在不同布局中的可见性（Auto、Classic、Simplified、Overflow）
• disabled - 启用/禁用项目
• 设置对象：buttonSettings、dropDownSettings、splitButtonSettings 等

如需查看完整示例和高级场景，请浏览上方各个参考文件。