syncfusion-react-sidebar

实现 Syncfusion React Sidebar

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

何时使用此技能

在以下情况下选择 Sidebar：

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

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 基本 Sidebar 渲染
• CSS 导入和主题配置
• 初始状态管理
• 首个可运行示例

API 参考：属性

📄 阅读： references/properties-reference.md

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

API 参考：方法

📄 阅读： references/methods-reference.md

• show(e?: Event) - 显示 Sidebar，可选传入事件参数
• hide(e?: Event) - 隐藏 Sidebar，可选传入事件参数
• toggle() - 切换打开/关闭状态
• destroy() - 从 DOM 中移除 Sidebar
• 每种方法的完整示例

API 参考：事件

📄 阅读： references/events-reference.md

• change - 状态变更通知（用户触发或以编程方式触发）
• open - Sidebar 打开前触发（可阻止）
• close - Sidebar 关闭前触发（可阻止）
• created - Sidebar 初始化后触发
• destroyed - Sidebar 移除时触发
• 事件处理示例和模式

API 参考：事件参数

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

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

Sidebar 定位与行为

📄 阅读： references/sidebar-positioning.md

• Sidebar 类型：Over、Push、Slide、Auto
• 位置：Left 或 Right
• 宽度和停靠尺寸配置
• 多个 Sidebar 并排显示
• 媒体查询响应式行为

打开和关闭 Sidebar

📄 阅读： references/opening-closing.md

• 切换功能
• 以编程方式调用 show/hide 方法
• 点击文档时自动关闭
• 按下 Escape 键时自动关闭
• 动画过渡
• 状态变更的事件处理

内容集成

📄 阅读： references/content-integration.md

• Sidebar 与 ListView 集成
• 使用 TreeView 实现分层导航
• 自定义 HTML 内容和结构
• 动态数据绑定模式
• 类似菜单的导航结构

样式与自定义

📄 阅读： references/styling-customization.md

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

无障碍访问与最佳实践

📄 阅读： references/accessibility.md

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

快速开始

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;

常见模式

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

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

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

模式 2：移动端抽屉菜单

点击背景遮罩或按 Escape 键即可关闭的浮动侧边栏。

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

模式 3：停靠式导航面板

固定宽度的常驻侧边栏，停靠时显示为图标栏。

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

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

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

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

主要属性概览

属性	类型	默认值	用途
type	SidebarType	'Auto'	显示模式：Over、Push、Slide、Auto
isOpen	boolean	false	控制侧边栏的打开/关闭状态
position	SidebarPosition	'Left'	侧边栏位置：Left 或 Right
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	启用从右到左布局

常见用例

• 管理后台导航 - 顶部标题栏搭配可折叠的侧边栏菜单
• 移动应用导航 - 汉堡菜单搭配抽屉式侧边栏
• 电商产品筛选 - 带可展开类别的左侧边栏
• 文档网站 - 常驻的目录侧边栏
• 设置面板 - 用于偏好设置的浮动右侧边栏
• 多面板布局 - 在不同侧边放置多个侧边栏

---