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