syncfusion-aspnetcore-sidebar

实现 Syncfusion ASP.NET Core Sidebar

Sidebar 组件是一个可展开或折叠的导航容器，可作为侧边面板，在主内容区域旁显示主要或次要内容。它支持灵活定位、多种展开类型和响应式行为，非常适合现代 Web 应用程序。

何时使用此技能

在以下情况下使用此技能：

• 创建响应式导航菜单，在移动设备上折叠，在桌面设备上展开
• 实现可折叠侧边栏，并添加流畅的动画和过渡效果
• 构建停靠式侧边栏面板，预留固定空间并提供仅显示图标的视图
• 管理侧边栏状态，通过打开/关闭方法和事件回调进行控制
• 自定义侧边栏行为，使用媒体查询、手势和背景遮罩
• 集成到 ASP.NET Core 应用程序中，使用 TagHelper 语法和服务器端绑定

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• 使用 Razor 页面创建 ASP.NET Core 项目
• 在 _ViewImports.cshtml 中注册 TagHelper
• 通过 CDN 或本地方式添加 CSS/脚本资源
• 首个可运行的侧边栏实现
• 注册脚本管理器

了解 Sidebar 类型

📄 阅读： references/sidebar-types.md

• Sidebar 类型枚举（Over、Push、Slide、Auto）
• Over 类型：悬浮在内容上方的侧边栏
• Push 类型：侧边栏将主内容推向一侧
• Slide 类型：侧边栏滑入，但不调整内容大小
• Auto 类型：根据屏幕分辨率选择响应式类型
• 使用 dataBind() 在运行时更改类型
• 类型选择最佳实践

管理 Sidebar 状态

📄 阅读： references/managing-state.md

• 用于设置初始状态的 isOpen 属性
• 以编程方式打开侧边栏的 show() 方法
• 关闭侧边栏的 hide() 方法
• 用于切换打开/关闭状态的 toggle() 方法
• 通过按钮点击控制侧边栏
• 状态初始化和持久化
• 使用 UI 按钮的切换模式

定位和尺寸

📄 阅读： references/positioning-and-sizing.md

• position 属性（放置在左侧或右侧）
• 用于自定义侧边栏尺寸的 width 属性
• 用于自定义上下文目标的 target 属性
• 将侧边栏放置在特定容器中
• 响应式尺寸策略
• 像素宽度与自动调整尺寸
• 在不同位置放置多个侧边栏

高级功能

📄 阅读： references/advanced-features.md

• 用于停靠状态模式的 enableDock 属性
• 用于预留空间的 dockSize 配置
• closeOnDocumentClick：点击时关闭
• 侧边栏打开时显示 showBackdrop 遮罩
• 使用 enableGestures 启用触摸滑动控制
• 使用 mediaQuery 控制响应式断点
• 使用 enablePersistence 在页面重新加载后保留状态

事件和回调

📄 阅读： references/events-and-callbacks.md

• change 事件：展开/折叠状态变化时触发
• open 事件：侧边栏打开时触发
• close 事件：侧边栏关闭时触发
• created 事件：组件初始化时触发
• destroyed 事件：组件销毁时触发
• 包含事件详情的 ChangeEventArgs 结构
• 用于事件处理的 EventArgs 属性
• 使用 TagHelper 语法绑定事件

国际化和 RTL

📄 阅读： references/internationalization.md

• 用于从右向左布局的 enableRtl 属性
• RTL 侧边栏定位（默认右对齐）
• 镜像定位和对齐
• RTL 动画和定位行为
• 多语言侧边栏内容
• 将 RTL 与定位属性结合使用

样式与外观

📄 阅读： references/styling-and-appearance.md

• 使用 animate 属性启用或禁用过渡效果
• 使用 zIndex 属性控制覆盖层的层级
• CSS 类自定义与主题设置
• 背景遮罩的样式与不透明度
• 动画时长与缓动配置
• 主题集成
• 自定义样式最佳实践

完整 API 参考

📄 阅读： references/api-reference.md

• 全部 15 个属性及其类型和默认值
• 全部 11 个方法及其签名和说明
• 全部 5 个事件及其参数类型
• 类型枚举（SidebarType、SidebarPosition）
• 事件参数结构（ChangeEventArgs、EventArgs）
• 功能文档的交叉引用
• 每个 API 的使用示例

快速入门示例

下面是一个带切换按钮的最简 Sidebar 实现：

<ejs-sidebar id="default-sidebar" type="Push" isOpen="false">
    <e-content-template>
        <div style="padding: 20px;">
            <h3>Sidebar Menu</h3>
            <p>Navigation items go here</p>
        </div>
    </e-content-template>
</ejs-sidebar>

<div style="padding: 20px;">
    <ejs-button id="toggleBtn" content="Toggle Sidebar" onclick="toggleSidebar()"></ejs-button>
    <h2>Main Content</h2>
    <p>Your page content appears here</p>
</div>

<script>
var sidebar;

document.addEventListener('DOMContentLoaded', function () {
    sidebar = document.getElementById('default-sidebar').ej2_instances[0];
});

function toggleSidebar() {
    sidebar.toggle();
}
</script>

常见模式

模式 1：适配移动设备的导航

使用 type="Auto"，根据屏幕分辨率自动在 Over（移动设备）和 Push（桌面设备）之间切换：

<ejs-sidebar id="navbar" type="Auto" isOpen="false">
    
</ejs-sidebar>

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

启用停靠功能，并为仅显示图标的视图预留空间：

<ejs-sidebar id="dockedbar" 
             enableDock="true" 
             dockSize="60px" 
             type="Push">
    
</ejs-sidebar>

模式 3：带覆盖层的背景遮罩

在侧边栏打开时显示内容覆盖层：

<ejs-sidebar id="overlaybar" 
             type="Over" 
             showBackdrop="true" 
             closeOnDocumentClick="true">
    
</ejs-sidebar>

模式 4：位于右侧的侧边栏

将侧边栏放在右侧：

<ejs-sidebar id="rightbar" position="Right" type="Push">
    
</ejs-sidebar>

模式 5：自定义宽度的侧边栏

设置具体的像素宽度：

<ejs-sidebar id="custombar" type="Push" width="320px">
    
</ejs-sidebar>

关键属性概览

属性	类型	用途
type	SidebarType	控制侧边栏的展开方式（Over/Push/Slide/Auto）
position	SidebarPosition	侧边栏位置（Left/Right）
isOpen	boolean	初始打开或关闭状态
width	string/number	侧边栏宽度（'auto'、'300px' 或数字）
enableDock	boolean	启用停靠状态模式
dockSize	string/number	停靠时的宽度（'auto'、'60px' 或数字）
animate	boolean	启用或禁用展开动画
enableGestures	boolean	启用触摸滑动以展开或收起
mediaQuery	string	用于响应式行为的 CSS 媒体查询
showBackdrop	boolean	侧边栏打开时显示覆盖层
closeOnDocumentClick	boolean	点击侧边栏外部时关闭侧边栏
enableRtl	boolean	支持从右向左的布局
zIndex	string/number	覆盖层模式的层级（默认值：1000）
target	HTMLElement/string	侧边栏的容器（自定义上下文）
enablePersistence	boolean	页面重新加载后保留状态

常见用例

• 管理后台：带可折叠导航的多分区仪表板
• 电子商务网站：可在移动设备上收起的筛选侧边栏
• 文档网站：目录侧边栏
• 应用菜单：悬停时展开的停靠式图标导航
• 移动应用：从侧边滑出的汉堡菜单
• 内容管理：可展开的编辑器侧边栏
• 数据表格：用于筛选和选择列的侧边栏

后续步骤

1. 从快速入门开始，安装并完成配置
2. 根据布局需求选择侧边栏类型
3. 学习状态管理，控制打开和关闭行为
4. 探索高级功能，了解停靠与响应式布局
5. 查阅完整 API，了解所有属性和方法

---

组件概览

Sidebar 组件基于 Syncfusion EJ2 框架构建，提供：

• 四种展开类型，并自动选择响应式模式
• 支持移动设备上的触摸手势
• 页面重新加载后仍可保留状态
• 用于打开、关闭和变更生命周期的事件系统
• 可自定义位置和尺寸
• 支持类似模态框行为的背景遮罩
• 支持 RTL 和国际化
• 流畅的动画和过渡效果
• 与 ASP.NET Core 的 TagHelper 完全集成

如需详细的实现示例和高级场景，请参阅上述参考指南。