syncfusion-react-ribbon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion React Ribbon

Component Overview

组件概述

The Syncfusion React Ribbon component is a professional, feature-rich toolbar designed for creating command-centric user interfaces inspired by Microsoft Office. It provides an intuitive hierarchical structure that organizes related commands into visually distinct tabs and groups, enabling users to quickly discover and execute actions.

Syncfusion React Ribbon组件是一款专业、功能丰富的工具栏，灵感源自Microsoft Office，用于创建以命令为中心的用户界面。它提供直观的层级结构，将相关命令组织到视觉区分明显的选项卡和组中，帮助用户快速找到并执行操作。

Key Capabilities

核心功能

Tabbed Ribbon Interface: Organize commands into logical tabs for easy navigation and grouping
Dual Layout Modes: Support for Classic (multi-row) and Simplified (single-row) layouts with dynamic switching
Multiple Item Types: Buttons, checkboxes, dropdowns, split buttons, combo boxes, color pickers, group buttons, galleries, and custom templates
Responsive Resizing: Automatically adjust item sizes (Large, Medium, Small) based on available space
File Menu & Backstage View: Complete file menu with traditional File menu or modern backstage interface
Contextual Tabs: Show/hide tabs dynamically based on user selection or application state
Gallery Support: Visual selection galleries with grouping, filtering, and custom item templates
KeyTips & Keyboard Navigation: Accessibility-first keyboard navigation with KeyTip support
Group Overflow Management: Control group priority and dedicated overflow popups for better space utilization
Rich Customization: Custom CSS classes, item templates, icons, and layout control
Comprehensive Event Handling: itemClick, tabSelected, fileMenuSelect, and more for precise control
Multi-Theme Support: Material, Bootstrap, Fluent, and Tailwind CSS themes with dark mode
RTL & Accessibility: Full right-to-left language support and WCAG compliance with ARIA attributes
Help Pane Integration: Built-in help pane for contextual assistance and documentation

Hierarchical Structure:

Ribbon (root container) - Main toolbar component
- Tabs (e.g., Home, Insert, View, Design) - Logical command groupings
  - Groups (e.g., Clipboard, Font, Styles) - Related command categories
    - Collections (logical item containers) - Item arrangement helpers
      - Items (buttons, dropdowns, galleries, color pickers, etc.) - Individual commands and controls

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

层级结构：

Ribbon（根容器）- 主工具栏组件
- Tabs（如：主页、插入、视图、设计）- 逻辑命令分组
  - Groups（如：剪贴板、字体、样式）- 相关命令类别
    - Collections（逻辑项容器）- 项排列辅助容器
      - Items（按钮、下拉菜单、图库、颜色选择器等）- 单个命令和控件

Documentation

文档

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup
Basic ribbon component implementation
CSS imports and themes
First working example
TypeScript configuration

📄 阅读： references/getting-started.md

安装与包配置
基础Ribbon组件实现
CSS导入与主题
第一个可用示例
TypeScript配置

Ribbon Structure

Ribbon结构

📄 Read: references/ribbon-structure.md

Tabs creation and configuration
Groups organization and hierarchy
Collections and item containers
Tab header properties
Group headers and icons
Item size and orientation

📄 阅读： references/ribbon-structure.md

选项卡创建与配置
组的组织与层级
集合与项容器
选项卡头部属性
组头部与图标
项尺寸与方向

Items and Groups

项与组

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

Built-in item types (Button, CheckBox, DropDown, SplitButton, ComboBox, ColorPicker, GroupButton, Template)
Item properties and icons
Item sizes (Large, Medium, Small) and active size control
Item CSS customization with custom classes
Item tooltips with RibbonTooltipSettings
Item templates for custom rendering
Disabled state and display options
Group orientation (Row vs Column)
Group overflow behavior and priority

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

内置项类型（按钮、复选框、下拉菜单、拆分按钮、组合框、颜色选择器、组按钮、模板）
项属性与图标
项尺寸（大、中、小）及活动尺寸控制
使用自定义类进行项CSS自定义
带有RibbonTooltipSettings的项工具提示
用于自定义渲染的项模板
禁用状态与显示选项
组方向（行 vs 列）
组溢出行为与优先级

Tabs and Groups Configuration

选项卡与组配置

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

Adding and managing tabs
Tab-level configuration and CSS customization
Tab styling with custom classes and themes
Group properties and organization
Group headers and icons
Group collapsibility and launcher icons
Dynamic tab/group management

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

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

Layouts and Display Modes

布局与显示模式

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

Classic layout (traditional multi-row format)
Simplified layout (single-row compact format)
Layout switching and the layout switcher button
Display options for items (Auto, Classic, Simplified, Overflow)
Responsive resizing behavior
Item size adaptation during resizing
Minimized state (ribbon collapse)

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

经典布局（传统多行格式）
简化布局（单行紧凑格式）
布局切换与布局切换按钮
项的显示选项（自动、经典、简化、溢出）
响应式调整行为
调整尺寸时的项尺寸适配
最小化状态（Ribbon折叠）

File Menu and Backstage

文件菜单与后台

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

File menu configuration and visibility
File menu item templates for custom rendering
File menu popup templates
File menu animation settings
File menu tooltip configuration
Complete event handling (beforeOpen, open, beforeClose, close, beforeItemRender, select)
Backstage view implementation
Backstage items configuration with advanced options
Backstage dimensions (width, height) and positioning
Backstage KeyTip integration
Backstage tooltip settings
Footer items and separators
Back button customization
Custom backstage templates
Navigation within backstage

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

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

Contextual Tabs and Gallery

上下文选项卡与图库

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

Creating contextual tabs
Controlling contextual tab visibility
Showing/hiding contextual tabs programmatically
Gallery item configuration
Gallery groups and items
Gallery item templates
Gallery filtering and selection
Popup width and height

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

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

Events and Accessibility

事件与无障碍访问

📄 Read: references/events-accessibility.md

Ribbon events (itemClick, tabSelected, etc.)
Event handling and callbacks
Keyboard shortcuts with KeyTips
KeyTip configuration
Accessibility compliance (WCAG)
ARIA attributes
Screen reader support
RTL support
Focus management
Keyboard navigation

📄 阅读： references/events-accessibility.md

Ribbon事件（itemClick、tabSelected等）
事件处理与回调
带有KeyTips的键盘快捷键
KeyTip配置
无障碍访问合规性（WCAG）
ARIA属性
屏幕阅读器支持
RTL支持
焦点管理
键盘导航

Customization and Theming

自定义与主题

📄 Read: references/customization-theming.md

Available built-in themes (Material, Bootstrap, Fluent, Tailwind)
Importing and applying themes
CSS customization
Custom icon fonts
Theme Studio integration
Dark mode support
Responsive design considerations
Custom CSS classes

📄 阅读： references/customization-theming.md

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

Tooltips and Help Pane

工具提示与帮助窗格

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

Tooltip implementation for items
Custom tooltip templates
Help pane configuration
Help pane templates and content
Contextual help integration

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

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

Troubleshooting

故障排查

📄 Read: references/troubleshooting.md

Common issues and solutions
Performance optimization tips
Styling and display issues
Event handling problems
Module injection troubleshooting
Responsive behavior issues

📄 阅读： references/troubleshooting.md

常见问题与解决方案
性能优化技巧
样式与显示问题
事件处理问题
模块注入故障排查
响应式行为问题

Quick Start

快速开始

Basic Ribbon with Tabs and Groups

带选项卡与组的基础Ribbon

tsx

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";
import "@syncfusion/ej2-base/styles/tailwind3.css";
import "@syncfusion/ej2-buttons/styles/tailwind3.css";
import "@syncfusion/ej2-popups/styles/tailwind3.css";
import "@syncfusion/ej2-splitbuttons/styles/tailwind3.css";
import "@syncfusion/ej2-inputs/styles/tailwind3.css";
import "@syncfusion/ej2-lists/styles/tailwind3.css";
import "@syncfusion/ej2-dropdowns/styles/tailwind3.css";
import "@syncfusion/ej2-navigations/styles/tailwind3.css";
import "@syncfusion/ej2-ribbon/styles/tailwind3.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;

tsx

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";
import "@syncfusion/ej2-base/styles/tailwind3.css";
import "@syncfusion/ej2-buttons/styles/tailwind3.css";
import "@syncfusion/ej2-popups/styles/tailwind3.css";
import "@syncfusion/ej2-splitbuttons/styles/tailwind3.css";
import "@syncfusion/ej2-inputs/styles/tailwind3.css";
import "@syncfusion/ej2-lists/styles/tailwind3.css";
import "@syncfusion/ej2-dropdowns/styles/tailwind3.css";
import "@syncfusion/ej2-navigations/styles/tailwind3.css";
import "@syncfusion/ej2-ribbon/styles/tailwind3.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;

Ribbon with File Menu

带文件菜单的Ribbon

tsx

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;

tsx

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;

Common Patterns

常见模式

Pattern 1: Multi-Tab Ribbon with Multiple Item Types

模式1：多选项卡Ribbon与多种项类型

Structure a professional ribbon with multiple tabs containing different item types (buttons, dropdowns, combos).

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

Pattern 2: Responsive Ribbon with Classic and Simplified Layouts

模式2：支持经典与简化布局的响应式Ribbon

Create a ribbon that switches between Classic (multi-row) and Simplified (single-row) layouts based on screen size or user preference.

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

Pattern 3: Context-Aware Ribbon

模式3：上下文感知Ribbon

Show/hide contextual tabs dynamically when users select specific objects or content types.

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

Pattern 4: File Menu with Backstage View

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

Combine file menu with backstage for comprehensive document management and application settings.

将文件菜单与后台视图结合，实现全面的文档管理和应用设置。

Pattern 5: Gallery-Based Item Selection

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

Use galleries to provide visual selection of styles, templates, or formatting options.

使用图库提供样式、模板或格式选项的视觉选择功能。

Key Props and Features

核心属性与功能

RibbonComponent:

```
fileMenu
```
- Configure file menu visibility and items
```
backStageMenu
```
- Enable and configure backstage view
```
activeLayout
```
- Set layout mode (Classic, Simplified)
```
isMinimized
```
- Programmatically minimize/expand ribbon
```
hideLayoutSwitcher
```
- Hide the layout switcher button

RibbonTabDirective:

```
header
```
- Tab title text
```
cssClass
```
- Custom CSS classes for tab styling

RibbonGroupDirective:

```
header
```
- Group title
```
orientation
```
- Item alignment (Row, Column)
```
groupIconCss
```
- Custom icon for group overflow
```
showLauncherIcon
```
- Show launcher icon
```
enableGroupOverflow
```
- Dedicated overflow popup for group
```
isCollapsible
```
- Allow group to collapse on resize
```
priority
```
- Collapse/expand priority

RibbonItemDirective:

```
type
```
- Item type (Button, CheckBox, DropDown, SplitButton, ComboBox, ColorPicker, GroupButton, Gallery, Template)
```
allowedSizes
```
- Permitted item sizes (Large, Medium, Small)
```
activeSize
```
- Current display size of the item
```
cssClass
```
- Custom CSS classes for item styling
```
ribbonTooltipSettings
```
- Tooltip configuration with title and content
```
itemTemplate
```
- Custom template for item rendering
```
displayOptions
```
- Visibility in layouts (Auto, Classic, Simplified, Overflow)
```
disabled
```
- Enable/disable item

Settings objects:

buttonSettings

dropDownSettings

splitButtonSettings

, etc.

For complete examples and advanced scenarios, explore individual reference files above.

RibbonComponent：

```
fileMenu
```
- 配置文件菜单可见性与项
```
backStageMenu
```
- 启用并配置后台视图
```
activeLayout
```
- 设置布局模式（经典、简化）
```
isMinimized
```
- 以编程方式最小化/展开Ribbon
```
hideLayoutSwitcher
```
- 隐藏布局切换按钮

RibbonTabDirective：

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

RibbonGroupDirective：

```
header
```
- 组标题
```
orientation
```
- 项对齐方式（行、列）
```
groupIconCss
```
- 组溢出的自定义图标
```
showLauncherIcon
```
- 显示启动器图标
```
enableGroupOverflow
```
- 为组提供专用溢出弹窗
```
isCollapsible
```
- 允许组在调整尺寸时折叠
```
priority
```
- 折叠/展开优先级

RibbonItemDirective：

```
type
```
- 项类型（按钮、复选框、下拉菜单、拆分按钮、组合框、颜色选择器、组按钮、图库、模板）
```
allowedSizes
```
- 允许的项尺寸（大、中、小）
```
activeSize
```
- 项的当前显示尺寸
```
cssClass
```
- 用于项样式的自定义CSS类
```
ribbonTooltipSettings
```
- 工具提示配置（含标题与内容）
```
itemTemplate
```
- 用于自定义渲染的项模板
```
displayOptions
```
- 布局中的可见性（自动、经典、简化、溢出）
```
disabled
```
- 启用/禁用项

设置对象：

buttonSettings

、

dropDownSettings

、

splitButtonSettings

等

如需完整示例和高级场景，请查看上述各参考文档。