鸿蒙 HarmonyOS - SideBarContainer 组件自学指南

2025-05-30
北京
本文字数：2037 字
阅读完需：约 7 分钟

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

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

组件简介

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

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

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

支持三种布局类型：

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

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

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

@Entry@Componentstruct 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：根据整体宽度智能切换模式。

尺寸控制参数

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

控制按钮样式

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

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

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

分割线样式

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

常见问题说明

侧边栏高度怎么控制？

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

宽度设置无效？

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

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

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

总结建议

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

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

发布于: 刚刚阅读数: 2

原文链接:【http://xie.infoq.cn/article/7fcc0a91503aa9a8e7238ec2e】。文章转载请联系作者。

李游Leo

关注

全栈开发工程师、全栈讲师、华为HDE 2022-07-14 加入

原百度、时趣互动、乐视高级前端（软件）开发工程师。后在北京一所当地大学任教，主要职务是教学主任，也为网易云课堂微专业的前端课程负责人。

发布

暂无评论

创作场景