鸿蒙HarmonyOS - SideBarContainer 组件自学指南

在日常开发中，如果你有类似「左侧导航 + 右侧内容」的布局需求，比如后台管理界面、文件管理器、设置页等，​`​SideBarContainer​`​ 是非常值得掌握的组件。它自带侧边栏和主内容区的分离机制，还支持折叠、拖拽、控制按钮和多种显示模式，是构建复杂页面结构的好帮手。

这篇文章将从实际开发视角出发，用一段简化的示例代码，带你快速掌握 ​`​SideBarContainer​`​ 的使用方法，并逐步解析核心属性与交互行为。

***

## 组件简介

​`​SideBarContainer​`​ 是 HarmonyOS 提供的一个双区域容器，固定由两个子组件组成：

*   第一个子组件表示侧边栏；
*   第二个子组件表示主内容区。

组件内部已实现侧边栏的显示与隐藏逻辑，开发者只需关注如何传入正确结构和控制显示行为即可。

支持三种布局类型：

*   ​`​Embed​`​：并排展示；
*   ​`​Overlay​`​：侧边栏悬浮；
*   ​`​Auto​`​：根据容器宽度自动选择 Embed 或 Overlay。

***

## 示例场景：基本侧边栏菜单布局

下面是一个常见的布局案例：左边是图标 + 文本菜单项，右边是内容展示区。

    @Entry
    @Component
    struct SideBarContainerExample {
      normalIcon: Resource = $r("app.media.startIcon")
      selectedIcon: Resource = $r("app.media.startIcon")
      @State arr: number[] = [1, 2, 3]
      @State current: number = 1

      build() {
        SideBarContainer(SideBarContainerType.Embed) {
          // 左侧导航栏
          Column() {
            ForEach(this.arr, (item: number) => {
              Column({ space: 5 }) {
                Image(this.current === item ? this.selectedIcon : this.normalIcon)
                  .width(48)
                  .height(48)
                Text("菜单 " + item)
                  .fontSize(20)
                  .fontColor(this.current === item ? '#0A59F7' : '#777')
                  .fontFamily('HarmonyOS Sans')
              }
              .onClick(() => {
                this.current = item
              })
            }, (item: number) => item.toString())
          }
          .width('100%')
          .justifyContent(FlexAlign.Center)
          .alignItems(HorizontalAlign.Center)
          .backgroundColor('#F3F3F3')

          // 右侧主内容区
          Column() {
            Text(`当前内容：菜单 ${this.current}`).fontSize(24).fontWeight(FontWeight.Medium)
            Text('这是侧边栏对应的内容区，可根据选择进行切换')
              .fontSize(18)
              .margin({ top: 10 })
          }
          .padding({ top: 50, left: 20, right: 20 })
        }
        .controlButton({
          left: 12,
          top: 40,
          width: 28,
          height: 28,
          icons: {
            hidden: $r('app.media.startIcon'),
            shown: $r('app.media.startIcon'),
            switching: $r('app.media.startIcon')
          }
        })
        .sideBarWidth(180)
        .minSideBarWidth(60)
        .maxSideBarWidth(280)
        .minContentWidth(300)
        .divider({
          strokeWidth: '2vp',
          color: '#CCCCCC',
          startMargin: '6vp',
          endMargin: '6vp'
        })
        .onChange((visible: boolean) => {
          console.info('侧边栏当前状态：' + (visible ? '显示' : '隐藏'))
        })
      }
    }


## 核心知识点说明

### 子组件数量限制

*   **必须且只能两个子组件**，否则布局会异常。

<!---->

*   一个子组件 → 只展示侧边栏。
*   超过两个 → 只保留前两个。

### 显示模式控制

通过构造函数传入 ​`​SideBarContainerType​`​ 类型参数控制显示样式，推荐用法：

*   ​`​.Embed​`​：固定并排展示；
*   ​`​.Overlay​`​：悬浮在内容上；
*   ​`​.Auto​`​：根据整体宽度智能切换模式。

### 尺寸控制参数

| 方法名                      | 说明        |
| ------------------------ | --------- |
| ​`​.sideBarWidth()​`​    | 默认宽度      |
| ​`​.minSideBarWidth()​`​ | 拖拽最小宽度    |
| ​`​.maxSideBarWidth()​`​ | 拖拽最大宽度    |
| ​`​.minContentWidth()​`​ | 内容区最小展示宽度 |

尺寸单位通常用 ​`​vp​`​​，支持直接传入数字，也支持百分比和 ​`​Length​`​ 类型。

### 控制按钮样式

通过 ​`​.controlButton({...})​`​ 方法自定义控制按钮的大小、位置与图标，图标支持：

*   ​`​shown​`​：侧边栏展开时；
*   ​`​hidden​`​：侧边栏隐藏时；
*   ​`​switching​`​：切换中状态。

图标资源建议使用 PixelMap 或 ​`​$r()​`​ 形式引用本地媒体资源。

### 分割线样式

通过 ​`​.divider({...})​`​ 方法自定义侧边栏和内容区中间的分隔线，支持设置线宽、颜色、边距等。

***

## 常见问题说明

1.  **侧边栏高度怎么控制？**

*   侧边栏会自动继承容器高度，建议不要直接设置 ​`​height​`​。

2.  **宽度设置无效？**

*   注意：不能直接对侧边栏子组件设置 ​`​width​`​​，请统一用 ​`​.sideBarWidth()​`​ 控制。

3.  **如何响应收起 / 展开状态变化？**

*   使用 ​`​.onChange()​`​ 监听器获取当前状态，可用于联动 UI 或输出日志。

***

## 总结建议

​`​SideBarContainer​`​ 是构建复杂结构页面时非常实用的组件，重点在于理解它对子组件数量的限制、布局样式的选择逻辑、以及各类尺寸控制参数。实际使用中，可以与页面状态管理、资源图标切换等逻辑配合，构建出灵活可交互的侧边栏体验。

建议从 Embed 模式开始练习，等熟悉后再尝试 Overlay 或 Auto 模式的布局响应性处理。