syncfusion-react-sidebar

用途

Syncfusion React Sidebar 是一个响应式导航组件，用于为现代 Web 应用构建灵活的布局模式。它适合在需要响应式导航菜单、抽屉式布局或内容组织面板时使用。

主要能力

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

使用方式

安装与基础渲染

参考 references/getting-started.md，包含安装与包配置、基础侧边栏渲染、CSS 导入与主题配置、初始状态管理以及第一个可运行示例。

快速开始

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;

API 参考

属性（references/properties-reference.md）：共 18 个属性，含类型、默认值与示例。

显示属性：type、position、width、animate、showBackdrop、zIndex
行为属性：closeOnDocumentClick、enableGestures、enableRtl、mediaQuery
状态属性：isOpen、enableDock、dockSize、enablePersistence
容器属性：target

方法（references/methods-reference.md）：

show(e?: Event) - 显示侧边栏，可选事件参数
hide(e?: Event) - 隐藏侧边栏，可选事件参数
toggle() - 切换打开/关闭状态
destroy() - 从 DOM 中移除侧边栏

事件（references/events-reference.md）：

change - 状态变更通知（用户或程序触发）
open - 侧边栏打开前（可阻止）
close - 侧边栏关闭前（可阻止）
created - 侧边栏初始化后
destroyed - 侧边栏被移除时

事件参数（references/event-arguments-reference.md）：

ChangeEventArgs 接口 - element、name、cancel、isInteracted
EventArgs 接口 - cancel、element、event、isInteracted、model
SidebarModel 对象 - 完整配置快照

关键属性概览

属性	类型	默认值	用途
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	从右到左布局

常见模式

模式 1：响应式 Auto 侧边栏 根据视口自动在 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"
/>

专题参考文档

定位与行为（references/sidebar-positioning.md）：Sidebar 类型、Left/Right 位置、宽度与停靠尺寸配置、多侧边栏并排、媒体查询响应式行为。
打开与关闭（references/opening-closing.md）：切换功能、程序化 show/hide 方法、点击文档自动关闭、Escape 键自动关闭、动画过渡、状态变更事件处理。
内容集成（references/content-integration.md）：ListView 集成、TreeView 层级导航集成、自定义 HTML 内容与结构、动态数据绑定、菜单式导航结构。
样式与自定义（references/styling-customization.md）：CSS 类自定义、主题样式（default、material、bootstrap）、动画变体与时长、响应式断点模式、RTL 支持、自定义动画。
无障碍与最佳实践（references/accessibility.md）：WCAG 合规指南、键盘导航（Tab、Enter、Escape）、屏幕阅读器 ARIA 属性、焦点管理、背景遮罩交互模式。

适用场景

管理后台导航：顶部页头配合可折叠侧边栏菜单
移动应用导航：汉堡菜单配合抽屉式侧边栏
电商商品筛选：左侧可展开分类侧边栏
文档站点：常驻目录侧边栏
设置面板：右侧浮动偏好设置侧边栏
多面板布局：不同侧边的多个侧边栏

限制

资料未提供关于收费、价格、平台兼容性、性能指标或具体效果的信息，暂未提供。