在多终端应用中，侧边栏（Sidebar）是常见的导航或功能区展现形式。ArkUI 的 SideBarContainer 组件，能够让你在室内设计模式（Embed）和覆盖模式（Overlay）之间轻松切换，并提供丰富的控制按钮定制能力。

---

一、组件简介

interface SideBarContainerInterface {
  (type?: SideBarContainerType): SideBarContainerAttribute;
}

• SideBarContainerType.Embed

  • 侧边栏始终与内容区并排显示，不会遮挡内容。

• SideBarContainerType.Overlay

  • 侧边栏浮于内容区之上，可通过按钮或滑动手势控制显示/隐藏。

容器内必须添加两个子组件：

1. 第一个子组件：侧边栏视图
2. 第二个子组件：主内容视图

---

二、快速上手

下面示例展示了一个浮层（Overlay）侧边栏，点击按钮即可切换显示状态。

@Entry @Component
struct MySidebarApp {
  @State showMenu: boolean = false;

  build() {
    SideBarContainer(SideBarContainerType.Overlay) {
      // ——— 侧边栏区域 ———
      Column() {
        Text("菜单")
          .fontSize(24)
          .textAlign(TextAlign.Center)
          .padding(20)
        Button("关闭")
          .onClick(() => this.showMenu = false)
      }
      .width(200)
      .backgroundColor("#f0f0f0")

      // ——— 主内容区域 ———
      Column({ space: 12 }) {
        Button(this.showMenu ? "隐藏侧边栏" : "显示侧边栏")
          .onClick(() => this.showMenu = !this.showMenu)

        Text("这是主内容区")
          .fontSize(18)
          .padding(10)
          .backgroundColor("#ffffff")
      }
      .backgroundColor("#e8e8e8")
    }
    .showSideBar(this.showMenu)
    .width("100%")
    .height("100%")
  }
}

• showSideBar(...)：绑定到 @State showMenu，实现在浮层模式下的展开/收起控制。

---

三、核心属性

属性	说明	示例值
showSideBar	布尔值，控制侧边栏显示/隐藏	true / false
controlButton	自定义控制按钮样式	ButtonStyle 对象
showControlButton	是否展示控制按钮	true / false
sideBarWidth	侧边栏宽度（px）	180
minSideBarWidth	侧边栏最小宽度	120
maxSideBarWidth	侧边栏最大宽度	300

ButtonStyle 结构

declare interface ButtonStyle {
  left?: number;   // 相对于容器左侧的偏移
  top?: number;    // 相对于容器顶部的偏移
  width?: number;
  height?: number;
  icons?: {
    shown: string;      // 展开图标
    hidden: string;     // 收起图标
    switching?: string; // 切换时过渡图标
  };
}

---

四、自定义控制按钮示例

在“嵌入模式”下，我们可以在侧边栏边缘放一个控制按钮，随时收起或弹出侧边栏：

@Entry @Component
struct EmbedSidebarDemo {
  @State menuVisible: boolean = true;

  build() {
    SideBarContainer(SideBarContainerType.Embed) {
      Column() {
        Text("主导航")
          .fontSize(20)
          .padding(16)
      }
      .width(240)
      .backgroundColor("#222")

      Column() {
        Text("应用内容")
          .fontSize(18)
          .padding(16)
      }
      .backgroundColor("#fff")
    }
    .showSideBar(this.menuVisible)
    .sideBarWidth(240)
    .controlButton({
      left: this.menuVisible ? 240 - 24 : 0,  // 当侧边栏收起时按钮贴左移入
      top: 16,
      width: 24,
      height: 24,
      icons: {
        shown: "icon_collapse",   // 假设已加载本地资源
        hidden: "icon_expand"
      }
    })
    .showControlButton(true)
    .onChange((visible) => {
      this.menuVisible = visible;
    })
    .width("100%")
    .height("100%");
  }
}

• 当侧边栏可见时，控制按钮位于侧边栏的右侧边缘；
• 收起后，按钮滑入内容区左侧，保持 24px 可点击区域。

---

五、事件回调

SideBarContainer(...)
  .onChange((visible: boolean) => {
    // visible = true：侧边栏展开
    // visible = false：侧边栏收起
    console.log("菜单当前状态：", visible);
  });

可用于同步外部数据、统计用户行为，或伴随动画效果执行额外逻辑。

---

六、实战建议

1. 模式选型

   • Embed：适合桌面端或平板，侧边栏占据永久空间；
   • Overlay：适合手机端，侧边栏可覆盖内容，不占用常驻布局空间。

2. 宽度管理

   • 选择合理的最小/最大宽度，防止内容过窄或占用过多屏幕。

3. 图标资源

   • 建议使用矢量或适应深色/浅色主题的图标，保证在不同背景下都清晰可见。

4. 可访问性

   • 控制按钮需留有足够的可点击面积（至少 44×44dp），并添加 aria-label 或无障碍描述。

---

小结

SideBarContainer 将侧边栏常见的“嵌入式”与“浮层式”场景封装得很轻量，通过一行类型切换、几行属性配置，即可实现从桌面级导航到移动端抽屉的多样侧边栏交互。掌握它，你的 ArkUI 项目就再也不怕菜单体量大、屏幕空间窄的尴尬了。