鸿蒙 HarmonyOS - SideBarContainer 组件自学指南

news2025/6/2 4:34:37

在日常开发中，如果你有类似「左侧导航 + 右侧内容」的布局需求，比如后台管理界面、文件管理器、设置页等，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()`	内容区最小展示宽度