1. 概述与场景

在桌面端和大屏应用中，侧边栏（Sidebar）通常用来承载导航、工具面板或目录树。ArkUI 提供了 SideBarContainer 组件，让你可以在：

• 嵌入模式（Embed）：侧边栏与主区域并排展示；
• 浮层模式（Overlay）：侧边栏在主区域之上滑出覆盖；

两种模式间自由切换，并可用按钮或手势控制展开与收起。

2. 快速上手

下面示例演示如何在“浮层模式”下，通过 @State 维护展开状态、并绑定到容器的 showSideBar 属性：

@Entry @Component
struct OverlaySidebarDemo {
  @State menuVisible: boolean = false;

  build() {
    SideBarContainer(SideBarContainerType.Overlay) {
      // —— 侧边栏面板 ——  
      Column({ space: 12, alignItems: HorizontalAlign.Center }) {
        Text("📑 菜单面板")
          .fontSize(24)
          .padding(16);
        Button(menuVisible ? "收起" : "展开")
          .onClick(() => this.menuVisible = !this.menuVisible);
      }
      .width(180)
      .backgroundColor("#EFEFEF")

      // —— 主内容区 ——  
      Column({ space: 12, alignItems: HorizontalAlign.Center }) {
        Text("👋 欢迎来到主内容区")
          .fontSize(20)
          .padding(16)
          .backgroundColor("#FFFFFF");
      }
      .backgroundColor("#FAFAFA")
    }
    // 绑定展开状态、全屏铺满
    .showSideBar(this.menuVisible)
    .width("100%")
    .height("100%");
  }
}

• SideBarContainerType.Overlay：浮层模式；
• .showSideBar(this.menuVisible)：跟随 @State 动态控制；
• 第一个子组件定义侧边栏，第二个子组件定义主区域。

3. 嵌入式侧边栏

在平板或桌面端，通常希望侧边栏常驻，并排展示。只需改成 Embed 模式，并加入控制按钮：

@Entry @Component
struct EmbedSidebarDemo {
  @State collapsed: boolean = false;

  build() {
    SideBarContainer(SideBarContainerType.Embed) {
      // — 永久侧边栏 —
      Column({ alignItems: HorizontalAlign.Center, space: 8 }) {
        Text("导航栏").fontSize(18).padding(12);
        Button(collapsed ? "▶" : "◀")
          .onClick(() => this.collapsed = !this.collapsed);
      }
      // 当收起时仅保留 48px 宽
      .width(this.collapsed ? 48 : 200)
      .backgroundColor("#333")

      // — 主内容 —
      Column({ alignItems: HorizontalAlign.Center }) {
        Text("主内容显示区")
          .fontSize(20)
          .padding(16);
      }
      .backgroundColor("#FFF")
    }
    .showSideBar(!this.collapsed)
    // 调整侧边栏宽度上下限，并启用控制按钮
    .sideBarWidth(200)
    .minSideBarWidth(48)
    .maxSideBarWidth(240)
    .showControlButton(true)
    .controlButton({
      left: this.collapsed ? 0 : 200 - 24,  // 保持按钮贴合侧边栏边缘
      top: 16,
      width: 24,
      height: 24,
      icons: {
        shown: "icon_arrow_left",
        hidden: "icon_arrow_right"
      }
    })
    .width("100%")
    .height("100%");
  }
}

• .showControlButton(true)：显隐控制按钮；
• .controlButton({...})：自定义按钮位置与图标。

4. 属性速览

5. 切换回调

监听用户展开或收起侧边栏，并在回调中做日志或业务联动：

SideBarContainer(...)
  .onChange((visible) => {
    console.log("侧边栏当前状态：", visible ? "已展开" : "已收起");
  });

6. 小贴士

1. 模式选择

   • 手机端推荐 Overlay，以节省内容区空间；
   • 大屏/平板可选 Embed，提升导航效率。

2. 按钮友好度

   • 保证按钮至少 44×44dp 点击区域；
   • 图标需适配深浅背景，自带可访问描述。

3. 宽度配置

   • 合理设置最小与最大宽度，避免出现“侧边栏过窄看不清”或“过宽挤压内容”。

4. 动画体验

   • onChange 回调中，可同步 Animation 做侧边栏滑动过渡，提升交互质感。

掌握以上用法后，无论是抽屉式导航，还是常驻式菜单，都能用一句组件调用、一两行配置轻松搞定。开始你的 ArkUI 侧边栏之旅吧！