syncfusion-angular-sidebar

实现 Syncfusion Angular 侧边栏组件

Sidebar 是一个可展开和折叠的导航组件，可作为主内容旁的侧边容器，用于放置主要或次要内容。它支持灵活的显示/隐藏行为、多种定位模式（左、右、上、下）、多种展开类型（Push、Slide、Over、Auto）、紧凑状态下的停靠、触控手势、动画、响应式行为，以及包含 TreeView 和 ListView 在内的丰富内容。

何时使用此技能

• 实现可折叠的导航菜单或侧边栏
• 创建可根据屏幕尺寸自适应的响应式导航
• 构建支持仅显示图标停靠状态的可展开面板
• 为触控设备添加基于手势的侧边栏切换功能
• 将侧边栏定位到不同方向（左、右、上、下）
• 实现背景遮罩层，以聚焦侧边栏内容
• 使用 TreeView 或 ListView 创建多级导航
• 使用自动关闭行为管理侧边栏的可见性
• 使用 show()、hide()、toggle() 方法构建切换按钮
• 为侧边栏应用动画和 RTL 支持

文档和导航指南

快速入门

📄 阅读： references/getting-started.md

• Angular CLI 设置和项目初始化（推荐）
• 安装 Syncfusion 包（Ivy 和 ngcc 版本）
• 导入模块和 CSS 样式
• 创建基本侧边栏组件
• 设置并初始化 ViewChild

SystemJS 设置（替代方案）

📄 阅读： references/systemjs-setup.md

• SystemJS 配置和安装
• 配置包含 Syncfusion 映射的 systemjs.config.js
• UMD 包配置
• 使用 SystemJS 创建 Sidebar
• 开发服务器和运行应用程序
• SystemJS 与 Angular CLI 对比

侧边栏定位和行为

📄 阅读： references/sidebar-positioning.md

• 侧边栏类型：Push、Slide、Over、Auto
• 定位：左、右、上、下
• 为静态侧边栏设置固定定位
• 使用 enableDock 和 dockSize 属性实现停靠
• 在同一页面上使用多个侧边栏
• 使用 dataBind() 动态更新属性

侧边栏交互和控制

📄 阅读： references/sidebar-interactions.md

• 控制方法：show()、hide()、toggle()
• 使用 mediaQuery 实现响应式自动关闭
• 使用 closeOnDocumentClick 处理外部点击
• 使用 showBackdrop 显示背景遮罩层
• 使用 enableGestures 支持触控手势
• 处理打开和关闭事件

侧边栏内容和组件

📄 阅读： references/sidebar-content.md

• 集成 ListView 以显示列表内容
• 集成 TreeView 以显示分层菜单
• 自定义 HTML 内容和菜单项
• 配置目标元素
• 内容结构和布局模式

动画和样式

📄 阅读： references/animations-and-styles.md

• 使用 animate 属性控制动画
• 动画类型和变体
• 使用 Material3 和其他主题设置 CSS 主题
• 使用 enableRtl 支持 RTL（从右向左）
• 响应式设计模式
• 使用 CRG（自定义资源生成器）

高级功能和模式

📄 阅读： references/advanced-features.md

• 使用 enablePersistence 实现持久化
• RTL 实现细节
• 无障碍功能
• 使用路由隐藏侧边栏
• 性能优化
• 边缘情况和故障排除

快速入门示例

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 属性行为

侧边栏的 target 属性用于控制侧边栏展开/折叠时会影响哪个元素。它有两种不同的模式：

隐式指定目标（推荐 - 默认行为）

未指定 target 属性。 侧边栏会自动将下一个同级 <div> 元素作为目标：

<ejs-sidebar id="sidebar" type="Push"></ejs-sidebar>
<div>  
  <div class="content">Main Content</div>
</div>

✅ 优点：

• 代码简单整洁
• 无需包装元素
• 非常适合简单布局
• 大多数应用都应使用此方式

---

显式指定目标（高级 - 需要控制时使用）

使用 [target]="'#selector'" 属性，显式指定要影响的元素：

<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 变换正常工作。

在以下情况下使用显式指定目标：

• 想排除某些元素（页眉、页脚）不受侧边栏效果影响
• 布局复杂，包含多个区块
• 需要精细控制变换效果

---

何时使用各模式

模式	使用场景	复杂度	是否需要包装元素
隐式（无 target）	大多数布局的默认方式	简单	❌ 否
显式（带 target）	复杂布局、选择性指定目标	高级	✅ 是（内部）

详细示例请参见 references/sidebar-positioning.md

---

API 属性参考

Sidebar 组件提供以下属性，用于控制其行为和外观：

animate

类型： boolean | 默认值： true

启用或禁用侧边栏展开或折叠时的动画过渡效果。

// Example: Disable animations for instant toggle
<ejs-sidebar [animate]="false"></ejs-sidebar>

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

---

closeOnDocumentClick

类型： boolean | 默认值： false

指定在主内容区域点击侧边栏外部时，侧边栏是否关闭。

// Example: Auto-close sidebar on document click
<ejs-sidebar [closeOnDocumentClick]="true"></ejs-sidebar>

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

---

dockSize

类型： string | number | 默认值： 'auto'

指定侧边栏处于停靠状态（已折叠，但仍显示图标）时的宽度。

// 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';

---

enableDock

类型： boolean | 默认值： false

启用停靠状态，此时侧边栏仅显示图标，并在悬停或点击时展开。

// 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';

---

enableGestures

类型： boolean | 默认值： true

启用触控手势（滑动），以便在触控设备上打开或关闭侧边栏。

// Example: Enable gesture support (default)
<ejs-sidebar [enableGestures]="true"></ejs-sidebar>

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

---

enablePersistence

类型： boolean | 默认值： false

启用使用 localStorage 持久保存侧边栏状态（打开/关闭、位置、类型），以便在页面重新加载后保留状态。

// 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

---

enableRtl

类型： boolean | 默认值： false

指定侧边栏采用从右到左的布局，适用于阿拉伯语和希伯来语等 RTL 语言。

// 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>

---

isOpen

类型： boolean | 默认值： false

获取或设置侧边栏是否处于打开（展开）或关闭（折叠）状态。

// 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

---

mediaQuery

类型： string | MediaQueryList | 默认值： null

指定媒体查询字符串；查询匹配时会自动打开侧边栏。

// 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)'

---

position

类型： SidebarPosition | 默认值： 'Left'

指定侧边栏的位置：'Left' 或 'Right'。

// 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>

可用值：

• 'Left' - 侧边栏显示在左侧
• 'Right' - 侧边栏显示在右侧

---

showBackdrop

类型： boolean | 默认值： false

指定侧边栏打开时，是否在主内容上显示覆盖背景层。

// 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>

---

target

类型： HTMLElement | string | 默认值： null

指定侧边栏将影响的元素（推移/滑动/变换）。请参见上文的 目标属性行为 部分。

⚠️ 重要： 使用显式目标和变换类型（Push/Slide）时，请在目标容器内添加一个内部包装 <div>。

// ✅ Example: Explicit targeting with ID selector (CORRECT - with wrapper)
<ejs-sidebar [target]="'#content-area'" [type]="'Push'"></ejs-sidebar>
<div id="content-area">
  <div>  
    <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>  
    <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>  
    <div>Content here</div>
  </div>
</div>

---

type

类型： SidebarType | 默认值： 'Auto'

指定侧边栏的展开方式：'Push'、'Slide'、'Over' 或 'Auto'。

// 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>

可用值：

• 'Push' - 侧边栏将主内容推向一侧
• 'Slide' - 侧边栏滑动并平移主内容
• 'Over' - 侧边栏浮于主内容上方
• 'Auto' - 响应式（移动设备上为 Over，桌面设备上为 Push）

---

width

类型： string | number | 默认值： '280px'

指定侧边栏展开时的宽度。可以使用像素、百分比或 em 单位。

// 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>

---

zIndex

类型： string | number | 默认值： 1000

指定侧边栏的 z-index。仅当侧边栏类型为 'Over'，或移动设备上的 'Auto' 时适用。

// 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>

---

API 方法参考

Sidebar 组件提供以下方法，供程序化控制：

show(e?: Event)

描述： 如果侧边栏当前处于关闭状态，则显示侧边栏。

参数：

• e（可选）- 触发显示操作的事件（MouseEvent | Event）

返回值： void

示例：

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);
  }
}

---

hide(e?: Event)

描述： 如果侧边栏当前处于打开状态，则隐藏侧边栏。

参数：

• e（可选）- 触发隐藏操作的事件（MouseEvent | Event）

返回值： void

示例：

@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);
  }
}

---

toggle()

描述： 切换侧边栏的打开和关闭状态。

返回值： void

示例：

@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()

描述： 从 DOM 中移除侧边栏控件，并解除所有事件处理程序和属性。

返回值： void

示例：

@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();
  }
}

---

dataBind()

描述： 将待处理的属性更改应用到侧边栏组件。动态更改侧边栏属性后，请使用此方法确保立即渲染更改。

返回值： void

示例：

@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();
  }
}

---

API 事件参考

Sidebar 组件在其生命周期和交互过程中会触发以下事件：

open

描述： 侧边栏打开时触发。

事件参数： EventArgs

EventArgs 属性：

• cancel（boolean）- 设为 true 可阻止打开操作
• element（HTMLElement）- 侧边栏 DOM 元素
• event（MouseEvent | Event）- 原始浏览器事件
• isInteracted（boolean）- 用户是否通过交互触发打开
• model（SidebarModel）- 侧边栏模型实例

示例：

@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;
  }
}

---

close

描述： 侧边栏关闭时触发。

事件参数： EventArgs

EventArgs 属性：

• cancel（boolean）- 设为 true 可阻止关闭操作
• element（HTMLElement）- 侧边栏 DOM 元素
• event（MouseEvent | Event）- 原始浏览器事件
• isInteracted（boolean）- 用户是否通过交互触发关闭
• model（SidebarModel）- 侧边栏模型实例

示例：

@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;
  }
}

---

change

描述： 侧边栏在打开和关闭状态之间切换时触发。

事件参数： ChangeEventArgs

ChangeEventArgs 属性：

• element（HTMLElement）- 侧边栏 DOM 元素
• name（string）- 事件名称：'change'

示例：

@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

描述： 侧边栏组件创建并初始化时触发。

事件参数： Object

示例：

@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 = '';
  }
}

---

destroyed

描述： 侧边栏组件销毁时触发。

事件参数： Object

示例：

@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
  }
}

---

常见模式

模式 1：切换按钮侧边栏

使用 toggle() 方法通过按钮点击打开/关闭侧边栏。非常适合移动导航和响应式布局。

// In component.ts
toggleSidebar() {
  this.sidebar?.toggle();
}

// In template
<button (click)="toggleSidebar()">Toggle</button>

模式 2：响应式自动关闭

使用 mediaQuery 属性，在小屏幕上自动折叠侧边栏。

public mediaQuery = window.matchMedia('(max-width: 600px)');
// In template
<ejs-sidebar [mediaQuery]="mediaQuery" [isOpen]="true">

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

创建紧凑的纯图标停靠状态，并支持点击展开。

public enableDock = true;
public dockSize = '72px';
// In template
<ejs-sidebar [enableDock]="enableDock" [dockSize]="dockSize">

模式 4：聚焦背景遮罩

使用背景遮罩覆盖主要内容，并聚焦于侧边栏。

// In template
<ejs-sidebar [showBackdrop]="true" [closeOnDocumentClick]="true">

关键属性

属性	类型	默认值	用途
type	Push | Slide | Over | Auto	Auto	展开行为和内容交互
position	Left | Right	Left	侧边栏方向和位置
width	string | number	280px	展开状态下的侧边栏宽度
dockSize	string | number	auto	停靠／折叠时的宽度
enableDock	boolean	false	启用紧凑停靠状态
isOpen	boolean	false	初始打开／关闭状态
animate	boolean	true	启用展开／折叠动画
showBackdrop	boolean	false	在主要内容上显示遮罩
closeOnDocumentClick	boolean	false	点击外部时关闭
enableGestures	boolean	true	启用触摸滑动手势
mediaQuery	string | MediaQueryList	null	屏幕尺寸符合条件时自动关闭
enableRtl	boolean	false	支持从右向左的布局
enablePersistence	boolean	false	在页面重新加载期间保留状态

常见用例

1. 应用导航菜单 - 带切换按钮的顶级导航
2. 移动端菜单 - 可响应式调整的侧边栏，在小屏幕上自动关闭
3. 设置面板 - 基于图标的停靠面板，展开后显示选项
4. 分层导航 - 基于 TreeView 的嵌套菜单结构
5. 内容侧边栏 - 与主要内容并排显示的常驻侧边栏
6. 邮件应用 - 带邮件列表的文件夹树（ListView + TreeView）
7. 仪表板布局 - 可折叠的小组件面板
8. RTL 应用 - 面向阿拉伯语／希伯来语界面的从右向左侧边栏

另请参阅

• Syncfusion Angular Sidebar 文档
• Sidebar API 参考
• 组件事件和属性