【鸿蒙next开发】ArkUI框架：ArkTS组件-SideBarContainer

于 2025-05-19 14:04:59 发布
阅读量976 收藏 20
点赞数 24
分类专栏： ArkTS组件 鸿蒙5.0开发 ArkUI框架 文章标签： harmonyos 华为 ArkTS ArkUI android 鸿蒙系统 前端
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/m0_73088370/article/details/148062183
版权

 往期鸿蒙5.0全套实战文章必看：（文中附带鸿蒙5.0全栈学习资料）

SideBarContainer

提供侧边栏可以显示和隐藏的侧边栏容器，通过子组件定义侧边栏和内容区，第一个子组件表示侧边栏，第二个子组件表示内容区。

说明

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

可以包含子组件。

说明

  • 子组件类型：系统组件和自定义组件，不支持渲染控制类型（if/else、ForEach和LazyForEach）。
  • 子组件个数：必须且仅包含2个子组件。
  • 子组件个数异常时：3个或以上子组件，显示第一个和第二个。1个子组件，显示侧边栏，内容区为空白。

接口

SideBarContainer( type?: SideBarContainerType )

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
typeSideBarContainerType否

设置侧边栏的显示类型。

默认值：SideBarContainerType.Embed

SideBarContainerType枚举说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称描述
Embed

侧边栏嵌入到组件内，和内容区并列显示。

组件尺寸小于minContentWidth + minSideBarWidth,并且未设置showSideBar时，侧边栏自动隐藏。

未设置minSideBarWidth或者minContentWidth采用未设置接口的默认值进行计算。

组件在自动隐藏后，如果通过点击控制按钮唤出侧边栏，则侧边栏悬浮在内容区上显示。

Overlay侧边栏浮在内容区上面。
AUTO10+

组件尺寸大于等于minSideBarWidth+minContentWidth时，采用Embed模式显示。

组件尺寸小于minSideBarWidth+minContentWidth时，采用Overlay模式显示。

未设置minSideBarWidth或minContentWidth时，会使用未设置接口的默认值进行计算，若计算的值小于600vp，则使用600vp做为模式切换的断点值。

属性

除支持通用属性外，还支持以下属性：

showSideBar

showSideBar(value: boolean)

设置是否显示侧边栏。

从API version 10开始，该属性支持$$双向绑定变量。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueboolean是

是否显示侧边栏。

true：显示侧边栏

false：不显示侧边栏

默认值：true

controlButton

controlButton(value: ButtonStyle)

设置侧边栏控制按钮的属性。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueButtonStyle是侧边栏控制按钮的属性。

showControlButton

showControlButton(value: boolean)

设置是否显示控制按钮。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueboolean是

是否显示控制按钮。

true：显示控制按钮

false：不显示控制按钮

默认值：true

sideBarWidth

sideBarWidth(value: number)

设置侧边栏的宽度。设置为小于0的值时按默认值显示。受最小宽度和最大宽度限制，不在限制区域内取最近的点。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valuenumber是

侧边栏的宽度。

默认值：240vp

单位：vp

说明：

API version 9及以下版本默认值为200vp，API version 10的默认值为240vp。

sideBarWidth9+

sideBarWidth(value: Length)

设置侧边栏的宽度。设置为小于0的值时按默认值显示。受最小宽度和最大宽度限制，不在限制区域内取最近的点。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueLength是

侧边栏的宽度。

默认值：240vp

单位：vp

说明：

API version 9的默认值为200vp，API version 10的默认值为240vp。

minSideBarWidth

minSideBarWidth(value: number)

设置侧边栏最小宽度。设置为小于0的值时按默认值显示。值不能超过侧边栏容器本身宽度，超过使用侧边栏容器本身宽度。

minSideBarWidth优先于侧边栏子组件minWidth，minSideBarWidth未设置时默认值优先级高于侧边栏子组件minWidth。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valuenumber是

侧边栏最小宽度。

默认值：API version 9及以下版本默认值为200vp，API version 10的默认值为240vp。

minSideBarWidth9+

minSideBarWidth(value: Length)

设置侧边栏最小宽度。设置为小于0的值时按默认值显示。值不能超过侧边栏容器本身宽度，超过使用侧边栏容器本身宽度。

minSideBarWidth优先于侧边栏子组件minWidth，minSideBarWidth未设置时默认值优先级高于侧边栏子组件minWidth。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueLength是

侧边栏最小宽度。

默认值：API version 9及以下版本默认值为200vp，API version 10的默认值为240vp。

maxSideBarWidth

maxSideBarWidth(value: number)

设置侧边栏最大宽度。设置为小于0的值时按默认值显示。值不能超过侧边栏容器本身宽度，超过使用侧边栏容器本身宽度。

maxSideBarWidth优先于侧边栏子组件maxWidth，maxSideBarWidth未设置时默认值优先级高于侧边栏子组件maxWidth。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valuenumber是

设置侧边栏最大宽度。

默认值：280vp

单位：vp

maxSideBarWidth9+

maxSideBarWidth(value: Length)

设置侧边栏最大宽度。设置为小于0的值时按默认值显示。值不能超过侧边栏容器本身宽度，超过使用侧边栏容器本身宽度。

maxSideBarWidth优先于侧边栏子组件maxWidth，maxSideBarWidth未设置时默认值优先级高于侧边栏子组件maxWidth。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueLength是

设置侧边栏最大宽度。

默认值：280vp

单位：vp

autoHide9+

autoHide(value: boolean)

设置当侧边栏拖拽到小于最小宽度后，是否自动隐藏。受minSideBarWidth属性方法影响，minSideBarWidth属性方法未设置值使用默认值。

拖拽过程中判断是否要自动隐藏。小于最小宽度时需要阻尼效果触发隐藏（越界一段距离）。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueboolean是

侧边栏拖拽到小于最小宽度后，是否自动隐藏。

true：会自动隐藏

false：不会自动隐藏

默认值：true

sideBarPosition9+

sideBarPosition(value: SideBarPosition)

设置侧边栏显示位置。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueSideBarPosition是

侧边栏显示位置。

默认值：SideBarPosition.Start

divider10+

divider(value: DividerStyle | null)

设置分割线的样式。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueDividerStyle | null是

分割线的样式。

默认为DividerStyle：显示分割线。

- null或undefined：行为不做处理，分割线样式与默认值保持一致。

说明：

API version 11及以下版本，null效果为不显示分割线。

minContentWidth10+

minContentWidth(value: Dimension)

设置SideBarContainer组件内容区可显示的最小宽度。

设置为小于0，内容区显示的最小宽度为360vp，未设置该属性时，组件内容区的可缩小到0。

Embed场景下，增大组件尺寸时仅增大内容区的尺寸。

缩小组件尺寸时，先缩小内容区的尺寸至minContentWidth。继续缩小组件尺寸时，保持内容区宽度minContentWidth不变，优先缩小侧边栏的尺寸。

当缩小侧边栏的尺寸至minSideBarWidth后，继续缩小组件尺寸时，

  • 如果autoHide属性为false，则会保持侧边栏宽度minSideBarWidth和内容区宽度minContentWidth不变，但内容区会被截断显示；
  • 如果autoHide属性为true，则会优先隐藏侧边栏，然后继续缩小至内容区宽度minContentWidth后，内容区宽度保持不变，但内容区会被截断显示。

minContentWidth优先于侧边栏的maxSideBarWidth与sideBarWidth属性，minContentWidth未设置时默认值优先级低于设置的minSideBarWidth与maxSideBarWidth属性。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueDimension是

SideBarContainer组件内容区可显示的最小宽度。

默认值：360vp

单位：vp

ButtonStyle对象说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
leftnumber否

设置侧边栏控制按钮距离容器左界限的间距。

默认值：16vp

单位：vp

topnumber否

设置侧边栏控制按钮距离容器上界限的间距。

默认值：48vp

单位：vp

widthnumber否

设置侧边栏控制按钮的宽度。

默认值：

API version 9及之前版本：32vp

从API version 10开始：24vp

单位：vp

heightnumber否

设置侧边栏控制按钮的高度。

默认值：

API version 9及之前版本：32vp

从API version 10开始：24vp

单位：vp

icons

{

shown: string | PixelMap | Resource ;

hidden: string | PixelMap | Resource ;

switching?: string | PixelMap | Resource

}

否

设置侧边栏控制按钮的图标：

- shown: 设置侧边栏显示时控制按钮的图标。

说明：

资源获取错误时，使用默认图标。

- hidden: 设置侧边栏隐藏时控制按钮的图标。

- switching:设置侧边栏显示和隐藏状态切换时控制按钮的图标。

SideBarPosition9+枚举说明

侧边栏显示位置。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称描述
Start侧边栏位于容器左侧。
End侧边栏位于容器右侧。

DividerStyle10+对象说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
strokeWidthLength是

分割线的线宽。

默认值：1vp

colorResourceColor否

分割线的颜色。

默认值：#000000，3%

startMarginLength否

分割线与侧边栏顶端的距离。

默认值：0

endMarginLength否

分割线与侧边栏底端的距离。

默认值：0

说明

针对侧边栏子组件设置通用属性宽高时，宽高都不生效。

针对侧边栏内容区设置通用属性宽高时，宽高都不生效，默认占满SideBarContainer的剩余空间。

当showSideBar属性未设置时，依据组件大小进行自动显示：

  • 小于minSideBarWidth + minContentWidth：默认不显示侧边栏。
  • 大于等于minSideBarWidth + minContentWidth：默认显示侧边栏。

事件

除支持通用事件外，还支持以下事件：

onChange

onChange(callback: (value: boolean) => void)

当侧边栏的状态在显示和隐藏之间切换时触发回调。

触发该事件的条件：

1、showSideBar属性值变换时；

2、showSideBar属性自适应行为变化时；

3、分割线拖拽触发autoHide时。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valueboolean是true表示显示，false表示隐藏。

示例

该示例主要演示如何使用侧边栏组件及页面布局效果。

// xxx.ets
@Entry
@Component
struct SideBarContainerExample {
  normalIcon: Resource = $r("app.media.icon")
  selectedIcon: Resource = $r("app.media.icon")
  @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(64).height(64)
            Text("Index0" + item)
              .fontSize(25)
              .fontColor(this.current === item ? '#0A59F7' : '#999')
              .fontFamily('source-sans-pro,cursive,sans-serif')
          }
          .onClick(() => {
            this.current = item
          })
        }, (item: string) => item)
      }.width('100%')
      .justifyContent(FlexAlign.SpaceEvenly)
      .backgroundColor('#19000000')


      Column() {
        Text('SideBarContainer content text1').fontSize(25)
        Text('SideBarContainer content text2').fontSize(25)
      }
      .margin({ top: 50, left: 20, right: 30 })
    }
    .controlButton({
      icons: {
        hidden: $r('app.media.drawer'),
        shown: $r('app.media.drawer'),
        switching: $r('app.media.drawer')
      }
    })
    .sideBarWidth(150)
    .minSideBarWidth(50)
    .maxSideBarWidth(300)
    .minContentWidth(0)
    .onChange((value: boolean) => {
      console.info('status:' + value)
    })
    .divider({ strokeWidth: '1vp', color: Color.Gray, startMargin: '4vp', endMargin: '4vp' })
  }
}

鸿蒙Harmony应用开发—ArkTS声明式开发（容器组件：SideBarContainer）
m0_64420071的博客
03-16 1271
ArkTS声明式开发（容器组件：SideBarContainer）
HarmonyOS应用开发：SideBarContainer（容器组件）
situnanQAQ的博客
06-19 1020
提供侧边栏可以显示和隐藏的侧边栏容器，通过子组件定义侧边栏和内容区，第一个子组件表示侧边栏，第二个子组件表示内容区。
HarmonyOS ArkUI容器类组件-侧边栏容器（SideBarContainer）
m0_71263309的博客
04-22 885
(type?type：设置侧边栏的显示类型，定义了一下 2 中类型：Embed：侧边栏嵌入到组件内，侧边栏和内容区并列显示。Overlay：侧边栏浮在内容区上面。build() {Column() {Text("侧边栏区域").width(10)Column() {Text("侧边栏区域")left?: number;top?: number;width?: number;height?: number;icons?
鸿蒙5.0版开发：ArkTS容器组件（SideBarContainer）
m0_69424697的博客
09-27 870
提供侧边栏可以显示和隐藏的侧边栏容器......
鸿蒙（HarmonyOS）项目方舟框架（ArkUI）之SideBarContainer容器组件
zy0412326的专栏
03-11 1502
鸿蒙（HarmonyOS）项目方舟框架（ArkUI）之SideBarContainer容器组件。
鸿蒙5.0版开发：ArkTS组件-SideBarContainer
m0_69424697的博客
11-04 900
提供侧边栏可以显示和隐藏的侧边栏容器..........
鸿蒙5.0开发进阶：API ArkUI框架-ArkTS组件（自定义绘制设置）
Androidbye的博客
12-27 916
当某些组件本身的绘制内容不满足需求时...........
鸿蒙5.0开发进阶：UI框架-ArkTS组件（TreeView）
Androidbye的博客
01-21 895
树视图作为一种分层显示的列表，适合显示嵌套结构。
鸿蒙(ArkTS)—ArkUI布局开发常见问题
m0_70749039的博客
05-28 2084
容器组件在使用position之后会脱离文本流，导致容器脱离外层容器束缚，导致height不生效，可以将外层容器换成Stack可以解决这个问题。
HarmonyOS NEXT实战开发：焦点事件
hanyanyou的博客
07-29 946
基础概念与规范.............
HarmonyOS Next应用开发——抽屉布局SideBarContainer
高心星的专栏
10-09 1717
提供侧边栏可以显示和隐藏的侧边栏容器，通过子组件定义侧边栏和内容区，第一个子组件表示侧边栏，第二个子组件表示内容区。 并且侧边栏可以出现在左侧也可以出现在右侧，侧边栏可以并列跟内容区一起展示，也可以浮动在内容区展示。
openharmony容器组件之SideBarContainer
lplj717的博客
08-10 743
SideBarContainer：提供侧边栏可以显示和隐藏的侧边栏容器，通过子组件定义侧边栏和内容区，第一个子组件表示侧边栏，第二个子组件表示内容区
鸿蒙HarmonyOS 5.0开发实战：使用SideBarContainer侧边栏淡入淡出动效实现案例
最新发布
m0_73088370的博客
02-21 485
本例主要介绍了如何基于显式动画实现侧边栏的淡入淡出动效。
OpenHarmony实战开发-SideBarContainer侧边栏淡入淡出动效实现案例。
m0_70749039的博客
04-17 492
在2in1或平板上，群聊侧边栏是一种较为常用的功能，虽然HarmonyOS已经具备了基本的动效，但是部分情况下开发者可能有定制侧边栏动效的需求，本例主要介绍了如何基于显式动画实现侧边栏的淡入淡出动效。
【HarmonyOS开发】ArkTs实现侧栏联动
qq_23334071的博客
12-19 1358
侧栏联动功能模块：1、切换左侧导航，右侧滚动到对应的内容。2、滚动右侧的内容，左侧会切换对应的导航。
HarmonyOS NEXT应用开发之SideBarContainer侧边栏淡入淡出动效实现案例
maniuT的博客
03-18 1064
在2in1或平板上，群聊侧边栏是一种较为常用的功能，虽然HarmonyOS已经具备了基本的动效，但是部分情况下开发者可能有定制侧边栏动效的需求，本例主要介绍了如何基于显式动画实现侧边栏的淡入淡出动效。
【鸿蒙开发】第十六章 ArkTS基础类库-容器（数据结构）
Yvan
03-03 2115
容器类库：用于存储各种数据类型的元素，并具备一系列处理数据元素的方法，作为纯数据结构容器来使用具有一定的优势。容器类采用了类似静态语言的方式来实现，并通过对存储位置以及属性的限制，让每种类型的数据都能在完成自身功能的基础上去除冗余逻辑，保证了数据的高效访问，提升了应用的性能。当前提供了线性和非线性两类容器，共14种。每种容器都有自身的特性及使用场景，详情请参见线性容器和非线性容器。
鸿蒙ArkUI声明式学习：【UI资源管理】
鸿蒙的技术博客
04-08 1546
OpenHarmony 应用的资源分类和资源的访问以及应用开发使用的像素单位以及各单位之间相互转换的方法。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值