Back to Details

syncfusion-aspnetcore-sidebar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion ASP.NET Core Sidebar

实现Syncfusion ASP.NET Core Sidebar组件

The Sidebar component is an expandable or collapsible navigation container that acts as a side panel to display primary or secondary content alongside the main content area. It provides flexible positioning, multiple expansion types, and responsive behavior ideal for modern web applications.
Sidebar组件是一个可展开或折叠的导航容器，作为侧边面板，在主内容区域旁显示主要或次要内容。它提供灵活的定位方式、多种展开类型，以及适合现代Web应用的响应式行为。

When to Use This Skill

何时使用该技能

Use this skill when you need to:
  • Create responsive navigation menus that collapse on mobile and expand on desktop
  • Implement collapsible sidebars with smooth animations and transitions
  • Build docked sidebar panels that reserve persistent space with icon-only views
  • Handle sidebar state management with open/close methods and event callbacks
  • Customize sidebar behavior with media queries, gestures, and backdrop overlays
  • Integrate with ASP.NET Core applications using TagHelper syntax and server-side binding
在以下场景中使用该技能：
  • 创建响应式导航菜单：在移动端折叠，在桌面端展开
  • 实现带平滑动画过渡的可折叠侧边栏
  • 构建停靠式侧边栏面板：保留持久空间，仅显示图标视图
  • 处理侧边栏状态管理：使用打开/关闭方法和事件回调
  • 自定义侧边栏行为：通过媒体查询、手势和背景遮罩
  • 与ASP.NET Core应用集成：使用TagHelper语法和服务器端绑定

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installation and NuGet package setup
  • ASP.NET Core project creation with Razor pages
  • TagHelper registration in _ViewImports.cshtml
  • Adding CSS/script resources via CDN or local
  • First working sidebar implementation
  • Script manager registration
📄 阅读： references/getting-started.md
  • 安装与NuGet包设置
  • 使用Razor页面创建ASP.NET Core项目
  • 在_ViewImports.cshtml中注册TagHelper
  • 通过CDN或本地添加CSS/脚本资源
  • 首个可运行的侧边栏实现
  • 注册脚本管理器

Understanding Sidebar Types

了解侧边栏类型

📄 Read: references/sidebar-types.md
  • Sidebar type enumeration (Over, Push, Slide, Auto)
  • Over type: floating sidebar above content
  • Push type: sidebar pushes main content aside
  • Slide type: sidebar slides without resizing content
  • Auto type: responsive type selection by screen resolution
  • Changing types at runtime with dataBind()
  • Type selection best practices
📄 阅读： references/sidebar-types.md
  • 侧边栏类型枚举（Over、Push、Slide、Auto）
  • Over类型：悬浮在内容上方的侧边栏
  • Push类型：侧边栏将主内容推开
  • Slide类型：侧边栏滑动而不调整内容大小
  • Auto类型：根据屏幕分辨率自动选择响应式类型
  • 使用dataBind()在运行时更改类型
  • 类型选择最佳实践

Managing Sidebar State

管理侧边栏状态

📄 Read: references/managing-state.md
  • isOpen property for initial state
  • show() method to open the sidebar programmatically
  • hide() method to close the sidebar
  • toggle() method for open/close switching
  • Controlling sidebar from button clicks
  • State initialization and persistence
  • Toggle patterns with UI buttons
📄 阅读： references/managing-state.md
  • isOpen属性：设置初始状态
  • show()方法：以编程方式打开侧边栏
  • hide()方法：关闭侧边栏
  • toggle()方法：切换打开/关闭状态
  • 通过按钮点击控制侧边栏
  • 状态初始化与持久化
  • 结合UI按钮的切换模式

Positioning and Sizing

定位与尺寸设置

📄 Read: references/positioning-and-sizing.md
  • position property (Left or Right placement)
  • width property for custom sidebar dimensions
  • target property for custom context targeting
  • Placing sidebar inside specific containers
  • Responsive sizing strategies
  • Width in pixels vs auto-sizing
  • Multiple sidebars in different positions
📄 阅读： references/positioning-and-sizing.md
  • position属性（左侧或右侧放置）
  • width属性：自定义侧边栏尺寸
  • target属性：自定义上下文目标
  • 将侧边栏放置在特定容器内
  • 响应式尺寸策略
  • 像素宽度与自动尺寸对比
  • 不同位置的多个侧边栏

Advanced Features

高级功能

📄 Read: references/advanced-features.md
  • enableDock property for docked state mode
  • dockSize configuration for reserved space
  • closeOnDocumentClick for dismiss-on-click behavior
  • showBackdrop overlay when sidebar is open
  • enableGestures for touch swipe control
  • mediaQuery for responsive breakpoint control
  • enablePersistence for state preservation across page reloads
📄 阅读： references/advanced-features.md
  • enableDock属性：启用停靠状态模式
  • dockSize配置：预留空间大小
  • closeOnDocumentClick：点击外部关闭的行为
  • showBackdrop：侧边栏打开时显示背景遮罩
  • enableGestures：启用触摸滑动控制
  • mediaQuery：响应式断点控制
  • enablePersistence：跨页面重载保留状态

Events and Callbacks

事件与回调

📄 Read: references/events-and-callbacks.md
  • change event: fires on expand/collapse state changes
  • open event: fires when sidebar opens
  • close event: fires when sidebar closes
  • created event: fires on component initialization
  • destroyed event: fires on component destruction
  • ChangeEventArgs structure with event details
  • EventArgs properties for event handling
  • Binding events with TagHelper syntax
📄 阅读： references/events-and-callbacks.md
  • change事件：展开/折叠状态变化时触发
  • open事件：侧边栏打开时触发
  • close事件：侧边栏关闭时触发
  • created事件：组件初始化时触发
  • destroyed事件：组件销毁时触发
  • ChangeEventArgs结构：包含事件详情
  • EventArgs属性：用于事件处理
  • 使用TagHelper语法绑定事件

Internationalization and RTL

国际化与RTL布局

📄 Read: references/internationalization.md
  • enableRtl property for right-to-left layouts
  • RTL sidebar positioning (right-aligned by default)
  • Mirror positioning and alignment
  • RTL animation and positioning behavior
  • Multi-language sidebar content
  • Combining RTL with positioning properties
📄 阅读： references/internationalization.md
  • enableRtl属性：支持从右到左布局
  • RTL侧边栏定位（默认右对齐）
  • 镜像定位与对齐
  • RTL动画与定位行为
  • 多语言侧边栏内容
  • 结合RTL与定位属性

Styling and Appearance

样式与外观

📄 Read: references/styling-and-appearance.md
  • animate property to enable/disable transitions
  • zIndex property for layering control with overlays
  • CSS class customization and theming
  • Backdrop styling and opacity
  • Animation duration and easing configuration
  • Theme integration
  • Custom styling best practices
📄 阅读： references/styling-and-appearance.md
  • animate属性：启用/禁用过渡动画
  • zIndex属性：控制遮罩的层级
  • CSS类自定义与主题设置
  • 背景遮罩样式与透明度
  • 动画时长与缓动配置
  • 主题集成
  • 自定义样式最佳实践

Complete API Reference

完整API参考

📄 Read: references/api-reference.md
  • All 15 properties with types and defaults
  • All 11 methods with signatures and descriptions
  • All 5 events with their argument types
  • Type enumerations (SidebarType, SidebarPosition)
  • Event argument structures (ChangeEventArgs, EventArgs)
  • Cross-references to feature documentation
  • Usage examples for each API
📄 阅读： references/api-reference.md
  • 所有15个属性及其类型与默认值
  • 所有11个方法及其签名与描述
  • 所有5个事件及其参数类型
  • 类型枚举（SidebarType、SidebarPosition）
  • 事件参数结构（ChangeEventArgs、EventArgs）
  • 功能文档的交叉引用
  • 每个API的使用示例

Quick Start Example

快速入门示例

Here's a minimal Sidebar implementation with a toggle button:
cshtml
<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>
以下是带切换按钮的最小化Sidebar实现：
cshtml
<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>

Common Patterns

常见模式

Pattern 1: Mobile-Responsive Navigation

模式1：移动端响应式导航

Use 
type="Auto"
to automatically switch between Over (mobile) and Push (desktop) based on screen resolution:
cshtml
<ejs-sidebar id="navbar" type="Auto" isOpen="false">
    <!-- Navigation items -->
</ejs-sidebar>
使用
type="Auto"
，根据屏幕分辨率自动在Over（移动端）和Push（桌面端）之间切换：
cshtml
<ejs-sidebar id="navbar" type="Auto" isOpen="false">
    <!-- Navigation items -->
</ejs-sidebar>

Pattern 2: Docked Sidebar with Icons

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

Enable docking with reserved space for icon-only view:
cshtml
<ejs-sidebar id="dockedbar" 
             enableDock="true" 
             dockSize="60px" 
             type="Push">
    <!-- Icon items -->
</ejs-sidebar>
启用停靠模式，为仅图标视图预留空间：
cshtml
<ejs-sidebar id="dockedbar" 
             enableDock="true" 
             dockSize="60px" 
             type="Push">
    <!-- Icon items -->
</ejs-sidebar>

Pattern 3: Backdrop with Overlay

模式3：带遮罩层的侧边栏

Show content overlay when sidebar opens:
cshtml
<ejs-sidebar id="overlaybar" 
             type="Over" 
             showBackdrop="true" 
             closeOnDocumentClick="true">
    <!-- Content -->
</ejs-sidebar>
侧边栏打开时显示内容遮罩：
cshtml
<ejs-sidebar id="overlaybar" 
             type="Over" 
             showBackdrop="true" 
             closeOnDocumentClick="true">
    <!-- Content -->
</ejs-sidebar>

Pattern 4: Right-Positioned Sidebar

模式4：右侧定位侧边栏

Place sidebar on the right side:
cshtml
<ejs-sidebar id="rightbar" position="Right" type="Push">
    <!-- Right-side navigation -->
</ejs-sidebar>
将侧边栏放置在右侧：
cshtml
<ejs-sidebar id="rightbar" position="Right" type="Push">
    <!-- Right-side navigation -->
</ejs-sidebar>

Pattern 5: Custom Width Sidebar

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

Set specific width in pixels:
cshtml
<ejs-sidebar id="custombar" type="Push" width="320px">
    <!-- Content with 320px width -->
</ejs-sidebar>
设置特定像素宽度：
cshtml
<ejs-sidebar id="custombar" type="Push" width="320px">
    <!-- Content with 320px width -->
</ejs-sidebar>

Key Properties Overview

关键属性概述

PropertyTypePurpose
type
SidebarTypeControls how sidebar expands (Over/Push/Slide/Auto)
position
SidebarPositionSidebar placement (Left/Right)
isOpen
booleanInitial open/closed state
width
string/numberSidebar width ('auto', '300px', or number)
enableDock
booleanEnables docked state mode
dockSize
string/numberWidth when docked ('auto', '60px', or number)
animate
booleanEnable/disable expansion animations
enableGestures
booleanEnable touch swipe to expand/collapse
mediaQuery
stringCSS media query for responsive behavior
showBackdrop
booleanShow overlay when sidebar is open
closeOnDocumentClick
booleanClose sidebar when clicking outside
enableRtl
booleanRight-to-left layout support
zIndex
string/numberLayering for overlay mode (default: 1000)
target
HTMLElement/stringContainer for sidebar (custom context)
enablePersistence
booleanPreserve state across page reloads
属性类型用途
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跨页面重载保留状态

Common Use Cases

常见使用场景

  • Admin Dashboards: Multi-section dashboards with collapsible navigation
  • E-Commerce Sites: Filter sidebars that collapse on mobile
  • Documentation Sites: Table of contents sidebars
  • Application Menus: Docked icon-based navigation that expands on hover
  • Mobile Apps: Hamburger menus that slide from the side
  • Content Management: Expandable editor sidebars
  • Data Tables: Filtering and column selection sidebars
  • 管理后台仪表盘：带可折叠导航的多区域仪表盘
  • 电商网站：移动端可折叠的筛选侧边栏
  • 文档网站：目录侧边栏
  • 应用菜单：停靠式图标导航，悬停时展开
  • 移动应用：从侧边滑出的汉堡菜单
  • 内容管理系统：可展开的编辑器侧边栏
  • 数据表格：筛选和列选择侧边栏

Next Steps

下一步行动

  1. Start with Getting Started to install and configure
  2. Choose your Sidebar Type based on your layout needs
  3. Learn State Management to control open/close behavior
  4. Explore Advanced Features for docking and responsiveness
  5. Reference Complete API for all properties and methods
  1. 从入门指南开始，完成安装和配置
  2. 根据布局需求选择侧边栏类型
  3. 学习状态管理，控制打开/关闭行为
  4. 探索高级功能，了解停靠和响应式特性
  5. 参考完整API，获取所有属性和方法

Component Overview

组件概述

The Sidebar component is built on the Syncfusion EJ2 framework and provides:
  • Four expansion types with automatic responsive selection
  • Touch gesture support for mobile devices
  • State persistence across page reloads
  • Event system for open/close/change lifecycle
  • Customizable positioning and sizing
  • Backdrop overlay for modal-like behavior
  • RTL and internationalization support
  • Smooth animations and transitions
  • Full TagHelper integration with ASP.NET Core
For detailed implementation examples and advanced scenarios, refer to the reference guides above.
Sidebar组件基于Syncfusion EJ2框架构建，提供：
  • 四种展开类型，支持自动响应式选择
  • 移动端触摸手势支持
  • 跨页面重载的状态持久化
  • 打开/关闭/变更生命周期的事件系统
  • 可自定义的定位和尺寸
  • 类似模态框的背景遮罩
  • RTL和国际化支持
  • 流畅的动画和过渡效果
  • 与ASP.NET Core的完整TagHelper集成
如需详细的实现示例和高级场景，请参考上述参考指南。