1# SideBarContainer 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @mayaolll--> 5<!--Designer: @jiangdayuan--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9提供侧边栏可以显示和隐藏的侧边栏容器，通过子组件定义侧边栏和内容区，第一个子组件表示侧边栏，第二个子组件表示内容区。 10 11> **说明：** 12> 13> 该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15 16## 子组件 17 18可以包含子组件。 19 20> **说明：** 21> 22> - 子组件类型：系统组件和自定义组件，不支持渲染控制类型（[if/else](../../../ui/state-management/arkts-rendering-control-ifelse.md)、[ForEach](../../../ui/state-management/arkts-rendering-control-foreach.md)和[LazyForEach](../../../ui/state-management/arkts-rendering-control-lazyforeach.md)）。 23> - 子组件个数：必须且仅包含2个子组件。 24> - 子组件个数异常时：3个或以上子组件，显示第一个和第二个。1个子组件，显示侧边栏，内容区为空白。 25> - SideBarContainer走焦时，先在内容区走焦，再在侧边栏走焦。 26 27## 接口 28 29SideBarContainer( type?: SideBarContainerType ) 30 31创建侧边栏容器。 32 33**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 34 35**系统能力：** SystemCapability.ArkUI.ArkUI.Full 36 37**参数：** 38 39| 参数名 | 类型 | 必填 | 说明 | 40| -------- | -------- | -------- | -------- | 41| type | [SideBarContainerType](#sidebarcontainertype枚举说明) | 否 | 设置侧边栏的显示类型。<br/>默认值：SideBarContainerType.Embed | 42 43## SideBarContainerType枚举说明 44 45容器内侧边栏样式枚举。 46 47**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 48 49**系统能力：** SystemCapability.ArkUI.ArkUI.Full 50 51| 名称 | 说明 | 52| -------- | -------- | 53| Embed | 侧边栏嵌入到组件内，和内容区并列显示。<br/>整体容器大小不变时，显示侧边栏会导致内容区缩小，隐藏侧边栏会扩大内容区。<br/>组件尺寸小于minContentWidth + minSideBarWidth，并且未设置showSideBar时，侧边栏自动隐藏。<br/>未设置minSideBarWidth或者minContentWidth采用未设置接口的默认值进行计算。<br/> 组件在自动隐藏后，如果通过点击控制按钮唤出侧边栏，则侧边栏悬浮在内容区上显示。| 54| Overlay | 侧边栏浮在内容区上面，不会影响内容区的大小。 | 55| AUTO<sup>10+</sup> | 组件尺寸大于等于minSideBarWidth+minContentWidth时，采用Embed模式显示。<br/>组件尺寸小于minSideBarWidth+minContentWidth时，采用Overlay模式显示。<br/>未设置minSideBarWidth或minContentWidth时，会使用未设置接口的默认值进行计算，若计算的值小于600vp，则使用600vp做为模式切换的断点值。| 56 57## 属性 58 59除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 60 61### showSideBar 62 63showSideBar(value: boolean) 64 65设置是否显示侧边栏。 66 67从API version 10开始，该属性支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。 68 69**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 70 71**系统能力：** SystemCapability.ArkUI.ArkUI.Full 72 73**参数：** 74 75| 参数名 | 类型 | 必填 | 说明 | 76| ------ | ------- | ---- | ------------------------------------------------------------ | 77| value | boolean | 是 | 是否显示侧边栏。<br/>true：显示侧边栏<br/>false：不显示侧边栏<br/>默认值：true | 78 79### controlButton 80 81controlButton(value: ButtonStyle) 82 83设置侧边栏控制按钮的属性。 84 85**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 86 87**系统能力：** SystemCapability.ArkUI.ArkUI.Full 88 89**参数：** 90 91| 参数名 | 类型 | 必填 | 说明 | 92| ------ | ----------------------------------- | ---- | ---------------------- | 93| value | [ButtonStyle](#buttonstyle对象说明) | 是 | 侧边栏控制按钮的属性。 | 94 95### showControlButton 96 97showControlButton(value: boolean) 98 99设置是否显示控制按钮。 100 101**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 102 103**系统能力：** SystemCapability.ArkUI.ArkUI.Full 104 105**参数：** 106 107| 参数名 | 类型 | 必填 | 说明 | 108| ------ | ------- | ---- | ------------------------------------------------------------ | 109| value | boolean | 是 | 是否显示控制按钮。<br/>true：显示控制按钮<br/>false：不显示控制按钮<br/>默认值：true | 110 111> **说明：** 112> 113> 通过控制按钮切换侧边栏的显隐会触发侧边栏的显示/隐藏动画。 114 115### sideBarWidth 116 117sideBarWidth(value: number) 118 119设置侧边栏的宽度。设置为小于0的值时按默认值显示。受最小宽度和最大宽度限制，不在限制区域内取最近的点。 120 121从API version 18开始，该参数支持[!!](../../../ui/state-management/arkts-new-binding.md)双向绑定变量。 122 123**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 124 125**系统能力：** SystemCapability.ArkUI.ArkUI.Full 126 127**参数：** 128 129| 参数名 | 类型 | 必填 | 说明 | 130| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 131| value | number | 是 | 侧边栏的宽度。<br/>默认值：240vp<br/>单位：vp<br/>取值范围：[0, +∞)<br/>**说明：** <br/>API version 9及以下版本默认值为200vp，API version 10的默认值为240vp。 | 132 133### sideBarWidth<sup>9+</sup> 134 135sideBarWidth(value: Length) 136 137设置侧边栏的宽度。设置为小于0的值时按默认值显示。受最小宽度和最大宽度限制，不在限制区域内取最近的点。与[sideBarWidth](#sidebarwidth)相比，value参数新增了对百分比字符串和其他[像素单位](ts-pixel-units.md)的支持。 138 139从API version 18开始，该参数支持[!!](../../../ui/state-management/arkts-new-binding.md)双向绑定变量。 140 141**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 142 143**系统能力：** SystemCapability.ArkUI.ArkUI.Full 144 145**参数：** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 149| value | [Length](ts-types.md#length) | 是 | 侧边栏的宽度。<br/>默认值：240vp<br/>单位：vp<br/>取值范围：[0, +∞)<br/>**说明：** <br/>API version 9的默认值为200vp，API version 10的默认值为240vp。 | 150 151### minSideBarWidth 152 153minSideBarWidth(value: number) 154 155设置侧边栏最小宽度。设置为小于0的值时按默认值显示。值不能超过侧边栏容器本身宽度，超过使用侧边栏容器本身宽度。 156 157minSideBarWidth优先于侧边栏子组件minWidth，minSideBarWidth未设置时默认值优先级高于侧边栏子组件minWidth。 158 159**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 160 161**系统能力：** SystemCapability.ArkUI.ArkUI.Full 162 163**参数：** 164 165| 参数名 | 类型 | 必填 | 说明 | 166| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 167| value | number | 是 | 侧边栏最小宽度。<br/>默认值：API version 9及以下版本默认值为200vp，API version 10的默认值为240vp。<br/>取值范围：[0, +∞) | 168 169### minSideBarWidth<sup>9+</sup> 170 171minSideBarWidth(value: Length) 172 173设置侧边栏最小宽度。设置为小于0的值时按默认值显示。值不能超过侧边栏容器本身宽度，超过使用侧边栏容器本身宽度。与[minSideBarWidth](#minsidebarwidth)相比，value参数新增了对百分比字符串和其他[像素单位](ts-pixel-units.md)的支持。 174 175minSideBarWidth优先于侧边栏子组件minWidth，minSideBarWidth未设置时默认值优先级高于侧边栏子组件minWidth。 176 177**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 178 179**系统能力：** SystemCapability.ArkUI.ArkUI.Full 180 181**参数：** 182 183| 参数名 | 类型 | 必填 | 说明 | 184| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 185| value | [Length](ts-types.md#length) | 是 | 侧边栏最小宽度。<br/>默认值：API version 9及以下版本默认值为200vp，API version 10的默认值为240vp。<br/>取值范围：[0, +∞) | 186 187### maxSideBarWidth 188 189maxSideBarWidth(value: number) 190 191设置侧边栏最大宽度。设置为小于0的值时按默认值显示。值不能超过侧边栏容器本身宽度，超过使用侧边栏容器本身宽度。 192 193maxSideBarWidth优先于侧边栏子组件maxWidth，maxSideBarWidth未设置时默认值优先级高于侧边栏子组件maxWidth。 194 195**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 196 197**系统能力：** SystemCapability.ArkUI.ArkUI.Full 198 199**参数：** 200 201| 参数名 | 类型 | 必填 | 说明 | 202| ------ | ------------------------------------------------------------ | ---- | --------------------------------------------------- | 203| value | number | 是 | 设置侧边栏最大宽度。<br/>默认值：280vp<br/>单位：vp<br/>取值范围：[0, +∞) | 204 205### maxSideBarWidth<sup>9+</sup> 206 207maxSideBarWidth(value: Length) 208 209设置侧边栏最大宽度。设置为小于0的值时按默认值显示。值不能超过侧边栏容器本身宽度，超过使用侧边栏容器本身宽度。 210 211maxSideBarWidth优先于侧边栏子组件maxWidth，maxSideBarWidth未设置时默认值优先级高于侧边栏子组件maxWidth。 212 213**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 214 215**系统能力：** SystemCapability.ArkUI.ArkUI.Full 216 217**参数：** 218 219| 参数名 | 类型 | 必填 | 说明 | 220| ------ | ------------------------------------------------------------ | ---- | --------------------------------------------------- | 221| value | [Length](ts-types.md#length) | 是 | 设置侧边栏最大宽度。<br/>默认值：280vp<br/>单位：vp<br/>取值范围：[0, +∞) | 222 223### autoHide<sup>9+</sup> 224 225autoHide(value: boolean) 226 227设置当侧边栏拖拽到小于最小宽度后，是否自动隐藏。受minSideBarWidth属性方法影响，minSideBarWidth属性方法未设置值使用默认值。 228 229拖拽过程中判断是否要自动隐藏。小于最小宽度时需要阻尼效果触发隐藏（越界一段距离）。 230 231**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 232 233**系统能力：** SystemCapability.ArkUI.ArkUI.Full 234 235**参数：** 236 237| 参数名 | 类型 | 必填 | 说明 | 238| ------ | ------- | ---- | ------------------------------------------------------------ | 239| value | boolean | 是 | 侧边栏拖拽到小于最小宽度后，是否自动隐藏。<br/>true：会自动隐藏<br/>false：不会自动隐藏<br/>默认值：true | 240 241### sideBarPosition<sup>9+</sup> 242 243sideBarPosition(value: SideBarPosition) 244 245设置侧边栏显示位置。 246 247**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 248 249**系统能力：** SystemCapability.ArkUI.ArkUI.Full 250 251**参数：** 252 253| 参数名 | 类型 | 必填 | 说明 | 254| ------ | -------------------------------------------- | ---- | -------------------------------------------------- | 255| value | [SideBarPosition](#sidebarposition9枚举说明) | 是 | 侧边栏显示位置。<br/>默认值：SideBarPosition.Start | 256 257### divider<sup>10+</sup> 258 259divider(value: DividerStyle | null) 260 261设置分割线的样式。 262 263**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 264 265**系统能力：** SystemCapability.ArkUI.ArkUI.Full 266 267**参数：** 268 269| 参数名 | 类型 | 必填 | 说明 | 270| ------ | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 271| value | [DividerStyle](#dividerstyle10对象说明) \| null | 是 | 分割线的样式。<br/>默认为DividerStyle：显示分割线。<br/>- null或undefined：行为不做处理，分割线样式与默认值保持一致。<br/>**说明：** <br/>API version 11及以下版本，null效果为不显示分割线。| 272 273### minContentWidth<sup>10+</sup> 274 275minContentWidth(value: Dimension) 276 277设置SideBarContainer组件内容区可显示的最小宽度。 278 279设置为小于0，内容区显示的最小宽度为360vp，未设置该属性时，组件内容区的可缩小到0。 280 281Embed场景下，增大组件尺寸时仅增大内容区的尺寸。 282 283缩小组件尺寸时，先缩小内容区的尺寸至minContentWidth。继续缩小组件尺寸时，保持内容区宽度minContentWidth不变，优先缩小侧边栏的尺寸。 284 285当缩小侧边栏的尺寸至minSideBarWidth后，继续缩小组件尺寸时， 286 287- 如果autoHide属性为false，则会保持侧边栏宽度minSideBarWidth和内容区宽度minContentWidth不变，但内容区会被截断显示； 288- 如果autoHide属性为true，则会优先隐藏侧边栏，然后继续缩小至内容区宽度minContentWidth后，内容区宽度保持不变，但内容区会被截断显示。 289 290minContentWidth优先于侧边栏的maxSideBarWidth与sideBarWidth属性，minContentWidth未设置时默认值优先级低于设置的minSideBarWidth与maxSideBarWidth属性。 291 292**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 293 294**系统能力：** SystemCapability.ArkUI.ArkUI.Full 295 296**参数：** 297 298| 参数名 | 类型 | 必填 | 说明 | 299| ------ | ------------------------------------ | ---- | ------------------------------------------------------------ | 300| value | [Dimension](ts-types.md#dimension10) | 是 | SideBarContainer组件内容区可显示的最小宽度。<br/>默认值：360vp<br/>单位：vp | 301 302## ButtonStyle对象说明 303 304设置侧边栏控制按钮的样式。 305 306**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 307 308**系统能力：** SystemCapability.ArkUI.ArkUI.Full 309 310| 名称 | 类型 | 只读 | 可选 | 说明 | 311| -------- | -------- | -------- | -------- | -------- | 312| left | number | 否 | 是 | 设置侧边栏控制按钮距离容器左界限的间距。<br/>默认值：16vp<br>单位：vp<br/>取值范围：[0, +∞) | 313| top | number | 否 | 是 | 设置侧边栏控制按钮距离容器上界限的间距。<br/>默认值：48vp<br/>单位：vp<br/>取值范围：[0, +∞) | 314| width | number | 否 | 是 | 设置侧边栏控制按钮的宽度。<br/>默认值：<br/>API version 9及之前版本：32vp<br/>从API version 10开始：24vp<br/>单位：vp<br/>取值范围：[0, +∞) | 315| height | number | 否 | 是 | 设置侧边栏控制按钮的高度。<br/>默认值：<br/>API version 9及之前版本：32vp<br/>从API version 10开始：24vp<br/>单位：vp<br/>取值范围：[0, +∞) | 316| icons | [ButtonIconOptions<sup>18+</sup>](#buttoniconoptions18对象说明) | 否 | 是 | 设置侧边栏控制按钮的图标。 | 317 318## ButtonIconOptions<sup>18+</sup>对象说明 319 320设置侧边栏控制按钮的图标。 321 322> **说明：** 323> 324> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 325 326**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 327 328**系统能力：** SystemCapability.ArkUI.ArkUI.Full 329 330| 名称 | 类型 | 只读 | 可选 | 说明 | 331| --------- | ------------------------------- | ---- | ---- | ------------------------------------------ | 332| shown<sup>8+</sup> | string \| [PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md) \| [Resource](ts-types.md#resource) | 否 | 否 | 设置侧边栏显示时控制按钮的图标。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 333| hidden<sup>8+</sup> | string \| [PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md) \| [Resource](ts-types.md#resource) | 否 | 否 | 设置侧边栏隐藏时控制按钮的图标。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 334| switching<sup>8+</sup> | string \| [PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md) \| [Resource](ts-types.md#resource) | 否 | 是 | 设置侧边栏显示和隐藏状态切换时控制按钮的图标。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 335 336> **说明：** 337> 338> 资源获取错误时，使用默认图标。 339 340## SideBarPosition<sup>9+</sup>枚举说明 341 342侧边栏显示位置。 343 344**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 345 346**系统能力：** SystemCapability.ArkUI.ArkUI.Full 347 348| 名称 | 说明 | 349| -------- | -------- | 350| Start | 侧边栏位于容器左侧。 | 351| End | 侧边栏位于容器右侧。 | 352 353## DividerStyle<sup>10+</sup>对象说明 354 355设置分割线的样式。 356 357**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 358 359**系统能力：** SystemCapability.ArkUI.ArkUI.Full 360 361| 名称 | 类型 | 只读 | 可选 | 说明 | 362| ----------- | ------------- | ---- | ---- | ---------------------------------------- | 363| strokeWidth | [Length](ts-types.md#length) | 否 | 否 | 分割线的线宽。<br/>默认值：1vp。<br/>取值范围：[0, +∞)。<br/>**说明**：<br>分割线的宽度不支持百分比设置。优先级低于[通用属性height](ts-universal-attributes-size.md#height)，超过通用属性设置大小时，按照通用属性进行裁切。部分设备硬件中存在1像素取整后分割线不显示问题，建议使用2像素。 | 364| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | 分割线的颜色。<br/>默认值：#000000，3% | 365| startMargin | [Length](ts-types.md#length) | 否 | 是 | 分割线与侧边栏顶端的距离。<br/>默认值：0。<br/>取值范围：[0, +∞)。 | 366| endMargin | [Length](ts-types.md#length) | 否 | 是 | 分割线与侧边栏底端的距离。<br/>默认值：0。<br/>取值范围：[0, +∞)。 | 367> **说明：** 368> 369> 针对侧边栏子组件设置[通用属性宽高](ts-universal-attributes-size.md)时，宽高都不生效。 370> 针对侧边栏内容区设置[通用属性宽高](ts-universal-attributes-size.md)时，宽高都不生效，默认占满SideBarContainer的剩余空间。 371> 372> 当showSideBar属性未设置时，依据组件大小进行自动显示： 373> 374> - 小于minSideBarWidth + minContentWidth：默认不显示侧边栏。 375> - 大于等于minSideBarWidth + minContentWidth：默认显示侧边栏。 376 377## 事件 378 379除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 380 381### onChange 382 383onChange(callback: (value: boolean) => void) 384 385当侧边栏的状态在显示和隐藏之间切换时触发回调。 386 387触发该事件的条件： 388 3891、showSideBar属性值变换时； 390 3912、showSideBar属性自适应行为变化时； 392 3933、分割线拖拽触发autoHide时。 394 395**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 396 397**系统能力：** SystemCapability.ArkUI.ArkUI.Full 398 399**参数：** 400 401| 参数名 | 类型 | 必填 | 说明 | 402| ------ | ------- | ---- | ----------------------------- | 403| value | boolean | 是 | true表示显示，false表示隐藏。 | 404 405 406## 示例 407 408该示例主要演示如何使用侧边栏组件及页面布局效果。 409 410```ts 411// xxx.ets 412@Entry 413@Component 414struct SideBarContainerExample { 415 normalIcon: Resource = $r("app.media.icon"); 416 selectedIcon: Resource = $r("app.media.icon"); 417 @State arr: number[] = [1, 2, 3]; 418 @State current: number = 1; 419 420 build() { 421 SideBarContainer(SideBarContainerType.Embed) { 422 Column() { 423 ForEach(this.arr, (item: number) => { 424 Column({ space: 5 }) { 425 Image(this.current === item ? this.selectedIcon : this.normalIcon).width(64).height(64) 426 Text("Index0" + item) 427 .fontSize(25) 428 .fontColor(this.current === item ? '#0A59F7' : '#999') 429 .fontFamily('source-sans-pro,cursive,sans-serif') 430 } 431 .onClick(() => { 432 this.current = item; 433 }) 434 }, (item: string) => item) 435 }.width('100%') 436 .justifyContent(FlexAlign.SpaceEvenly) 437 .backgroundColor('#19000000') 438 439 Column() { 440 Text('SideBarContainer content text1').fontSize(25) 441 Text('SideBarContainer content text2').fontSize(25) 442 } 443 .margin({ top: 50, left: 20, right: 30 }) 444 } 445 .controlButton({ 446 icons: { 447 hidden: $r('app.media.drawer'), 448 shown: $r('app.media.drawer'), 449 switching: $r('app.media.drawer') 450 } 451 }) 452 .sideBarWidth(150) 453 .minSideBarWidth(50) 454 .maxSideBarWidth(300) 455 .minContentWidth(0) 456 .onChange((value: boolean) => { 457 console.info('status:' + value); 458 }) 459 .divider({ strokeWidth: '1vp', color: Color.Gray, startMargin: '4vp', endMargin: '4vp' }) 460 } 461} 462``` 463 464 465
