syncfusion-javascript-sidebar

用途

Syncfusion JavaScript Sidebar 是一个可展开与折叠的侧边导航组件，作为主内容旁边的侧边容器使用，适用于构建响应式导航菜单、可停靠面板以及移动端友好的布局。该组件基于 Syncfusion Essential JS 2，主要面向 TypeScript/JavaScript 应用。

主要能力

四种展开类型：Over、Push、Slide、Auto，用于控制侧边栏与主内容的交互方式。
停靠支持（Docking）：在停靠状态下为图标预留空间，同时保留完整侧边栏功能。
动画与手势：支持平滑过渡，以及触摸滑动和移动端手势。
响应式设计：可在桌面（Push）与移动（Over）模式之间自动调整行为。
自定义目标：可将侧边栏定位到任意 HTML 容器，支持隐式或显式 target 指定。
内容集成：支持列表视图、树视图以及自定义 HTML 内容。

target 属性行为

组件提供两种控制侧边栏影响元素的模式：

隐式定位（推荐，默认）：侧边栏自动作用于下一个同级元素，无需包装元素，代码简洁。
显式定位（进阶）：使用 [target]="'#selector'" 属性指定目标，目标容器内部需要一个包装元素以支持 CSS 变换；适用于需要排除某些元素（如页头、页脚）或需要精细控制的场景。

类型与位置

展开类型：Over、Push、Slide、Auto。
位置选项：Left 或 Right。
提供类型对比以及各类型适用场景说明，并支持类型切换和响应式行为。

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

方法：show()、hide()、toggle()。
状态事件：open、close、change，附带 EventArgs 属性。
生命周期事件：created、destroyed。
可通过 args.cancel 阻止默认行为，通过 args.isInteracted 检测用户交互。

自动关闭与响应式行为

mediaQuery 属性用于设置响应式断点。
支持点击文档时自动关闭。
支持关闭按钮实现。
区分移动端与桌面端视口处理。

停靠侧边栏

enableDock 与 dockSize 属性。
在停靠状态下仅显示图标。
通过 CSS 控制文本可见性。
提供停靠状态的使用场景说明。

动画与手势

animate 属性及时间配置。
支持滑动与触摸交互手势。
移动端交互模式。
动画性能优化。

内容集成

侧边栏结合列表视图内容。
侧边栏结合树视图内容。
多个侧边栏实例。
同一位置放置多个侧边栏。
自定义 HTML 内容模式。

样式与主题

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

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 与国际化的支持。

关键属性

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，初始打开状态。

快速开始（隐式定位，推荐）

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

let sidebar: Sidebar = new Sidebar({
    type: 'Push',
    width: '280px'
});
sidebar.appendTo('#sidebar');

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

HTML 结构：侧边栏会自动作用于下一个同级元素。

<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',
    width: '280px'
});
sidebar.appendTo('#sidebar');

常见模式

移动端响应式侧边栏：

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

停靠图标侧边栏：

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

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

适用场景

导航菜单：带可折叠菜单项的主应用导航。
可停靠面板：基于图标、点击或悬停时展开的导航。
移动端菜单：使用手势与 Auto 类型的触摸友好侧边栏。
多级导航：结合列表或树视图层级的侧边栏。
管理后台：带基于角色菜单项的可折叠侧边栏。
内容抽屉：用于筛选、设置或附加内容的侧边面板。

限制

关于收费、价格、平台支持范围、浏览器兼容性和性能上限等具体信息，资料中暂未提供。