syncfusion-javascript-sidebar

Syncfusion TypeScript Sidebar

Sidebar 是一种可展开和折叠的导航组件，可作为主内容旁边的侧边容器。它非常适合使用 Syncfusion Essential JS 2 在 TypeScript 应用中构建响应式导航菜单、可停靠面板和适配移动设备的布局。

主要功能

• 四种展开类型：Over、Push、Slide 和 Auto，灵活控制内容交互
• 停靠支持：为已停靠的图标保留空间，同时保留完整的侧边栏功能
• 动画和手势：流畅的过渡效果，并支持触摸滑动和移动设备手势
• 响应式设计：在桌面端（Push）和移动端（Over）模式之间自动调整行为
• 自定义目标：使用隐式或显式目标定位，将侧边栏放置在任意 HTML 容器中
• 内容集成：支持列表视图、树视图和自定义 HTML 内容

导航指南

根据任务阅读相应的参考文件：

入门

📄 阅读： references/getting-started.md（约 150 行）

• 软件包安装和依赖项
• 使用 webpack 设置项目
• HTML 结构和初始化
• CSS 导入和配置
• 运行你的第一个侧边栏

Target 属性行为（重要）

控制侧边栏影响哪个元素有两种不同模式：

隐式目标定位（推荐 — 默认）：

• 侧边栏会自动将**下一个同级 <div>**作为目标
• 无需包装元素
• 代码简单、整洁，适用于大多数应用

显式目标定位（高级）：

• 使用 [target]="'#selector'" 属性
• 为了应用 CSS 变换，目标容器内必须包含一个 <div> 包装元素
• 在需要排除元素（页眉、页脚）或进行精细控制时使用

📄 阅读： references/positioning-and-target.md（约 160 行）

• 目标选择器和 HTML 结构
• 隐式与显式目标定位模式
• 固定定位和布局注意事项
• 常见目标配置场景

侧边栏类型和位置

📄 阅读： references/sidebar-types-and-positions.md（约 180 行，含目录）

• 四种展开类型详解：Over、Push、Slide、Auto
• 位置选项：Left 或 Right
• 类型对比表及各类型的适用场景
• 类型切换和响应式行为

打开和关闭方法及生命周期事件

📄 阅读： references/open-and-close.md（约 250 行）

• show()、hide()、toggle() 方法
• 状态事件：open、close、change 及其 EventArgs 属性
• 生命周期事件：created、destroyed
• 以编程方式管理侧边栏状态
• 使用 args.cancel 阻止默认行为
• 使用 args.isInteracted 检测用户交互

自动关闭和响应式行为

📄 阅读： references/auto-close-responsive.md（约 140 行）

• 用于设置响应式断点的 mediaQuery 属性
• 文档点击时自动关闭的行为
• 关闭按钮的实现
• 移动端与桌面端视口的处理

停靠侧边栏

📄 阅读： references/docking-sidebar.md（约 170 行，含目录）

• enableDock 和 dockSize 属性
• 在停靠状态下仅显示图标
• 控制文本可见性的 CSS
• 停靠状态的使用场景

动画和手势

📄 阅读： references/animations-and-gestures.md（约 200 行，含目录）

• animate 属性和时间配置
• 手势支持：滑动和触摸交互
• 移动设备交互模式
• 动画性能优化

内容集成

📄 阅读： references/content-integration.md（约 180 行，含目录）

• 在侧边栏中使用列表视图内容
• 在侧边栏中使用树视图内容
• 多个侧边栏实例
• 在同一位置放置多个侧边栏
• 自定义 HTML 内容模式

样式与主题

📄 阅读： references/styling-and-theming.md（约 200 行，含目录）

• CSS 类和选择器（.e-sidebar、.e-open、.e-close、.e-dock）
• 按类型和位置自定义侧边栏
• 背景遮罩的样式和自定义
• 响应式设计和移动端样式

故障排除

📄 阅读： references/troubleshooting.md（约 120 行）

• 常见问题及解决方案
• Z-index 和堆叠上下文问题
• 性能优化技巧
• 手势冲突和手势无法正常工作
• 移动端响应式问题排查

API 方法和属性参考

📄 阅读： references/api-methods-properties.md（约 580 行，全面涵盖 API）

• 所有侧边栏属性及其默认值和类型：type、position、width、target、showBackdrop、animate、closeOnDocumentClick、enableGestures、enableDock、dockSize、mediaQuery、zIndex、isOpen、enableRtl、enablePersistence
• 所有方法及可运行示例：show()、hide()、toggle()、getRootElement()、destroy()、refresh()、dataBind()
• 事件监听器管理：addEventListener()、removeEventListener()
• 响应式配置示例
• 持久化和状态管理
• RTL 和国际化支持

快速入门示例

隐式指定目标（推荐）

import { Sidebar } from '@syncfusion/ej2-navigations';

// Create sidebar - automatically targets next sibling div
let sidebar: Sidebar = new Sidebar({
    type: 'Push',
    width: '280px'
});
sidebar.appendTo('#sidebar');

// Toggle on button click
document.querySelector('#toggle')?.addEventListener('click', () => {
    sidebar.toggle();
});

<aside id="sidebar">
    <div class="title">Navigation Menu</div>
    <ul>
        <li>Home</li>
        <li>About</li>
        <li>Contact</li>
    </ul>
</aside>


<div id="main-content">
    <button id="toggle">Toggle Sidebar</button>
    <div class="content">Main content here</div>
</div>

显式指定目标（带内部包装器）

let sidebar: Sidebar = new Sidebar({
    type: 'Push',
    target: '#content-area',  // Explicit target selector
    width: '280px'
});
sidebar.appendTo('#sidebar');

<aside id="sidebar">
    <div class="title">Navigation</div>
</aside>

<div id="content-area">              
    <div>                             
        <button id="toggle">Toggle</button>
        <div class="content">Main content</div>
    </div>
</div>

常见模式

模式 1：移动端响应式侧边栏

let sidebar: Sidebar = new Sidebar({
    type: 'Auto',  // Over on mobile, Push on desktop
    mediaQuery: window.matchMedia('(max-width: 768px)'),
    width: '280px'
});
sidebar.appendTo('#sidebar');

模式 2：停靠式图标侧边栏

let sidebar: Sidebar = new Sidebar({
    enableDock: true,
    dockSize: '72px',
    width: '220px'
});
sidebar.appendTo('#sidebar');

// CSS for docked state
// .e-dock.e-close span.e-text { display: none; }
// .e-dock.e-open span.e-text { display: inline-block; }

模式 3：带事件的切换

let sidebar: Sidebar = new Sidebar({
    open: (e) => console.log('Sidebar opened'),
    close: (e) => console.log('Sidebar closed'),
    showBackdrop: true
});
sidebar.appendTo('#sidebar');

// Programmatic control
document.querySelector('#open')?.addEventListener('click', () => sidebar.show());
document.querySelector('#close')?.addEventListener('click', () => sidebar.hide());
document.querySelector('#toggle')?.addEventListener('click', () => sidebar.toggle());

关键属性参考

属性	类型	默认值	用途
type	'Over' | 'Push' | 'Slide' | 'Auto'	'Auto'	展开行为
position	'Left' | 'Right'	'Left'	侧边栏位置
width	string	'100%'	侧边栏宽度
target	string	null	目标元素选择器（显式指定）
enableDock	boolean	false	启用停靠/折叠状态
dockSize	string	'52px'	停靠时的宽度
showBackdrop	boolean	false	显示背景遮罩
animate	boolean	true	启用动画
mediaQuery	MediaQueryList	null	响应式断点
isOpen	boolean	false	初始打开状态

常见用例

• 导航菜单：包含可折叠菜单项的应用主导航
• 可停靠面板：基于图标的导航，可通过悬停/点击展开
• 移动端菜单：使用手势和 Auto 类型的触控友好型侧边栏
• 多级导航：具有列表或树形视图层级结构的侧边栏
• 管理后台仪表板：包含基于角色的菜单项的可折叠侧边栏
• 内容抽屉：用于筛选条件、设置或其他内容的侧面板

---

后续步骤： 根据当前任务选择一个参考文件并阅读详细文档。如果是首次使用 Sidebar 组件，请从“入门”开始。