鸿蒙HarmonyOS - SideBarContainer 组件自学指南

简介: `SideBarContainer` 是 HarmonyOS 提供的双区域容器组件,适用于「左侧导航 + 右侧内容」布局,如后台管理界面、文件管理器等。它支持三种布局类型:Embed(并排)、Overlay(悬浮)和 Auto(自动切换),并提供折叠、拖拽、控制按钮等功能。本文通过示例代码详解其用法,包括子组件限制、显示模式控制、尺寸参数设置、控制按钮与分割线样式定制,以及常见问题解答。掌握该组件可高效构建复杂页面结构,推荐从 Embed 模式入手逐步进阶。

在日常开发中,如果你有类似「左侧导航 + 右侧内容」的布局需求,比如后台管理界面、文件管理器、设置页等,​​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 ? '显示' : '隐藏'))
    })
  }
}
AI 代码解读

aaaa-1.gif

核心知识点说明

子组件数量限制

  • 必须且只能两个子组件,否则布局会异常。
  • 一个子组件 → 只展示侧边栏。
  • 超过两个 → 只保留前两个。

显示模式控制

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

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

尺寸控制参数

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

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

控制按钮样式

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

  • ​shown​​:侧边栏展开时;
  • ​hidden​​:侧边栏隐藏时;
  • ​switching​​:切换中状态。

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

分割线样式

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


常见问题说明

  1. 侧边栏高度怎么控制?
  • 侧边栏会自动继承容器高度,建议不要直接设置 ​​height​​。
  1. 宽度设置无效?
  • 注意:不能直接对侧边栏子组件设置 ​​width​​​,请统一用 ​​.sideBarWidth()​​ 控制。
  1. 如何响应收起 / 展开状态变化?
  • 使用 ​​.onChange()​​ 监听器获取当前状态,可用于联动 UI 或输出日志。

总结建议

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

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

技术栈标签 HarmonyOS 语言
行业标签 工具效率
目录
相关文章
|
1月前
|
45.[HarmonyOS NEXT RelativeContainer案例二] 精确控制组件间距:外边距在相对布局中的高级应用
在HarmonyOS NEXT的UI开发中,组件之间的间距控制对于创建美观、易用的界面至关重要。RelativeContainer不仅提供了强大的锚点定位系统,还可以结合外边距(margin)属性实现更精细的布局控制。本教程将详细讲解如何在RelativeContainer中巧妙运用外边距,帮助你掌握这一实用技巧。
88 29
44.[HarmonyOS NEXT RelativeContainer案例一] 掌握组件锚点布局:打造灵活精准的UI定位系统
在HarmonyOS NEXT的UI开发中,精确控制组件位置是构建复杂界面的关键。RelativeContainer作为一种强大的布局容器,通过锚点系统提供了精确定位能力,使开发者能够创建出灵活且精准的UI布局。本教程将详细讲解如何使用RelativeContainer的锚点布局功能,帮助你掌握这一核心技术。
64 4
|
1月前
|
43.[HarmonyOS NEXT Row案例十一] 构建智能分页控件:Row组件实现页码与翻页按钮的完美结合
分页控件是数据展示类应用中不可或缺的导航元素,它允许用户在大量数据中进行有序浏览。本教程将详细讲解如何使用HarmonyOS NEXT的Row组件创建一个功能完善的分页控件,实现页码显示与前后翻页按钮的完美结合。 分页控件在各类应用场景中广泛应用,如电子商城的商品列表、新闻应用的文章列表、图库应用的图片浏览等。通过合理的设计和交互,可以提升用户的浏览体验和数据访问效率。
67 3
37.[HarmonyOS NEXT Row案例五] 构建智能聊天气泡:Row组件的reverse属性妙用
在即时通讯应用中,聊天气泡是一个核心UI元素,它需要能够区分发送方和接收方的消息,并以不同的样式和位置显示。本教程将详细讲解如何使用HarmonyOS NEXT的Row组件创建反向排列的消息气泡,重点介绍reverse属性的巧妙应用,帮助开发者构建出专业、美观的聊天界面。
59 3
19.[HarmonyOS NEXT Column案例二(下)] 时间线组件的详细实现与样式定制
在上一篇教程中,我们介绍了Column组件的reverse属性及其在时间线应用中的基本用法。本篇将深入探讨时间线中各个子组件的实现细节,包括ForEach循环渲染、Row布局、Text组件的样式设置,以及如何通过这些组件构建一个完整的时间线界面。
64 2
17.[HarmonyOS NEXT Column案例一(下)] 表单组件的详细实现与样式定制
在上一篇教程中,我们介绍了Column组件的基本概念和参数设置。本篇将深入探讨登录表单中各个子组件的实现细节,包括Text、TextInput和Button组件的属性设置和样式定制,以及如何将这些组件组合成一个完整的登录表单界面。
59 4
16.[HarmonyOS NEXT Column案例一(上)] 使用Column组件构建垂直表单布局的基础指南
在HarmonyOS NEXT应用开发中,布局是构建用户界面的基础。本教程将详细讲解如何使用Column组件创建垂直排列的表单布局,通过一个登录表单的实例,展示Column组件的基本用法、间距控制和对齐方式等核心知识点。
64 4
06.HarmonyOS Next UI进阶:Text组件与视觉样式完全指南
在HarmonyOS Next应用开发中,Text组件是最基础也是最常用的UI元素之一。它不仅用于显示文本内容,还可以通过丰富的样式属性实现各种视觉效果。掌握Text组件的样式设置,是构建精美UI界面的基础技能。
100 1
|
1月前
|
HarmonyOS Next快速入门:Button组件
本教程摘自《HarmonyOS Next快速入门》,聚焦HarmonyOS应用开发中的Button组件。Button支持胶囊、圆形和普通三种类型,可通过子组件实现复杂功能,如嵌入图片或文字。支持自定义样式(边框弧度、文本样式、背景色等)及点击事件处理。示例代码展示了不同类型按钮的创建与交互逻辑,助开发者快速上手。适合HarmonyOS初学者及对UI组件感兴趣的开发者学习。
90 0
|
1月前
|
HarmonyOS Next快速入门:Image组件
本教程摘自《HarmonyOS Next快速入门》,专注于HarmonyOS应用开发中的Image组件使用。Image组件支持多种图片格式(如png、jpg、svg等),可渲染本地资源、网络图片、媒体库文件及PixelMap像素图。通过设置`objectFit`属性,实现不同缩放类型;利用`fillColor`属性调整矢量图颜色。示例代码涵盖本地、网络及资源图片的加载与样式设置,同时需在`module.json5`中声明网络权限以加载外部资源。适合开发者快速掌握HarmonyOS图像展示功能。
111 0