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