syncfusion-blazor-sidebar

实现 Syncfusion Blazor 侧边栏组件

Syncfusion Blazor 侧边栏是一种响应式导航组件，可为导航内容预留屏幕空间。它支持多种定位模式、停靠和状态持久化，并可与其他 Syncfusion 组件无缝集成。

何时使用此技能

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

• 为 Blazor 应用添加可折叠的导航侧边栏
• 以编程方式控制侧边栏的打开／关闭状态
• 根据屏幕分辨率启用响应式行为
• 显示仅含图标的导航（停靠模式）
• 在页面导航期间保留侧边栏状态
• 显示多个采用不同定位方式的侧边栏
• 指定用于侧边栏上下文的 HTML 元素
• 在侧边栏中集成 ListView 或 TreeView 组件
• 为侧边栏外观应用自定义 CSS 样式
• 在 Blazor WebAssembly 或 .NET 8 应用中构建响应式布局

主要组件属性

属性	用途
IsOpen	获取或设置一个布尔值，用于指示侧边栏组件是打开还是关闭。当侧边栏类型设为 Auto 时，无论 IsOpen 属性的值如何，组件都会在桌面模式下展开，在移动模式下折叠。
Width	以像素或百分比设置侧边栏宽度
Type	侧边栏行为：Push、Over、Slide、Auto
Position	侧边栏位置：Left（默认）或 Right
EnableDock	折叠时仅显示图标（默认值：false）
DockSize	以像素为单位设置停靠区域的宽度
MediaQuery	用于响应式行为的 CSS 媒体查询
Target	用作侧边栏上下文的特定 HTML 元素
EnablePersistence	在 localStorage 中保留状态（默认值：false）
ShowBackdrop	在侧边栏后方显示遮罩，防止与内容交互
Animate	展开或折叠时启用动画过渡效果（默认值：true）
EnableRtl	为 RTL 语言以从右到左的方向显示侧边栏（默认值：false）

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 在 Visual Studio、VS Code 和 .NET CLI 中安装
• 配置 NuGet 包（Syncfusion.Blazor.Navigations、Syncfusion.Blazor.Themes）
• 导入命名空间并注册服务
• 引用主题样式表和脚本
• 渲染基本组件

Web 应用设置（.NET 8）

📄 阅读： references/web-app-setup.md

• 创建 Blazor Web App 项目
• 交互式渲染模式（Auto、Server、WebAssembly）
• 为客户端项目安装包
• 在 App.razor 中引用样式表和脚本
• 使用渲染模式指令

打开／关闭控制

📄 阅读： references/open-close-control.md

• IsOpen 属性和使用 @bind-IsOpen 进行双向绑定
• 用于编程控制的切换方法
• 基于按钮切换侧边栏
• 组合多个打开／关闭触发方式并进行标准事件处理

响应式与停靠功能

📄 阅读： references/responsive-docking.md

• 使用 MediaQuery 属性实现响应式行为
• 使用 EnableDock 属性启用仅含图标的导航模式
• 使用 DockSize 控制图标区域宽度
• 图标样式设置和字体配置
• 使用 ListItems 进行停靠并管理图标

状态持久化与目标上下文

📄 阅读： references/state-persistence-targets.md

• 使用 EnablePersistence 支持 localStorage
• 持久化功能正常工作所需的 ID
• 用于侧边栏上下文的 Target 属性
• 将侧边栏应用于特定 HTML 元素
• 与 Toolbar 和 AppBar 集成

样式与动画

📄 阅读： references/styling-customization.md

• 使用 Animate 属性控制动画
• 使用 EnableRtl 属性支持从右向左（RTL）布局
• CSS 过渡效果和自定义动画效果
• 基于状态的样式设置和视觉自定义
• 背景遮罩自定义和停靠样式

多个侧边栏

📄 阅读： references/multiple-sidebars.md

• 管理多个侧边栏实例
• Position 属性（左侧／右侧）
• 用于多侧边栏布局的 e-main-content 类
• 左侧和右侧侧边栏的切换
• 协调多个侧边栏的状态

内容集成

📄 阅读： references/content-integration.md

• 在侧边栏中集成 ListView 组件
• ListViewFieldSettings 配置
• 为分层菜单集成 TreeView
• 集成 Toolbar 组件
• 在 .NET 8 应用中集成 MainLayout

API 参考

📄 阅读： references/api-reference.md

• SfSidebar 组件的完整 API 文档
• 全部 22 个属性及其说明和可接受的值
• 方法及其返回类型
• 完整的事件系统（Changed、Created、Destroyed、IsOpenChanged、OnClose、OnOpen）
• 事件参数（ChangeEventArgs、EventArgs）
• SfSidebarContainer 文档
• 9 个以上包含代码的完整用法示例
• 属性用例及其实用实现

---

快速入门示例

@using Syncfusion.Blazor.Navigations
@using Syncfusion.Blazor.Buttons

<SfSidebar @ref="sidebarObj" Width="250px" @bind-IsOpen="SidebarToggle">
    <ChildContent>
        <div style="text-align: center; padding: 3rem;">
            <p>Sidebar Content</p>
            <SfButton @onclick="Close" CssClass="e-btn">Close</SfButton>
        </div>
    </ChildContent>
</SfSidebar>

<div style="padding: 3rem;">
    <div>Main Content</div>
    <SfButton @onclick="Toggle" IsToggle="true">Toggle Sidebar</SfButton>
</div>

@code {
    SfSidebar sidebarObj;
    public bool SidebarToggle = false;

    public void Toggle() => SidebarToggle = !SidebarToggle;
    public void Close() => SidebarToggle = false;
}

常见实现模式

模式 1：基本切换侧边栏

通过按钮点击使用 IsOpen 属性显示／隐藏侧边栏。

模式 2：响应式侧边栏

使用 MediaQuery 在移动设备上自动隐藏侧边栏，并在桌面设备上显示。

模式 3：停靠式导航

使用 EnableDock 和 DockSize 实现仅显示图标、悬停／点击时展开的导航。

模式 4：持久化状态

使用 EnablePersistence 和唯一的 ID，在页面导航期间记住侧边栏状态。

模式 5：Target 属性行为

• 隐式（默认）： 不设置 Target 属性 → 侧边栏会自动以紧邻其后的同级元素为目标
• 显式（高级）： Target=".selector" → 需要内部包装 <div> 才能实现 CSS 变换
• ✓ 大多数情况下使用隐式方式 | 仅在需要限定布局控制时使用显式方式
• 有关详细模式，请参阅状态持久化与 Target 上下文

模式 6：带菜单的侧边栏

结合 ListView 或 TreeView 实现结构化导航菜单。

模式 7：多个侧边栏

使用 Position 属性，让左右侧边栏分列主内容区域两侧。

---

后续步骤：

1. 选择平台：WebAssembly 或 .NET 8 Web 应用
2. 按照入门指南进行安装
3. 从上方导航指南中选择功能
4. 使用合适的样式实现侧边栏

有关详细示例和高级场景，请参阅各个参考文件。