syncfusion-angular-sidebar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion Angular Sidebar Component

实现Syncfusion Angular Sidebar组件

The Sidebar is an expandable and collapsible navigation component that acts as a side container for primary or secondary content alongside main content. It supports flexible show/hide behavior, multiple positioning modes (left, right, top, bottom), various expand types (Push, Slide, Over, Auto), docking for compact states, touch gestures, animations, responsive behavior, and rich content including TreeView and ListView.
Sidebar是一个可展开和折叠的导航组件,可作为主内容旁的侧边容器,用于承载主要或次要内容。它支持灵活的显示/隐藏行为、多种定位模式(左侧、右侧、顶部、底部)、各类展开类型(Push、Slide、Over、Auto)、紧凑状态下的停靠功能、触摸手势、动画效果、响应式行为,以及包含TreeView和ListView的丰富内容。

When to Use This Skill

何时使用本内容

  • Implementing collapsible navigation menus or sidebars
  • Creating responsive navigation that adapts to screen size
  • Building expandable panels with icon-only docked states
  • Adding gesture-based sidebar toggle on touch devices
  • Positioning sidebars in various directions (left, right, top, bottom)
  • Implementing backdrop overlays to focus on sidebar content
  • Creating multi-level navigation with TreeView or ListView
  • Managing sidebar visibility with auto-close behavior
  • Building toggle buttons with show(), hide(), toggle() methods
  • Applying animations and RTL support to sidebars
  • 实现可折叠的导航菜单或侧边栏
  • 创建可适配屏幕尺寸的响应式导航
  • 构建仅显示图标的停靠状态展开面板
  • 在触控设备上添加基于手势的侧边栏切换功能
  • 在不同方向(左、右、上、下)定位侧边栏
  • 实现背景遮罩以聚焦侧边栏内容
  • 创建基于TreeView或ListView的多级导航
  • 通过自动关闭行为管理侧边栏可见性
  • 使用show()、hide()、toggle()方法构建切换按钮
  • 为侧边栏应用动画和RTL支持

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Angular CLI setup and project initialization (Recommended)
  • Installing Syncfusion packages (Ivy and ngcc versions)
  • Importing modules and CSS styles
  • Creating basic sidebar component
  • ViewChild setup and initialization
📄 阅读: references/getting-started.md
  • Angular CLI设置与项目初始化(推荐)
  • 安装Syncfusion包(Ivy和ngcc版本)
  • 导入模块和CSS样式
  • 创建基础侧边栏组件
  • ViewChild设置与初始化

SystemJS Setup (Alternative)

SystemJS设置(替代方案)

📄 Read: references/systemjs-setup.md
  • SystemJS configuration and installation
  • systemjs.config.js setup with Syncfusion mappings
  • UMD bundle configuration
  • Creating Sidebar with SystemJS
  • Development server and running the application
  • SystemJS vs Angular CLI comparison
📄 阅读: references/systemjs-setup.md
  • SystemJS配置与安装
  • 配置带有Syncfusion映射的systemjs.config.js
  • UMD包配置
  • 使用SystemJS创建Sidebar
  • 开发服务器与运行应用
  • SystemJS与Angular CLI对比

Sidebar Positioning and Behavior

侧边栏定位与行为

📄 Read: references/sidebar-positioning.md
  • Sidebar types: Push, Slide, Over, Auto
  • Positioning: Left, Right, Top, Bottom
  • Fixed positioning for static sidebars
  • Docking with enableDock and dockSize properties
  • Multiple sidebars on same page
  • dataBind() for dynamic property updates
📄 阅读: references/sidebar-positioning.md
  • 侧边栏类型:Push、Slide、Over、Auto
  • 定位:左侧、右侧、顶部、底部
  • 静态侧边栏的固定定位
  • 使用enableDock和dockSize属性实现停靠
  • 同一页面中的多个侧边栏
  • 使用dataBind()更新动态属性

Sidebar Interactions and Control

侧边栏交互与控制

📄 Read: references/sidebar-interactions.md
  • Control methods: show(), hide(), toggle()
  • Auto-close with mediaQuery for responsive behavior
  • closeOnDocumentClick for external click handling
  • Backdrop overlay with showBackdrop
  • Touch gesture support with enableGestures
  • Open and close event handling
📄 阅读: references/sidebar-interactions.md
  • 控制方法:show()、hide()、toggle()
  • 使用mediaQuery实现响应式自动关闭
  • 使用closeOnDocumentClick处理外部点击
  • 使用showBackdrop添加背景遮罩
  • 使用enableGestures支持触摸手势
  • 打开和关闭事件处理

Sidebar Content and Components

侧边栏内容与组件

📄 Read: references/sidebar-content.md
  • ListView integration for list-based content
  • TreeView integration for hierarchical menus
  • Custom HTML content and menu items
  • Target element configuration
  • Content structure and layout patterns
📄 阅读: references/sidebar-content.md
  • 集成ListView实现列表类内容
  • 集成TreeView实现层级菜单
  • 自定义HTML内容和菜单项
  • 目标元素配置
  • 内容结构与布局模式

Animations and Styling

动画与样式

📄 Read: references/animations-and-styles.md
  • Animation control with animate property
  • Animation types and variations
  • CSS theming with Material3 and other themes
  • RTL (right-to-left) support with enableRtl
  • Responsive design patterns
  • CRG (Custom Resource Generator) usage
📄 阅读: references/animations-and-styles.md
  • 使用animate属性控制动画
  • 动画类型与变体
  • 使用Material3及其他主题进行CSS主题定制
  • 使用enableRtl支持RTL(从右到左)布局
  • 响应式设计模式
  • CRG(自定义资源生成器)的使用

Advanced Features and Patterns

高级功能与模式

📄 Read: references/advanced-features.md
  • Persistence with enablePersistence
  • RTL implementation details
  • Accessibility features
  • Hiding sidebars with routing
  • Performance optimization
  • Edge cases and troubleshooting
📄 阅读: references/advanced-features.md
  • 使用enablePersistence实现状态持久化
  • RTL实现细节
  • 无障碍功能
  • 结合路由隐藏侧边栏
  • 性能优化
  • 边缘案例与故障排除

Quick Start Example

快速入门示例

typescript
import { SidebarModule } from '@syncfusion/ej2-angular-navigations';
import { Component, ViewChild } from '@angular/core';
import { SidebarComponent } from '@syncfusion/ej2-angular-navigations';

@Component({
  imports: [SidebarModule],
  standalone: true,
  selector: 'app-root',
  template: `<ejs-sidebar #sidebar id="default-sidebar">
              <div class="title">Sidebar Content</div>
            </ejs-sidebar>
            <div>
              <div class="title">Main Content</div>
              <button (click)="toggleSidebar()">Toggle Sidebar</button>
            </div>`,
  styles: [`
    .title { padding: 20px; font-weight: bold; }
  `]
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  toggleSidebar() {
    this.sidebar?.toggle();
  }
}
typescript
import { SidebarModule } from '@syncfusion/ej2-angular-navigations';
import { Component, ViewChild } from '@angular/core';
import { SidebarComponent } from '@syncfusion/ej2-angular-navigations';

@Component({
  imports: [SidebarModule],
  standalone: true,
  selector: 'app-root',
  template: `<ejs-sidebar #sidebar id="default-sidebar">
              <div class="title">Sidebar Content</div>
            </ejs-sidebar>
            <div>
              <div class="title">Main Content</div>
              <button (click)="toggleSidebar()">Toggle Sidebar</button>
            </div>`,
  styles: [`
    .title { padding: 20px; font-weight: bold; }
  `]
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  toggleSidebar() {
    this.sidebar?.toggle();
  }
}

Target Property Behavior

Target属性行为

The sidebar's
target
property controls which element is affected when the sidebar expands/collapses. There are two distinct modes:
侧边栏的
target
属性用于控制侧边栏展开/折叠时影响的元素。有两种不同模式

Implicit Targeting (Recommended - Default Behavior)

隐式目标(推荐 - 默认行为)

No
target
property is specified.
The sidebar automatically targets the next sibling
<div>
element:
typescript
<ejs-sidebar id="sidebar" type="Push"></ejs-sidebar>
<div>  <!-- Automatically becomes target - no wrapper needed -->
  <div class="content">Main Content</div>
</div>
Advantages:
  • Simple and clean code
  • No wrapper element needed
  • Perfect for straightforward layouts
  • Use this for most applications

未指定
target
属性
。侧边栏会自动将下一个同级
<div>
元素
作为目标:
typescript
<ejs-sidebar id="sidebar" type="Push"></ejs-sidebar>
<div>  <!-- 自动成为目标 - 无需包裹元素 -->
  <div class="content">Main Content</div>
</div>
优势:
  • 代码简洁干净
  • 无需包裹元素
  • 适用于简单布局
  • 大多数应用推荐使用此方式

Explicit Targeting (Advanced - When You Need Control)

显式目标(高级 - 需要精细控制时)

Use the
[target]="'#selector'"
property to explicitly specify which element to affect:
typescript
<ejs-sidebar [target]="'#content-area'" type="Push"></ejs-sidebar>
<div id="content-area">              <!-- Explicit target -->
  <div>                              <!-- ⚠️ REQUIRED: Inner wrapper -->
    <div class="content">Main Content</div>
  </div>
</div>
⚠️ IMPORTANT: When using explicit
target
, you MUST include an inner wrapper
<div>
inside the target container for CSS transforms to work correctly.
Use explicit targeting when:
  • You want to exclude certain elements (header, footer) from sidebar effects
  • You have complex layouts with multiple sections
  • You need fine-grained control over transformation

使用**
[target]="'#selector'"
**属性明确指定要影响的元素:
typescript
<ejs-sidebar [target]="'#content-area'" type="Push"></ejs-sidebar>
<div id="content-area">              <!-- 显式目标 -->
  <div>                              <!-- ⚠️ 必填:内部包裹元素 -->
    <div class="content">Main Content</div>
  </div>
</div>
⚠️ 重要提示: 使用显式
target
时,必须在目标容器内包含一个内部包裹
<div>
,以确保CSS变换正常工作。
在以下场景使用显式目标:
  • 希望将某些元素(页眉、页脚)排除在侧边栏影响之外
  • 拥有包含多个区块的复杂布局
  • 需要对变换进行精细控制

When to Use Each Mode

何时使用每种模式

ModeWhen to UseComplexityWrapper Needed
Implicit (No target)Default for most layoutsSimple❌ No
Explicit (With target)Complex layouts, selective targetingAdvanced✅ Yes (inner)
See detailed examples in references/sidebar-positioning.md

模式使用场景复杂度是否需要包裹元素
隐式(无target)大多数布局的默认选择简单❌ 不需要
显式(有target)复杂布局、选择性定位高级✅ 需要(内部包裹)
详见references/sidebar-positioning.md中的详细示例

API Properties Reference

API属性参考

The Sidebar component exposes the following properties to control its behavior and appearance:
Sidebar组件提供以下属性用于控制其行为和外观:

animate

animate

Type:
boolean
| Default:
true
Enable or disable animation transitions when expanding or collapsing the sidebar.
typescript
// Example: Disable animations for instant toggle
<ejs-sidebar [animate]="false"></ejs-sidebar>

// Example: Enable animations (default)
<ejs-sidebar [animate]="true"></ejs-sidebar>

类型:
boolean
| 默认值:
true
启用或禁用侧边栏展开/折叠时的动画过渡效果。
typescript
// 示例:禁用动画以实现即时切换
<ejs-sidebar [animate]="false"></ejs-sidebar>

// 示例:启用动画(默认)
<ejs-sidebar [animate]="true"></ejs-sidebar>

closeOnDocumentClick

closeOnDocumentClick

Type:
boolean
| Default:
false
Specifies whether the sidebar closes when clicking outside of it on the main content area.
typescript
// Example: Auto-close sidebar on document click
<ejs-sidebar [closeOnDocumentClick]="true"></ejs-sidebar>

// Example: In component
this.closeOnClick = true;

类型:
boolean
| 默认值:
false
指定点击主内容区域的侧边栏外部时是否关闭侧边栏。
typescript
// 示例:点击文档区域时自动关闭侧边栏
<ejs-sidebar [closeOnDocumentClick]="true"></ejs-sidebar>

// 示例:在组件中设置
this.closeOnClick = true;

dockSize

dockSize

Type:
string | number
| Default:
'auto'
Specifies the width of the sidebar when in dock state (collapsed but still visible with icons).
typescript
// Example: Set dock size to 72 pixels
<ejs-sidebar [dockSize]="'72px'" [enableDock]="true"></ejs-sidebar>

// Example: Set as number
<ejs-sidebar [dockSize]="72" [enableDock]="true"></ejs-sidebar>

// Example: In component
public dockSize: string = '72px';

类型:
string | number
| 默认值:
'auto'
指定侧边栏处于停靠状态(折叠但仍显示图标)时的宽度。
typescript
// 示例:将停靠尺寸设置为72像素
<ejs-sidebar [dockSize]="'72px'" [enableDock]="true"></ejs-sidebar>

// 示例:以数字形式设置
<ejs-sidebar [dockSize]="72" [enableDock]="true"></ejs-sidebar>

// 示例:在组件中设置
public dockSize: string = '72px';

enableDock

enableDock

Type:
boolean
| Default:
false
Enables the docking state where sidebar shows icons only and expands on hover or click.
typescript
// Example: Enable docking for icon-only sidebar
<ejs-sidebar [enableDock]="true" [dockSize]="'72px'">
  <div class="sidebar-item" title="Home">
    <i class="e-icons e-home"></i>
  </div>
  <div class="sidebar-item" title="Settings">
    <i class="e-icons e-settings"></i>
  </div>
</ejs-sidebar>

// Example: In component
public enableDock = true;
public dockSize = '72px';

类型:
boolean
| 默认值:
false
启用停靠状态,此时侧边栏仅显示图标,并在悬停或点击时展开。
typescript
// 示例:启用仅显示图标的侧边栏停靠功能
<ejs-sidebar [enableDock]="true" [dockSize]="'72px'">
  <div class="sidebar-item" title="Home">
    <i class="e-icons e-home"></i>
  </div>
  <div class="sidebar-item" title="Settings">
    <i class="e-icons e-settings"></i>
  </div>
</ejs-sidebar>

// 示例:在组件中设置
public enableDock = true;
public dockSize = '72px';

enableGestures

enableGestures

Type:
boolean
| Default:
true
Enables touch gestures (swipe) to open/close the sidebar on touch devices.
typescript
// Example: Enable gesture support (default)
<ejs-sidebar [enableGestures]="true"></ejs-sidebar>

// Example: Disable gestures for specific use cases
<ejs-sidebar [enableGestures]="false"></ejs-sidebar>

类型:
boolean
| 默认值:
true
启用触摸手势(滑动)以在触控设备上打开/关闭侧边栏。
typescript
// 示例:启用手势支持(默认)
<ejs-sidebar [enableGestures]="true"></ejs-sidebar>

// 示例:针对特定场景禁用手势
<ejs-sidebar [enableGestures]="false"></ejs-sidebar>

enablePersistence

enablePersistence

Type:
boolean
| Default:
false
Enable persisting the sidebar state (open/closed, position, type) between page reloads using localStorage.
typescript
// Example: Enable persistence to remember sidebar state
<ejs-sidebar [enablePersistence]="true"></ejs-sidebar>

// Persisted states:
// 1. Position (Left/Right)
// 2. Type (Push/Slide/Over/Auto)
// 3. Open/Closed state

类型:
boolean
| 默认值:
false
启用侧边栏状态(打开/关闭、位置、类型)在页面刷新之间的持久化,使用localStorage存储。
typescript
// 示例:启用持久化以记住侧边栏状态
<ejs-sidebar [enablePersistence]="true"></ejs-sidebar>

// 持久化的状态包括:
// 1. 位置(左/右)
// 2. 类型(Push/Slide/Over/Auto)
// 3. 打开/关闭状态

enableRtl

enableRtl

Type:
boolean
| Default:
false
Specifies right-to-left layout for the sidebar, useful for RTL languages like Arabic and Hebrew.
typescript
// Example: Enable RTL layout
<ejs-sidebar [enableRtl]="true"></ejs-sidebar>

// Example: Dynamically set based on language
public isRtl = document.documentElement.lang === 'ar';
<ejs-sidebar [enableRtl]="isRtl"></ejs-sidebar>

类型:
boolean
| 默认值:
false
指定侧边栏的从右到左布局,适用于阿拉伯语和希伯来语等RTL语言。
typescript
// 示例:启用RTL布局
<ejs-sidebar [enableRtl]="true"></ejs-sidebar>

// 示例:根据语言动态设置
public isRtl = document.documentElement.lang === 'ar';
<ejs-sidebar [enableRtl]="isRtl"></ejs-sidebar>

isOpen

isOpen

Type:
boolean
| Default:
false
Gets or sets whether the sidebar is in open (expanded) or closed (collapsed) state.
typescript
// Example: Initially open sidebar
<ejs-sidebar [isOpen]="true"></ejs-sidebar>

// Example: Initially closed (default)
<ejs-sidebar [isOpen]="false"></ejs-sidebar>

// Example: Toggle state from component
@ViewChild('sidebar') sidebar?: SidebarComponent;

toggleOpen() {
  this.sidebar!.isOpen = !this.sidebar!.isOpen;
}

// Note: When sidebar type is 'Auto', this property is ignored on mobile devices

类型:
boolean
| 默认值:
false
获取或设置侧边栏处于打开(展开)还是关闭(折叠)状态。
typescript
// 示例:初始状态为打开的侧边栏
<ejs-sidebar [isOpen]="true"></ejs-sidebar>

// 示例:初始状态为关闭(默认)
<ejs-sidebar [isOpen]="false"></ejs-sidebar>

// 示例:从组件中切换状态
@ViewChild('sidebar') sidebar?: SidebarComponent;

toggleOpen() {
  this.sidebar!.isOpen = !this.sidebar!.isOpen;
}

// 注意:当侧边栏类型为'Auto'时,此属性在移动设备上会被忽略

mediaQuery

mediaQuery

Type:
string | MediaQueryList
| Default:
null
Specifies a media query string that automatically opens the sidebar when the query matches.
typescript
// Example: Open sidebar on screens wider than 600px
<ejs-sidebar [mediaQuery]="'(min-width: 600px)'"></ejs-sidebar>

// Example: Using MediaQueryList object
public mediaQuery = window.matchMedia('(min-width: 768px)');
<ejs-sidebar [mediaQuery]="mediaQuery"></ejs-sidebar>

// Example: Common breakpoints
// Mobile: '(max-width: 600px)'
// Tablet: '(min-width: 601px) and (max-width: 1024px)'
// Desktop: '(min-width: 1025px)'

类型:
string | MediaQueryList
| 默认值:
null
指定媒体查询字符串,当查询匹配时自动打开侧边栏。
typescript
// 示例:在屏幕宽度大于600px时打开侧边栏
<ejs-sidebar [mediaQuery]="'(min-width: 600px)'"></ejs-sidebar>

// 示例:使用MediaQueryList对象
public mediaQuery = window.matchMedia('(min-width: 768px)');
<ejs-sidebar [mediaQuery]="mediaQuery"></ejs-sidebar>

// 示例:常见断点
// 移动端: '(max-width: 600px)'
// 平板端: '(min-width: 601px) and (max-width: 1024px)'
// 桌面端: '(min-width: 1025px)'

position

position

Type:
SidebarPosition
| Default:
'Left'
Specifies the position of the sidebar:
'Left'
or
'Right'
.
typescript
// Example: Position sidebar on the left (default)
<ejs-sidebar [position]="'Left'"></ejs-sidebar>

// Example: Position sidebar on the right
<ejs-sidebar [position]="'Right'"></ejs-sidebar>

// Example: Set position dynamically
public sidebarPosition: SidebarPosition = 'Left';
<ejs-sidebar [position]="sidebarPosition"></ejs-sidebar>
Available values:
  • 'Left'
    - Sidebar appears on the left side
  • 'Right'
    - Sidebar appears on the right side

类型:
SidebarPosition
| 默认值:
'Left'
指定侧边栏的位置:
'Left'
'Right'
typescript
// 示例:将侧边栏定位在左侧(默认)
<ejs-sidebar [position]="'Left'"></ejs-sidebar>

// 示例:将侧边栏定位在右侧
<ejs-sidebar [position]="'Right'"></ejs-sidebar>

// 示例:动态设置位置
public sidebarPosition: SidebarPosition = 'Left';
<ejs-sidebar [position]="sidebarPosition"></ejs-sidebar>
可用值:
  • 'Left'
    - 侧边栏显示在左侧
  • 'Right'
    - 侧边栏显示在右侧

showBackdrop

showBackdrop

Type:
boolean
| Default:
false
Specifies whether to display an overlay backdrop on the main content when sidebar is open.
typescript
// Example: Show backdrop overlay
<ejs-sidebar [showBackdrop]="true"></ejs-sidebar>

// Example: Backdrop with auto-close on click
<ejs-sidebar [showBackdrop]="true" [closeOnDocumentClick]="true"></ejs-sidebar>

// Example: Combine with other properties
<ejs-sidebar 
  [showBackdrop]="true" 
  [closeOnDocumentClick]="true"
  [type]="'Over'">
</ejs-sidebar>

类型:
boolean
| 默认值:
false
指定侧边栏打开时是否在主内容上显示背景遮罩。
typescript
// 示例:显示背景遮罩
<ejs-sidebar [showBackdrop]="true"></ejs-sidebar>

// 示例:点击遮罩时自动关闭侧边栏
<ejs-sidebar [showBackdrop]="true" [closeOnDocumentClick]="true"></ejs-sidebar>

// 示例:结合其他属性使用
<ejs-sidebar 
  [showBackdrop]="true" 
  [closeOnDocumentClick]="true"
  [type]="'Over'">
</ejs-sidebar>

target

target

Type:
HTMLElement | string
| Default:
null
Specifies which element the sidebar will affect (push/slide/transform). See Target Property Behavior section above.
⚠️ Important: When using explicit target with transform types (Push/Slide), include an inner wrapper
<div>
inside the target container.
typescript
// ✅ Example: Explicit targeting with ID selector (CORRECT - with wrapper)
<ejs-sidebar [target]="'#content-area'" [type]="'Push'"></ejs-sidebar>
<div id="content-area">
  <div>  <!-- Required wrapper for transforms -->
    <div>Content here</div>
  </div>
</div>

// ✅ Example: Explicit targeting with CSS class (CORRECT - with wrapper)
<ejs-sidebar [target]="'.main-content'" [type]="'Push'"></ejs-sidebar>
<div class="main-content">
  <div>  <!-- Required wrapper for transforms -->
    <div>Content here</div>
  </div>
</div>

// ✅ Example: Pass HTMLElement directly
@ViewChild('targetDiv') targetElement?: ElementRef;
<ejs-sidebar [target]="targetElement?.nativeElement" [type]="'Push'"></ejs-sidebar>
<div #targetDiv>
  <div>  <!-- Required wrapper for transforms -->
    <div>Content here</div>
  </div>
</div>

类型:
HTMLElement | string
| 默认值:
null
指定侧边栏将影响的元素(推送/滑动/变换)。详见上方的Target属性行为部分。
⚠️ 重要提示: 使用显式目标和变换类型(Push/Slide)时,需在目标容器内包含一个内部包裹
<div>
typescript
// ✅ 示例:使用ID选择器的显式定位(正确 - 包含包裹元素)
<ejs-sidebar [target]="'#content-area'" [type]="'Push'"></ejs-sidebar>
<div id="content-area">
  <div>  // 变换所需的必填包裹元素
    <div>Content here</div>
  </div>
</div>

// ✅ 示例:使用CSS类的显式定位(正确 - 包含包裹元素)
<ejs-sidebar [target]="'.main-content'" [type]="'Push'"></ejs-sidebar>
<div class="main-content">
  <div>  // 变换所需的必填包裹元素
    <div>Content here</div>
  </div>
</div>

// ✅ 示例:直接传递HTMLElement
@ViewChild('targetDiv') targetElement?: ElementRef;
<ejs-sidebar [target]="targetElement?.nativeElement" [type]="'Push'"></ejs-sidebar>
<div #targetDiv>
  <div>  // 变换所需的必填包裹元素
    <div>Content here</div>
  </div>
</div>

type

type

Type:
SidebarType
| Default:
'Auto'
Specifies how the sidebar expands:
'Push'
,
'Slide'
,
'Over'
, or
'Auto'
.
typescript
// Example: Push type - sidebar pushes content aside
<ejs-sidebar [type]="'Push'"></ejs-sidebar>

// Example: Slide type - sidebar slides over and translates content
<ejs-sidebar [type]="'Slide'"></ejs-sidebar>

// Example: Over type - sidebar floats over content
<ejs-sidebar [type]="'Over'"></ejs-sidebar>

// Example: Auto type - Over on mobile, Push on desktop
<ejs-sidebar [type]="'Auto'"></ejs-sidebar>
Available values:
  • 'Push'
    - Sidebar pushes main content to the side
  • 'Slide'
    - Sidebar slides and translates main content
  • 'Over'
    - Sidebar floats over main content
  • 'Auto'
    - Responsive (Over on mobile, Push on desktop)

类型:
SidebarType
| 默认值:
'Auto'
指定侧边栏的展开方式:
'Push'
'Slide'
'Over'
'Auto'
typescript
// 示例:Push类型 - 侧边栏将内容推到一旁
<ejs-sidebar [type]="'Push'"></ejs-sidebar>

// 示例:Slide类型 - 侧边栏滑动并平移内容
<ejs-sidebar [type]="'Slide'"></ejs-sidebar>

// 示例:Over类型 - 侧边栏悬浮在内容上方
<ejs-sidebar [type]="'Over'"></ejs-sidebar>

// 示例:Auto类型 - 移动端为Over,桌面端为Push
<ejs-sidebar [type]="'Auto'"></ejs-sidebar>
可用值:
  • 'Push'
    - 侧边栏将主内容推到一侧
  • 'Slide'
    - 侧边栏滑动并平移主内容
  • 'Over'
    - 侧边栏悬浮在主内容上方
  • 'Auto'
    - 响应式(移动端为Over,桌面端为Push)

width

width

Type:
string | number
| Default:
'280px'
Specifies the width of the sidebar in its expanded state. Can be set in pixels, percentages, or em units.
typescript
// Example: Set width in pixels
<ejs-sidebar [width]="'300px'"></ejs-sidebar>

// Example: Set width as number (treated as pixels)
<ejs-sidebar [width]="300"></ejs-sidebar>

// Example: Set width in percentage
<ejs-sidebar [width]="'50%'"></ejs-sidebar>

// Example: Set width in em units
<ejs-sidebar [width]="'20em'"></ejs-sidebar>

// Example: Responsive width
public sidebarWidth = window.innerWidth < 768 ? '100%' : '300px';
<ejs-sidebar [width]="sidebarWidth"></ejs-sidebar>

类型:
string | number
| 默认值:
'280px'
指定侧边栏展开状态下的宽度。可设置为像素、百分比或em单位。
typescript
// 示例:以像素设置宽度
<ejs-sidebar [width]="'300px'"></ejs-sidebar>

// 示例:以数字设置宽度(视为像素)
<ejs-sidebar [width]="300"></ejs-sidebar>

// 示例:以百分比设置宽度
<ejs-sidebar [width]="'50%'"></ejs-sidebar>

// 示例:以em单位设置宽度
<ejs-sidebar [width]="'20em'"></ejs-sidebar>

// 示例:响应式宽度
public sidebarWidth = window.innerWidth < 768 ? '100%' : '300px';
<ejs-sidebar [width]="sidebarWidth"></ejs-sidebar>

zIndex

zIndex

Type:
string | number
| Default:
1000
Specifies the z-index of the sidebar. Only applicable when sidebar type is
'Over'
or
'Auto'
on mobile.
typescript
// Example: Set z-index for layering
<ejs-sidebar [zIndex]="1000"></ejs-sidebar>

// Example: High z-index to appear above other modals
<ejs-sidebar [zIndex]="9999" [type]="'Over'"></ejs-sidebar>

类型:
string | number
| 默认值:
1000
指定侧边栏的z-index值。仅当侧边栏类型为
'Over'
或移动端的
'Auto'
时适用。
typescript
// 示例:设置层级的z-index
<ejs-sidebar [zIndex]="1000"></ejs-sidebar>

// 示例:设置高z-index以显示在其他模态框上方
<ejs-sidebar [zIndex]="9999" [type]="'Over'"></ejs-sidebar>

API Methods Reference

API方法参考

The Sidebar component provides the following methods for programmatic control:
Sidebar组件提供以下方法用于程序化控制:

show(e?: Event)

show(e?: Event)

Description: Shows the sidebar if it's currently closed.
Parameters:
  • e
    (optional) - The event triggering the show action (MouseEvent | Event)
Returns:
void
Example:
typescript
import { Component, ViewChild } from '@angular/core';
import { SidebarComponent } from '@syncfusion/ej2-angular-navigations';

@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar #sidebar></ejs-sidebar>
    <button (click)="openSidebar()">Open Sidebar</button>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  // Method 1: Show without event
  openSidebar() {
    this.sidebar?.show();
  }

  // Method 2: Show with event
  openSidebarWithEvent(event: MouseEvent) {
    this.sidebar?.show(event);
  }
}

描述: 如果侧边栏当前处于关闭状态,则将其显示。
参数:
  • e
    (可选)- 触发显示操作的事件(MouseEvent | Event)
返回值:
void
示例:
typescript
import { Component, ViewChild } from '@angular/core';
import { SidebarComponent } from '@syncfusion/ej2-angular-navigations';

@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar #sidebar></ejs-sidebar>
    <button (click)="openSidebar()">Open Sidebar</button>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  // 方法1:无事件触发显示
  openSidebar() {
    this.sidebar?.show();
  }

  // 方法2:带事件触发显示
  openSidebarWithEvent(event: MouseEvent) {
    this.sidebar?.show(event);
  }
}

hide(e?: Event)

hide(e?: Event)

Description: Hides the sidebar if it's currently open.
Parameters:
  • e
    (optional) - The event triggering the hide action (MouseEvent | Event)
Returns:
void
Example:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar #sidebar></ejs-sidebar>
    <button (click)="closeSidebar()">Close Sidebar</button>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  // Method 1: Hide without event
  closeSidebar() {
    this.sidebar?.hide();
  }

  // Method 2: Hide with click event
  closeSidebarOnClick(event: MouseEvent) {
    this.sidebar?.hide(event);
  }
}

描述: 如果侧边栏当前处于打开状态,则将其隐藏。
参数:
  • e
    (可选)- 触发隐藏操作的事件(MouseEvent | Event)
返回值:
void
示例:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar #sidebar></ejs-sidebar>
    <button (click)="closeSidebar()">Close Sidebar</button>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  // 方法1:无事件触发隐藏
  closeSidebar() {
    this.sidebar?.hide();
  }

  // 方法2:带点击事件触发隐藏
  closeSidebarOnClick(event: MouseEvent) {
    this.sidebar?.hide(event);
  }
}

toggle()

toggle()

Description: Toggles the sidebar between open and closed states.
Returns:
void
Example:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar #sidebar id="sidebar" [isOpen]="false">
      <button (click)="toggleMenu()">Close</button>
    </ejs-sidebar>
    <button (click)="toggleMenu()">☰ Menu</button>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  toggleMenu() {
    this.sidebar?.toggle();
  }
}

描述: 在侧边栏的打开和关闭状态之间切换。
返回值:
void
示例:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar #sidebar id="sidebar" [isOpen]="false">
      <button (click)="toggleMenu()">Close</button>
    </ejs-sidebar>
    <button (click)="toggleMenu()">☰ Menu</button>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  toggleMenu() {
    this.sidebar?.toggle();
  }
}

destroy()

destroy()

Description: Removes the sidebar control from the DOM and detaches all event handlers and attributes.
Returns:
void
Example:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar #sidebar></ejs-sidebar>
    <button (click)="destroySidebar()">Destroy Sidebar</button>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  // Destroy and remove the sidebar
  destroySidebar() {
    this.sidebar?.destroy();
  }
}

描述: 从DOM中移除侧边栏控件,并分离所有事件处理程序和属性。
返回值:
void
示例:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar #sidebar></ejs-sidebar>
    <button (click)="destroySidebar()">Destroy Sidebar</button>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  // 销毁并移除侧边栏
  destroySidebar() {
    this.sidebar?.destroy();
  }
}

dataBind()

dataBind()

Description: Applies pending property changes to the sidebar component. Use this method after dynamically changing sidebar properties to ensure changes are rendered immediately.
Returns:
void
Example:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar 
      [width]="sidebarWidth"
      [type]="sidebarType">
    </ejs-sidebar>
    <button (click)="changeSidebarProperties()">Change Properties</button>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  sidebarWidth = '280px';
  sidebarType = 'Push';

  // Change sidebar properties dynamically
  changeSidebarProperties() {
    // Modify properties
    this.sidebarWidth = '350px';
    this.sidebarType = 'Slide';
    
    // Apply changes to the component
    (this.sidebar as SidebarComponent).dataBind();
  }

  // Another example: Toggle width on docked state
  updateDockSize() {
    (this.sidebar as SidebarComponent).dockSize = '100px';
    (this.sidebar as SidebarComponent).dataBind();
  }
}

描述: 将待处理的属性变更应用到侧边栏组件。动态更改侧边栏属性后,使用此方法确保变更立即生效。
返回值:
void
示例:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar 
      [width]="sidebarWidth"
      [type]="sidebarType">
    </ejs-sidebar>
    <button (click)="changeSidebarProperties()">Change Properties</button>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  sidebarWidth = '280px';
  sidebarType = 'Push';

  // 动态更改侧边栏属性
  changeSidebarProperties() {
    // 修改属性
    this.sidebarWidth = '350px';
    this.sidebarType = 'Slide';
    
    // 将变更应用到组件
    (this.sidebar as SidebarComponent).dataBind();
  }

  // 另一个示例:在停靠状态下切换宽度
  updateDockSize() {
    (this.sidebar as SidebarComponent).dockSize = '100px';
    (this.sidebar as SidebarComponent).dataBind();
  }
}

API Events Reference

API事件参考

The Sidebar component emits the following events during its lifecycle and interactions:
Sidebar组件在其生命周期和交互过程中会触发以下事件:

open

open

Description: Triggers when the sidebar is opened.
Event Arguments:
EventArgs
EventArgs Properties:
  • cancel
    (boolean) - Set to true to prevent the open action
  • element
    (HTMLElement) - The sidebar DOM element
  • event
    (MouseEvent | Event) - The original browser event
  • isInteracted
    (boolean) - Whether the user interacted to trigger the open
  • model
    (SidebarModel) - The sidebar model instance
Example:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar
      (open)="onOpen($event)">
    </ejs-sidebar>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  onOpen(event: any) {
    console.log('Sidebar opened');
    console.log('Event:', event.event);
    console.log('Element:', event.element);
    console.log('Is Interacted:', event.isInteracted);
    
    // Prevent opening if needed
    // event.cancel = true;
  }
}

描述: 侧边栏打开时触发。
事件参数:
EventArgs
EventArgs属性:
  • cancel
    (boolean) - 设置为true可阻止打开操作
  • element
    (HTMLElement) - 侧边栏DOM元素
  • event
    (MouseEvent | Event) - 原始浏览器事件
  • isInteracted
    (boolean) - 是否由用户交互触发打开
  • model
    (SidebarModel) - 侧边栏模型实例
示例:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar
      (open)="onOpen($event)">
    </ejs-sidebar>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  onOpen(event: any) {
    console.log('Sidebar opened');
    console.log('Event:', event.event);
    console.log('Element:', event.element);
    console.log('Is Interacted:', event.isInteracted);
    
    // 如需阻止打开
    // event.cancel = true;
  }
}

close

close

Description: Triggers when the sidebar is closed.
Event Arguments:
EventArgs
EventArgs Properties:
  • cancel
    (boolean) - Set to true to prevent the close action
  • element
    (HTMLElement) - The sidebar DOM element
  • event
    (MouseEvent | Event) - The original browser event
  • isInteracted
    (boolean) - Whether the user interacted to trigger the close
  • model
    (SidebarModel) - The sidebar model instance
Example:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar
      (close)="onClose($event)">
    </ejs-sidebar>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  onClose(event: any) {
    console.log('Sidebar closed');
    console.log('Is Interacted:', event.isInteracted);
    
    // Prevent closing if needed
    // event.cancel = true;
  }
}

描述: 侧边栏关闭时触发。
事件参数:
EventArgs
EventArgs属性:
  • cancel
    (boolean) - 设置为true可阻止关闭操作
  • element
    (HTMLElement) - 侧边栏DOM元素
  • event
    (MouseEvent | Event) - 原始浏览器事件
  • isInteracted
    (boolean) - 是否由用户交互触发关闭
  • model
    (SidebarModel) - 侧边栏模型实例
示例:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar
      (close)="onClose($event)">
    </ejs-sidebar>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  onClose(event: any) {
    console.log('Sidebar closed');
    console.log('Is Interacted:', event.isInteracted);
    
    // 如需阻止关闭
    // event.cancel = true;
  }
}

change

change

Description: Triggers when the sidebar state changes between open and closed.
Event Arguments:
ChangeEventArgs
ChangeEventArgs Properties:
  • element
    (HTMLElement) - The sidebar DOM element
  • name
    (string) - Event name: 'change'
Example:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar
      (change)="onChange($event)">
    </ejs-sidebar>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  onChange(event: any) {
    console.log('Sidebar state changed');
    console.log('Event name:', event.name);
    console.log('Element:', event.element);
  }
}

描述: 侧边栏在打开和关闭状态之间切换时触发。
事件参数:
ChangeEventArgs
ChangeEventArgs属性:
  • element
    (HTMLElement) - 侧边栏DOM元素
  • name
    (string) - 事件名称: 'change'
示例:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar
      (change)="onChange($event)">
    </ejs-sidebar>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  onChange(event: any) {
    console.log('Sidebar state changed');
    console.log('Event name:', event.name);
    console.log('Element:', event.element);
  }
}

created

created

Description: Triggers when the sidebar component is created and initialized.
Event Arguments:
Object
Example:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar
      (created)="onCreated($event)"
      style="visibility: hidden">
    </ejs-sidebar>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  onCreated(event: any) {
    console.log('Sidebar created and initialized');
    // Make sidebar visible after creation
    (this.sidebar as SidebarComponent).element.style.visibility = '';
  }
}

描述: 侧边栏组件创建并初始化完成时触发。
事件参数:
Object
示例:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar
      (created)="onCreated($event)"
      style="visibility: hidden">
    </ejs-sidebar>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  onCreated(event: any) {
    console.log('Sidebar created and initialized');
    // 创建完成后显示侧边栏
    (this.sidebar as SidebarComponent).element.style.visibility = '';
  }
}

destroyed

destroyed

Description: Triggers when the sidebar component is destroyed.
Event Arguments:
Object
Example:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar
      (destroyed)="onDestroyed($event)">
    </ejs-sidebar>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  onDestroyed(event: any) {
    console.log('Sidebar destroyed');
    // Cleanup any additional resources
  }
}

描述: 侧边栏组件被销毁时触发。
事件参数:
Object
示例:
typescript
@Component({
  selector: 'app-root',
  template: `
    <ejs-sidebar 
      #sidebar
      (destroyed)="onDestroyed($event)">
    </ejs-sidebar>
  `
})
export class AppComponent {
  @ViewChild('sidebar') sidebar?: SidebarComponent;

  onDestroyed(event: any) {
    console.log('Sidebar destroyed');
    // 清理额外资源
  }
}

Common Patterns

常见模式

Pattern 1: Toggle Button Sidebar

模式1:切换按钮侧边栏

Open/close sidebar with button clicks using the toggle() method. Perfect for mobile navigation and responsive layouts.
typescript
// In component.ts
toggleSidebar() {
  this.sidebar?.toggle();
}

// In template
<button (click)="toggleSidebar()">Toggle</button>
使用toggle()方法通过按钮点击打开/关闭侧边栏。适用于移动端导航和响应式布局。
typescript
// 在component.ts中
toggleSidebar() {
  this.sidebar?.toggle();
}

// 在模板中
<button (click)="toggleSidebar()">Toggle</button>

Pattern 2: Responsive Auto-Close

模式2:响应式自动关闭

Automatically collapse sidebar on small screens using mediaQuery property.
typescript
public mediaQuery = window.matchMedia('(max-width: 600px)');
// In template
<ejs-sidebar [mediaQuery]="mediaQuery" [isOpen]="true">
使用mediaQuery属性在小屏幕上自动折叠侧边栏。
typescript
public mediaQuery = window.matchMedia('(max-width: 600px)');
// 在模板中
<ejs-sidebar [mediaQuery]="mediaQuery" [isOpen]="true">

Pattern 3: Docked Navigation with Icons

模式3:带图标的停靠导航

Create a compact icon-only docked state that expands on click.
typescript
public enableDock = true;
public dockSize = '72px';
// In template
<ejs-sidebar [enableDock]="enableDock" [dockSize]="dockSize">
创建仅显示图标的紧凑停靠状态,点击时展开。
typescript
public enableDock = true;
public dockSize = '72px';
// 在模板中
<ejs-sidebar [enableDock]="enableDock" [dockSize]="dockSize">

Pattern 4: Backdrop for Focus

模式4:聚焦用背景遮罩

Use backdrop to overlay main content and focus on sidebar.
typescript
// In template
<ejs-sidebar [showBackdrop]="true" [closeOnDocumentClick]="true">
使用背景遮罩覆盖主内容,聚焦侧边栏。
typescript
// 在模板中
<ejs-sidebar [showBackdrop]="true" [closeOnDocumentClick]="true">

Key Properties

关键属性

PropertyTypeDefaultPurpose
type
Push | Slide | Over | AutoAutoExpand behavior and content interaction
position
Left | RightLeftSidebar direction and positioning
width
string | number280pxSidebar width in expanded state
dockSize
string | numberautoWidth when docked/collapsed
enableDock
booleanfalseEnable compact docked state
isOpen
booleanfalseInitial open/closed state
animate
booleantrueEnable expand/collapse animations
showBackdrop
booleanfalseDisplay overlay on main content
closeOnDocumentClick
booleanfalseClose when clicking outside
enableGestures
booleantrueEnable touch swipe gestures
mediaQuery
string | MediaQueryListnullAuto-close on screen size match
enableRtl
booleanfalseRight-to-left layout support
enablePersistence
booleanfalsePersist state between page reloads
属性类型默认值用途
type
Push | Slide | Over | AutoAuto展开行为与内容交互方式
position
Left | RightLeft侧边栏方向与定位
width
string | number280px侧边栏展开状态下的宽度
dockSize
string | numberauto停靠/折叠状态下的宽度
enableDock
booleanfalse启用紧凑停靠状态
isOpen
booleanfalse初始打开/关闭状态
animate
booleantrue启用展开/折叠动画
showBackdrop
booleanfalse在主内容上显示遮罩
closeOnDocumentClick
booleanfalse点击外部时关闭
enableGestures
booleantrue启用触摸滑动手势
mediaQuery
string | MediaQueryListnull匹配屏幕尺寸时自动关闭
enableRtl
booleanfalse支持从右到左布局
enablePersistence
booleanfalse在页面刷新之间持久化状态

Common Use Cases

常见使用场景

  1. App Navigation Menu - Top-level navigation with toggle button
  2. Mobile Menu - Responsive sidebar that auto-closes on small screens
  3. Settings Panel - Docked icon-based panel expanding to show options
  4. Hierarchical Navigation - TreeView-based nested menu structure
  5. Content Sidebar - Always-visible sidebar alongside main content
  6. Mail Application - Folder tree with email list (ListView + TreeView)
  7. Dashboard Layout - Collapsible widget panel
  8. RTL Application - Right-to-left sidebar for Arabic/Hebrew interfaces
  1. 应用导航菜单 - 带切换按钮的顶层导航
  2. 移动端菜单 - 在小屏幕上自动关闭的响应式侧边栏
  3. 设置面板 - 基于图标的停靠面板,展开后显示选项
  4. 层级导航 - 基于TreeView的嵌套菜单结构
  5. 内容侧边栏 - 始终显示在主内容旁的侧边栏
  6. 邮件应用 - 文件夹树与邮件列表(ListView + TreeView)
  7. 仪表板布局 - 可折叠的小组件面板
  8. RTL应用 - 适用于阿拉伯语/希伯来语界面的从右到左侧边栏

See Also

另请参阅