syncfusion-react-sidebar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Sidebar

实现 Syncfusion React Sidebar

The Syncfusion React Sidebar is a responsive navigation component that enables flexible layout patterns for modern web applications. It supports multiple display modes (Over, Push, Slide, Auto), responsive breakpoints, touch gestures, keyboard navigation, and seamless integration with ListView and TreeView components.

Syncfusion React Sidebar 是一款响应式导航组件，可为现代 Web 应用提供灵活的布局模式。它支持多种展示模式（Over、Push、Slide、Auto）、响应式断点、触摸手势、键盘导航，并且可与 ListView 和 TreeView 组件无缝集成。

When to Use This Skill

何时使用本技能

Choose Sidebar when you need:

Responsive navigation - Drawer menus that adapt to desktop/mobile viewports
Multi-mode layouts - Over (float), Push (shift content), Slide (translate), or Auto (responsive) behaviors
Content organization - Nested menus, ListView/TreeView integration, or multi-panel layouts
User interaction patterns - Toggle buttons, backdrop overlays, auto-close on item click, or keyboard shortcuts
Accessibility - ARIA labels, keyboard navigation (Tab, Enter, Escape), and screen reader support
Customization - Themed styling, animation variations, RTL support, or custom context containers

当你需要以下能力时可选择 Sidebar：

响应式导航 - 可适配桌面/移动视口的抽屉菜单
多模式布局 - Over（浮动）、Push（内容位移）、Slide（平移）或 Auto（响应式）行为
内容组织 - 嵌套菜单、ListView/TreeView 集成或多面板布局
用户交互模式 - 切换按钮、背景遮罩、点击选项自动关闭或键盘快捷键
无障碍访问 - ARIA 标签、键盘导航（Tab、Enter、Escape）和屏幕阅读器支持
自定义能力 - 主题样式、动画变体、RTL 支持或自定义上下文容器

Navigation Guide

使用指南

Getting Started

入门

📄 Read: references/getting-started.md

Installation and package setup
Basic sidebar rendering
CSS imports and theme configuration
Initial state management
First working example

📄 阅读： references/getting-started.md

安装与包配置
基础侧边栏渲染
CSS 导入与主题配置
初始状态管理
第一个可运行示例

API Reference: Properties

API 参考：属性

📄 Read: references/properties-reference.md

All 18 properties with types, defaults, and examples
Display properties (type, position, width, animate, showBackdrop, zIndex)
Behavior properties (closeOnDocumentClick, enableGestures, enableRtl, mediaQuery)
State properties (isOpen, enableDock, dockSize, enablePersistence)
Container property (target)

📄 阅读： references/properties-reference.md

全部 18 个属性的类型、默认值与示例
展示属性（type、position、width、animate、showBackdrop、zIndex）
行为属性（closeOnDocumentClick、enableGestures、enableRtl、mediaQuery）
状态属性（isOpen、enableDock、dockSize、enablePersistence）
容器属性（target）

API Reference: Methods

API 参考：方法

📄 Read: references/methods-reference.md

```
show(e?: Event)
```
- Display sidebar with optional event parameter
```
hide(e?: Event)
```
- Hide sidebar with optional event parameter
```
toggle()
```
- Toggle open/closed state
```
destroy()
```
- Remove sidebar from DOM
Complete examples for each method

📄 阅读： references/methods-reference.md

```
show(e?: Event)
```
- 展示侧边栏，支持传入可选事件参数
```
hide(e?: Event)
```
- 隐藏侧边栏，支持传入可选事件参数
```
toggle()
```
- 切换开/关状态
```
destroy()
```
- 从 DOM 中移除侧边栏
每个方法的完整示例

API Reference: Events

API 参考：事件

📄 Read: references/events-reference.md

```
change
```
- State change notification (user or programmatic)
```
open
```
- Before sidebar opens (preventable)
```
close
```
- Before sidebar closes (preventable)
```
created
```
- After sidebar is initialized
```
destroyed
```
- When sidebar is removed
Event handling examples and patterns

📄 阅读： references/events-reference.md

```
change
```
- 状态变更通知（用户触发或程序触发）
```
open
```
- 侧边栏打开前触发（可阻止）
```
close
```
- 侧边栏关闭前触发（可阻止）
```
created
```
- 侧边栏初始化完成后触发
```
destroyed
```
- 侧边栏被移除时触发
事件处理示例与模式

API Reference: Event Arguments

API 参考：事件参数

📄 Read: references/event-arguments-reference.md

```
ChangeEventArgs
```
interface - element, name, cancel, isInteracted
```
EventArgs
```
interface - cancel, element, event, isInteracted, model
```
SidebarModel
```
object - Complete configuration snapshot
Type definitions and usage examples

📄 阅读： references/event-arguments-reference.md

```
ChangeEventArgs
```
接口 - element、name、cancel、isInteracted
```
EventArgs
```
接口 - cancel、element、event、isInteracted、model
```
SidebarModel
```
对象 - 完整配置快照
类型定义与使用示例

Sidebar Positioning & Behavior

侧边栏定位与行为

📄 Read: references/sidebar-positioning.md

Sidebar types: Over, Push, Slide, Auto
Position: Left or Right
Width and dock size configuration
Multiple sidebars side-by-side
Media query responsive behavior

📄 阅读： references/sidebar-positioning.md

侧边栏类型：Over、Push、Slide、Auto
位置：左侧或右侧
宽度与停靠尺寸配置
多个侧边栏并排展示
媒体查询响应式行为

Opening & Closing Sidebar

侧边栏开启与关闭

📄 Read: references/opening-closing.md

Toggle functionality
Programmatic show/hide methods
Auto-close on document click
Auto-close on escape key
Animation transitions
Event handling for state changes

📄 阅读： references/opening-closing.md

切换功能
程序化 show/hide 方法
点击文档区域自动关闭
按下 Escape 键自动关闭
动画过渡效果
状态变更的事件处理

Content Integration

内容集成

📄 Read: references/content-integration.md

ListView integration with sidebar
TreeView integration for hierarchical navigation
Custom HTML content and structures
Dynamic data binding patterns
Menu-like navigation structures

📄 阅读： references/content-integration.md

ListView 与侧边栏集成
用于层级导航的 TreeView 集成
自定义 HTML 内容与结构
动态数据绑定模式
类菜单导航结构

Styling & Customization

样式与自定义

📄 Read: references/styling-customization.md

CSS class customization
Theme styles (default, material, bootstrap)
Animation variations and timing
Responsive breakpoint patterns
RTL (Right-to-Left) support
Custom animations

📄 阅读： references/styling-customization.md

CSS 类自定义
主题样式（默认、material、bootstrap）
动画变体与时长
响应式断点模式
RTL（从右到左）支持
自定义动画

Accessibility & Best Practices

无障碍访问与最佳实践

📄 Read: references/accessibility.md

WCAG compliance guidelines
Keyboard navigation (Tab, Enter, Escape)
ARIA attributes for screen readers
Focus management
Backdrop overlay interaction patterns

📄 阅读： references/accessibility.md

WCAG 合规指南
键盘导航（Tab、Enter、Escape）
面向屏幕阅读器的 ARIA 属性
焦点管理
背景遮罩交互模式

Quick Start

快速开始

jsx

import React, { useState } from 'react';
import { SidebarComponent } from '@syncfusion/ej2-react-navigations';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';

function App() {
  const [isOpen, setIsOpen] = useState(false);
  
  const handleToggle = () => {
    setIsOpen(!isOpen);
  };

  return (
    <div className="container">
      {/* Toggle Button */}
      <ButtonComponent 
        cssClass="e-primary" 
        onClick={handleToggle}
      >
        Toggle Sidebar
      </ButtonComponent>

      {/* Sidebar Component */}
      <SidebarComponent
        id="sidebar"
        width="250px"
        type="Over"
        isOpen={isOpen}
        change={() => setIsOpen(!isOpen)}
        showBackdrop={true}
        closeOnDocumentClick={true}
      >
        <div className="sidebar-content">
          <h3>Navigation Menu</h3>
          <ul>
            <li><a href="#home">Home</a></li>
            <li><a href="#about">About</a></li>
            <li><a href="#services">Services</a></li>
            <li><a href="#contact">Contact</a></li>
          </ul>
        </div>
      </SidebarComponent>

      {/* Main Content */}
      <div className="main-content">
        <h1>Main Content Area</h1>
        <p>Content shifts when type is "Push"</p>
      </div>
    </div>
  );
}

export default App;

jsx

import React, { useState } from 'react';
import { SidebarComponent } from '@syncfusion/ej2-react-navigations';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';

function App() {
  const [isOpen, setIsOpen] = useState(false);
  
  const handleToggle = () => {
    setIsOpen(!isOpen);
  };

  return (
    <div className="container">
      {/* Toggle Button */}
      <ButtonComponent 
        cssClass="e-primary" 
        onClick={handleToggle}
      >
        Toggle Sidebar
      </ButtonComponent>

      {/* Sidebar Component */}
      <SidebarComponent
        id="sidebar"
        width="250px"
        type="Over"
        isOpen={isOpen}
        change={() => setIsOpen(!isOpen)}
        showBackdrop={true}
        closeOnDocumentClick={true}
      >
        <div className="sidebar-content">
          <h3>Navigation Menu</h3>
          <ul>
            <li><a href="#home">Home</a></li>
            <li><a href="#about">About</a></li>
            <li><a href="#services">Services</a></li>
            <li><a href="#contact">Contact</a></li>
          </ul>
        </div>
      </SidebarComponent>

      {/* Main Content */}
      <div className="main-content">
        <h1>Main Content Area</h1>
        <p>Content shifts when type is "Push"</p>
      </div>
    </div>
  );
}

export default App;

Common Patterns

常用模式

Pattern 1: Responsive Auto Sidebar

模式 1：响应式自动侧边栏

Automatically switches between Over (mobile) and Push (desktop) modes based on viewport.

jsx

<SidebarComponent
  type="Auto"
  width="250px"
  isOpen={true}
  showBackdrop={true}
/>

根据视口自动在 Over（移动端）和 Push（桌面端）模式之间切换。

jsx

<SidebarComponent
  type="Auto"
  width="250px"
  isOpen={true}
  showBackdrop={true}
/>

Pattern 2: Mobile Drawer Menu

模式 2：移动端抽屉菜单

Floating sidebar that closes on backdrop click or escape key.

jsx

<SidebarComponent
  type="Over"
  width="280px"
  showBackdrop={true}
  closeOnDocumentClick={true}
  position="Left"
/>

浮动侧边栏，点击背景或按下 Escape 键可关闭。

jsx

<SidebarComponent
  type="Over"
  width="280px"
  showBackdrop={true}
  closeOnDocumentClick={true}
  position="Left"
/>

Pattern 3: Docked Navigation Panel

模式 3：停靠式导航面板

Persistent sidebar with fixed width that shows as icon bar when docked.

jsx

<SidebarComponent
  enableDock={true}
  dockSize="50px"
  width="250px"
  type="Push"
/>

固定宽度的持久化侧边栏，停靠时显示为图标栏。

jsx

<SidebarComponent
  enableDock={true}
  dockSize="50px"
  width="250px"
  type="Push"
/>

Pattern 4: RTL Navigation (Arabic/Hebrew)

模式 4：RTL 导航（阿拉伯语/希伯来语）

Right-aligned sidebar for right-to-left languages.

jsx

<SidebarComponent
  position="Right"
  enableRtl={true}
  type="Over"
/>

面向从右到左语言的右对齐侧边栏。

jsx

<SidebarComponent
  position="Right"
  enableRtl={true}
  type="Over"
/>

Key Properties Overview

核心属性概览

Property	Type	Default	Purpose
type	`SidebarType`	`'Auto'`	Display mode: Over, Push, Slide, Auto
isOpen	`boolean`	`false`	Controls sidebar open/closed state
position	`SidebarPosition`	`'Left'`	Sidebar placement: Left or Right
width	`string \| number`	`'auto'`	Sidebar width (pixels or percentage)
target	`HTMLElement \| string`	`null`	Container to render sidebar inside
showBackdrop	`boolean`	`false`	Show overlay when open
closeOnDocumentClick	`boolean`	`false`	Close on content area click
animate	`boolean`	`true`	Enable open/close animations
enableDock	`boolean`	`false`	Enable dock/minimize mode
dockSize	`string \| number`	`'auto'`	Width when docked
enableGestures	`boolean`	`true`	Touch swipe gestures
enableRtl	`boolean`	`false`	Right-to-left layout

属性	类型	默认值	用途
type	`SidebarType`	`'Auto'`	展示模式：Over、Push、Slide、Auto
isOpen	`boolean`	`false`	控制侧边栏的开/关状态
position	`SidebarPosition`	`'Left'`	侧边栏位置：左侧或右侧
width	`string \| number`	`'auto'`	侧边栏宽度（像素或百分比）
target	`HTMLElement \| string`	`null`	渲染侧边栏的容器
showBackdrop	`boolean`	`false`	开启时展示遮罩层
closeOnDocumentClick	`boolean`	`false`	点击内容区域时关闭
animate	`boolean`	`true`	开启开/关动画
enableDock	`boolean`	`false`	开启停靠/最小化模式
dockSize	`string \| number`	`'auto'`	停靠时的宽度
enableGestures	`boolean`	`true`	支持触摸滑动手势
enableRtl	`boolean`	`false`	从右到左布局

Common Use Cases

常见使用场景

Admin Dashboard Navigation - Top header with collapsible sidebar menu
Mobile App Navigation - Hamburger menu with drawer sidebar
E-commerce Product Filter - Left sidebar with expandable categories
Documentation Sites - Persistent table of contents sidebar
Settings Panels - Floating right sidebar for preferences
Multi-panel Layouts - Multiple sidebars on different sides

管理后台导航 - 顶部 header 搭配可折叠侧边栏菜单
移动应用导航 - 汉堡菜单搭配抽屉侧边栏
电商产品筛选 - 左侧侧边栏搭配可展开分类
文档站点 - 持久化目录侧边栏
设置面板 - 右侧浮动侧边栏用于偏好设置
多面板布局 - 不同位置展示多个侧边栏