• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# SideBarContainer
2
3The **SideBarContainer** component contains a sidebar and content area as its child components. The sidebar is the first child component and can be shown or hidden as needed. The content area is the second child component.
4
5>  **NOTE**
6>
7>  This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
8
9
10## Child Components
11
12Supported
13
14>  **NOTE**
15>
16>  - Built-in components and custom components are allowed, without support for ([if/else](../../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../../quick-start/arkts-rendering-control-foreach.md), and [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)) rendering control.
17>  - This component must contain two child components.
18>  - If there are three or more child components, only the first and second child components are displayed. If there is only one child component, the sidebar is displayed, and the content area is blank.
19
20
21## APIs
22
23SideBarContainer( type?: SideBarContainerType )
24
25Creates a sidebar container.
26
27**Atomic service API**: This API can be used in atomic services since API version 11.
28
29**System capability**: SystemCapability.ArkUI.ArkUI.Full
30
31**Parameters**
32
33| Name| Type| Mandatory| Description|
34| -------- | -------- | -------- | -------- |
35| type | [SideBarContainerType](#sidebarcontainertype) | No| Display type of the sidebar.<br>Default value: **SideBarContainerType.Embed**|
36
37## SideBarContainerType
38
39Enumerates the types of sidebars in a container.
40
41**Atomic service API**: This API can be used in atomic services since API version 11.
42
43**System capability**: SystemCapability.ArkUI.ArkUI.Full
44
45| Name| Description|
46| -------- | -------- |
47| Embed | The sidebar is embedded in the component and displayed side by side with the content area.<br>When the component size is less than the sum of **minContentWidth** and **minSideBarWidth** and **showSideBar** is not set, the sidebar is automatically hidden.<br>If **minSideBarWidth** or **minContentWidth** is not set, the default value will be used for calculation.<br> The user can bring out the sidebar in Overlay mode by clicking the control button.|
48| Overlay | The sidebar is displayed overlaid on the content area.|
49| AUTO<sup>10+</sup> | The sidebar is displayed in Embed mode when the component size is greater than or equal to the sum of **minSideBarWidth** and **minContentWidth**<br>and in Overlay mode otherwise.<br>If **minSideBarWidth** or **minContentWidth** is not set, the default value will be used for calculation. If the calculation result is less than 600 vp, 600 vp will be used as the breakpoint value for mode switching.|
50
51## Attributes
52
53In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported.
54
55### showSideBar
56
57showSideBar(value: boolean)
58
59Specifies whether to display the sidebar.
60
61Since API version 10, this attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).
62
63**Atomic service API**: This API can be used in atomic services since API version 11.
64
65**System capability**: SystemCapability.ArkUI.ArkUI.Full
66
67**Parameters**
68
69| Name| Type   | Mandatory| Description                                                        |
70| ------ | ------- | ---- | ------------------------------------------------------------ |
71| value  | boolean | Yes  | Whether to display the sidebar.<br>**true**: The sidebar is displayed.<br>**false**: The sidebar is not displayed.<br>Default value: **true**|
72
73### controlButton
74
75controlButton(value: ButtonStyle)
76
77Sets the attributes of the sidebar control button.
78
79**Atomic service API**: This API can be used in atomic services since API version 11.
80
81**System capability**: SystemCapability.ArkUI.ArkUI.Full
82
83**Parameters**
84
85| Name| Type                               | Mandatory| Description                  |
86| ------ | ----------------------------------- | ---- | ---------------------- |
87| value  | [ButtonStyle](#buttonstyle) | Yes  | Attributes of the sidebar control button.|
88
89### showControlButton
90
91showControlButton(value: boolean)
92
93Specifies whether to display the sidebar control button.
94
95**Atomic service API**: This API can be used in atomic services since API version 11.
96
97**System capability**: SystemCapability.ArkUI.ArkUI.Full
98
99**Parameters**
100
101| Name| Type   | Mandatory| Description                                                        |
102| ------ | ------- | ---- | ------------------------------------------------------------ |
103| value  | boolean | Yes  | Whether to display the sidebar control button.<br>**true**: The sidebar control button is displayed.<br>**false**: The sidebar control button is not displayed.<br>Default value: **true**|
104
105### sideBarWidth
106
107sideBarWidth(value: number)
108
109Sets the width of the sidebar. If a value less than 0 is set, the default value is used. The value must comply with the width constraints. If it is not within the valid range, the valid value closest to the set one is used.
110
111**Atomic service API**: This API can be used in atomic services since API version 11.
112
113**System capability**: SystemCapability.ArkUI.ArkUI.Full
114
115**Parameters**
116
117| Name| Type                                                        | Mandatory| Description                                                        |
118| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
119| value  | number | Yes  | Width of the sidebar.<br>Default value: **240vp**<br>Unit: vp<br>Value range: [0, +∞).<br>**NOTE**<br>In API version 9 and earlier versions, the default value is **200vp**. In API version 10, the default value is **240vp**.|
120
121### sideBarWidth<sup>9+</sup>
122
123sideBarWidth(value: Length)
124
125Sets the width of the sidebar. If a value less than 0 is set, the default value is used. The value must comply with the width constraints. If it is not within the valid range, the valid value closest to the set one is used. Compared to [sideBarWidth](#sidebarwidth), this API supports percentage strings and other [pixel units](ts-pixel-units.md) for the **value** parameter.
126
127**Atomic service API**: This API can be used in atomic services since API version 11.
128
129**System capability**: SystemCapability.ArkUI.ArkUI.Full
130
131**Parameters**
132
133| Name| Type                                                        | Mandatory| Description                                                        |
134| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
135| value  | [Length](ts-types.md#length) | Yes  | Width of the sidebar.<br>Default value: **240vp**.<br>Unit: vp.<br>Value range: [0, +∞).<br>**NOTE**<br>The default value is **200vp** in API version 9 and **240vp** in API version 10.|
136
137### minSideBarWidth
138
139minSideBarWidth(value: number)
140
141Sets the minimum width of the sidebar. If a value less than 0 is set, the default value is used. The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
142
143**minSideBarWidth**, whether it is specified or kept at the default value, takes precedence over **minWidth** of the sidebar child components.
144
145**Atomic service API**: This API can be used in atomic services since API version 11.
146
147**System capability**: SystemCapability.ArkUI.ArkUI.Full
148
149**Parameters**
150
151| Name| Type                                                        | Mandatory| Description                                                        |
152| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
153| value  | number | Yes  | Minimum width of the sidebar.<br>Default value: In API version 9 and earlier versions, the default value is **200vp**. In API version 10, the default value is **240vp**.<br>Value range: [0, +∞).|
154
155### minSideBarWidth<sup>9+</sup>
156
157minSideBarWidth(value: Length)
158
159Sets the minimum width of the sidebar. If a value less than 0 is set, the default value is used. The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used. Compared to [minSideBarWidth](#minsidebarwidth), this API supports percentage strings and other [pixel units](ts-pixel-units.md) for the **value** parameter.
160
161**minSideBarWidth**, whether it is specified or kept at the default value, takes precedence over **minWidth** of the sidebar child components.
162
163**Atomic service API**: This API can be used in atomic services since API version 11.
164
165**System capability**: SystemCapability.ArkUI.ArkUI.Full
166
167**Parameters**
168
169| Name| Type                                                        | Mandatory| Description                                                        |
170| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
171| value  | [Length](ts-types.md#length) | Yes  | Minimum width of the sidebar.<br>Default value: In API version 9 and earlier versions, the default value is **200vp**. In API version 10, the default value is **240vp**.<br>Value range: [0, +∞).|
172
173### maxSideBarWidth
174
175maxSideBarWidth(value: number)
176
177Sets the maximum width of the sidebar. If a value less than 0 is set, the default value is used. The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
178
179**maxSideBarWidth**, whether it is specified or kept at the default value, takes precedence over **maxWidth** of the sidebar child components.
180
181**Atomic service API**: This API can be used in atomic services since API version 11.
182
183**System capability**: SystemCapability.ArkUI.ArkUI.Full
184
185**Parameters**
186
187| Name| Type                                                        | Mandatory| Description                                               |
188| ------ | ------------------------------------------------------------ | ---- | --------------------------------------------------- |
189| value  | number | Yes  | Maximum width of the sidebar.<br>Default value: **280vp**<br>Unit: vp.<br>Value range: [0, +∞).|
190
191### maxSideBarWidth<sup>9+</sup>
192
193maxSideBarWidth(value: Length)
194
195Sets the maximum width of the sidebar. If a value less than 0 is set, the default value is used. The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
196
197**maxSideBarWidth**, whether it is specified or kept at the default value, takes precedence over **maxWidth** of the sidebar child components.
198
199**Atomic service API**: This API can be used in atomic services since API version 11.
200
201**System capability**: SystemCapability.ArkUI.ArkUI.Full
202
203**Parameters**
204
205| Name| Type                                                        | Mandatory| Description                                               |
206| ------ | ------------------------------------------------------------ | ---- | --------------------------------------------------- |
207| value  | [Length](ts-types.md#length) | Yes  | Maximum width of the sidebar.<br>Default value: **280vp**<br>Unit: vp.<br>Value range: [0, +∞).|
208
209### autoHide<sup>9+</sup>
210
211autoHide(value: boolean)
212
213Specifies whether to automatically hide the sidebar when it is dragged to be smaller than the minimum width. The value is subject to the **minSideBarWidth** attribute method. If it is not set in **minSideBarWidth**, the default value is used.
214
215Whether the sidebar should be hidden is determined when it is being dragged. When it is dragged to be smaller than the minimum width, the damping effect is required to trigger hiding (a distance out of range).
216
217**Atomic service API**: This API can be used in atomic services since API version 11.
218
219**System capability**: SystemCapability.ArkUI.ArkUI.Full
220
221**Parameters**
222
223| Name| Type   | Mandatory| Description                                                        |
224| ------ | ------- | ---- | ------------------------------------------------------------ |
225| value  | boolean | Yes  | Whether to automatically hide the sidebar when it is dragged to be smaller than the minimum width.<br>**true**: The sidebar is automatically hidden.<br>**false**: The sidebar is not automatically hidden.<br>Default value: **true**|
226
227### sideBarPosition<sup>9+</sup>
228
229sideBarPosition(value: SideBarPosition)
230
231Sets the position of the sidebar.
232
233**Atomic service API**: This API can be used in atomic services since API version 11.
234
235**System capability**: SystemCapability.ArkUI.ArkUI.Full
236
237**Parameters**
238
239| Name| Type                                        | Mandatory| Description                                              |
240| ------ | -------------------------------------------- | ---- | -------------------------------------------------- |
241| value  | [SideBarPosition](#sidebarposition9) | Yes  | Position of the sidebar.<br>Default value: **SideBarPosition.Start**|
242
243### divider<sup>10+</sup>
244
245divider(value: DividerStyle | null)
246
247Sets the divider style.
248
249**Atomic service API**: This API can be used in atomic services since API version 11.
250
251**System capability**: SystemCapability.ArkUI.ArkUI.Full
252
253**Parameters**
254
255| Name| Type                                                     | Mandatory| Description                                                        |
256| ------ | --------------------------------------------------------- | ---- | ------------------------------------------------------------ |
257| value  | [DividerStyle](#dividerstyle10) \| null | Yes  | Divider style.<br>- **DividerStyle** (default): The divider is displayed.<br>- **null** or **undefined**: No action is taken, and the divider style remains consistent with the default.<br>**NOTE**<br>In API version 11 and earlier versions, **null** results in the divider not being displayed.|
258
259### minContentWidth<sup>10+</sup>
260
261minContentWidth(value: Dimension)
262
263Sets the minimum content area width of the sidebar container.
264
265If this attribute is set to a value less than 0, the default value **360vp** will be used. If this attribute is not set, the width of the content area can shrink to 0.
266
267In Embed mode, when the component size is increased, only the content area is enlarged;
268
269when the component size is decreased, the content area is shrunk until its width reaches the value defined by **minContentWidth**; if the component size is further decreased, while respecting the **minContentWidth** settings, the sidebar is shrunk
270
271until its width reaches the value defined by **minSideBarWidth**; if the component size is further decreased, then:
272
273- If **autoHide** is set to **false**, while respecting the **minSideBarWidth** and **minContentWidth** settings, the content area has its content clipped.
274- If **autoHide** is set to **true**, the sidebar is hidden first, and then the content area is shrunk. After its width reaches the value defined by **minContentWidth**, the content area has its content clipped.
275
276**minContentWidth**, whether it is specified or kept at the default value, takes precedence over **minSideBarWidth** and **sideBarWidth** of the sidebar.
277
278**Atomic service API**: This API can be used in atomic services since API version 11.
279
280**System capability**: SystemCapability.ArkUI.ArkUI.Full
281
282**Parameters**
283
284| Name| Type                                | Mandatory| Description                                                        |
285| ------ | ------------------------------------ | ---- | ------------------------------------------------------------ |
286| value  | [Dimension](ts-types.md#dimension10) | Yes  | Minimum content area width of the sidebar container.<br>Default value: **360vp**<br>Unit: vp|
287
288## ButtonStyle
289
290Describes the style of the sidebar control button.
291
292**Atomic service API**: This API can be used in atomic services since API version 11.
293
294**System capability**: SystemCapability.ArkUI.ArkUI.Full
295
296| Name| Type| Mandatory| Description|
297| -------- | -------- | -------- | -------- |
298| left | number | No| Spacing between the sidebar control button and the left of the container.<br>Default value: **16vp**<br>Unit: vp.<br>Value range: [0, +∞).|
299| top | number | No| Spacing between the sidebar control button and the top of the container.<br>Default value: **48vp**<br>Unit: vp.<br>Value range: [0, +∞).|
300| width | number | No| Width of the sidebar control button.<br>Default value:<br>API version 9 and earlier versions: **32vp**<br>API version 10 and later versions: **24vp**<br>Unit: vp.<br>Value range: [0, +∞).|
301| height | number | No| Height of the sidebar control button.<br>Default value:<br>API version 9 and earlier versions: **32vp**<br>API version 10 and later versions: **24vp**<br>Unit: vp.<br>Value range: [0, +∞).|
302| icons | [ButtonIconOptions<sup>14+</sup>](#buttoniconoptions14) | No| Icons of the sidebar control button.|
303
304## ButtonIconOptions<sup>14+</sup>
305
306Describes the icons of the sidebar control button.
307
308**Atomic service API**: This API can be used in atomic services since API version 14.
309
310**System capability**: SystemCapability.ArkUI.ArkUI.Full
311
312| Name      | Type                          | Mandatory| Description                                       |
313| --------- | -------------------------------| ---- | ------------------------------------------ |
314| shown<sup>8+</sup>     | string \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md#resource) | Yes  | Icon of the control button when the sidebar is displayed.<br>**Atomic service API**: This API can be used in atomic services since API version 11.             |
315| hidden<sup>8+</sup>    | string \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md#resource) | Yes  | Icon of the control button when the sidebar is hidden.<br>**Atomic service API**: This API can be used in atomic services since API version 11.             |
316| switching<sup>8+</sup> | string \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md#resource) | No  | Icon of the control button when the sidebar is switching between the shown and hidden states.<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
317
318> **NOTE**
319>
320> When an error occurs during resource obtaining, the default icon is used.
321
322## SideBarPosition<sup>9+</sup>
323
324Enumerates the positions of the sidebar.
325
326**Atomic service API**: This API can be used in atomic services since API version 11.
327
328**System capability**: SystemCapability.ArkUI.ArkUI.Full
329
330| Name| Description|
331| -------- | -------- |
332| Start | The sidebar is on the left side of the container.|
333| End | The sidebar is on the right side of the container.|
334
335## DividerStyle<sup>10+</sup>
336
337Sets the divider style.
338
339**Atomic service API**: This API can be used in atomic services since API version 11.
340
341**System capability**: SystemCapability.ArkUI.ArkUI.Full
342
343| Name       | Type     | Mandatory| Description                                    |
344| ----------- | ------------- | ---- | ---------------------------------------- |
345| strokeWidth | [Length](ts-types.md#length)        | Yes  | Stroke width of the divider.<br>Default value: **1vp**|
346| color       | [ResourceColor](ts-types.md#resourcecolor) | No  | Color of the divider.<br>Default value: **#000000, 3%**  |
347| startMargin | [Length](ts-types.md#length)        | No  | Distance between the divider and the top of the sidebar.<br>Default value: **0**|
348| endMargin   | [Length](ts-types.md#length)        | No  | Distance between the divider and the bottom of the sidebar.<br>Default value: **0**|
349>  **NOTE**
350>
351>  The settings of the [universal size attributes](ts-universal-attributes-size.md) **width** and **height** do not take effect for the sidebar child component.
352>  The settings do not take effect for the sidebar content area either. By default, the sidebar content area takes up the remaining space of the sidebar container.
353>
354>  If the **showSideBar** attribute is not set, the sidebar's visibility is subject to its size.
355>
356>  - If the size is less than the sum of **minSideBarWidth** and **minContentWidth**, the sidebar is not displayed by default.
357>  - If the size is greater than or equal to the sum of **minSideBarWidth** and **minContentWidth**, the sidebar is displayed by default.
358
359## Events
360
361In addition to the [universal events](ts-component-general-events.md), the following events are supported.
362
363### onChange
364
365onChange(callback: (value: boolean) =&gt; void)
366
367Triggered when the status of the sidebar switches between shown and hidden.
368
369This event is triggered when any of the following conditions is met:
370
3711. The value of **showSideBar** changes.
372
3732. The **showSideBar** attribute adapts to behavior changes.
374
3753. The **autoHide** API is triggered when the divider is dragged.
376
377**Atomic service API**: This API can be used in atomic services since API version 11.
378
379**System capability**: SystemCapability.ArkUI.ArkUI.Full
380
381**Parameters**
382
383| Name| Type   | Mandatory| Description                         |
384| ------ | ------- | ---- | ----------------------------- |
385| value  | boolean | Yes  | The value **true** means that the sidebar is displayed, and **false** means the opposite.|
386
387
388## Example
389
390This example demonstrates how to use the **SideBarContainer** component and implement the page layout.
391
392```ts
393// xxx.ets
394@Entry
395@Component
396struct SideBarContainerExample {
397  normalIcon: Resource = $r("app.media.icon")
398  selectedIcon: Resource = $r("app.media.icon")
399  @State arr: number[] = [1, 2, 3]
400  @State current: number = 1
401
402  build() {
403    SideBarContainer(SideBarContainerType.Embed) {
404      Column() {
405        ForEach(this.arr, (item: number) => {
406          Column({ space: 5 }) {
407            Image(this.current === item ? this.selectedIcon : this.normalIcon).width(64).height(64)
408            Text("Index0" + item)
409              .fontSize(25)
410              .fontColor(this.current === item ? '#0A59F7' : '#999')
411              .fontFamily('source-sans-pro,cursive,sans-serif')
412          }
413          .onClick(() => {
414            this.current = item
415          })
416        }, (item: string) => item)
417      }.width('100%')
418      .justifyContent(FlexAlign.SpaceEvenly)
419      .backgroundColor('#19000000')
420
421      Column() {
422        Text('SideBarContainer content text1').fontSize(25)
423        Text('SideBarContainer content text2').fontSize(25)
424      }
425      .margin({ top: 50, left: 20, right: 30 })
426    }
427    .controlButton({
428      icons: {
429        hidden: $r('app.media.drawer'),
430        shown: $r('app.media.drawer'),
431        switching: $r('app.media.drawer')
432      }
433    })
434    .sideBarWidth(150)
435    .minSideBarWidth(50)
436    .maxSideBarWidth(300)
437    .minContentWidth(0)
438    .onChange((value: boolean) => {
439      console.info('status:' + value)
440    })
441    .divider({ strokeWidth: '1vp', color: Color.Gray, startMargin: '4vp', endMargin: '4vp' })
442  }
443}
444```
445
446![](figures/sidebarcontainer.png)
447