• 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
25**Atomic service API**: This API can be used in atomic services since API version 11.
26
27**System capability**: SystemCapability.ArkUI.ArkUI.Full
28
29**Parameters**
30
31| Name| Type| Mandatory| Description|
32| -------- | -------- | -------- | -------- |
33| type | [SideBarContainerType](#sidebarcontainertype) | No| Display type of the sidebar.<br>Default value: **SideBarContainerType.Embed**|
34
35## SideBarContainerType
36
37**Atomic service API**: This API can be used in atomic services since API version 11.
38
39**System capability**: SystemCapability.ArkUI.ArkUI.Full
40
41| Name| Description|
42| -------- | -------- |
43| 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.|
44| Overlay | The sidebar is displayed overlaid on the content area.|
45| 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** 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.|
46
47## Attributes
48
49In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported.
50
51### showSideBar
52
53showSideBar(value: boolean)
54
55Specifies whether to display the sidebar.
56
57Since API version 10, this attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).
58
59**Atomic service API**: This API can be used in atomic services since API version 11.
60
61**System capability**: SystemCapability.ArkUI.ArkUI.Full
62
63**Parameters**
64
65| Name| Type   | Mandatory| Description                                                        |
66| ------ | ------- | ---- | ------------------------------------------------------------ |
67| 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**|
68
69### controlButton
70
71controlButton(value: ButtonStyle)
72
73Sets the attributes of the sidebar control button.
74
75**Atomic service API**: This API can be used in atomic services since API version 11.
76
77**System capability**: SystemCapability.ArkUI.ArkUI.Full
78
79**Parameters**
80
81| Name| Type                               | Mandatory| Description                  |
82| ------ | ----------------------------------- | ---- | ---------------------- |
83| value  | [ButtonStyle](#buttonstyle) | Yes  | Attributes of the sidebar control button.|
84
85### showControlButton
86
87showControlButton(value: boolean)
88
89Specifies whether to display the sidebar control button.
90
91**Atomic service API**: This API can be used in atomic services since API version 11.
92
93**System capability**: SystemCapability.ArkUI.ArkUI.Full
94
95**Parameters**
96
97| Name| Type   | Mandatory| Description                                                        |
98| ------ | ------- | ---- | ------------------------------------------------------------ |
99| 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**|
100
101### sideBarWidth
102
103sideBarWidth(value: number)
104
105Sets the width of the sidebar. A value less than 0 evaluates to the default value. 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.
106
107**Atomic service API**: This API can be used in atomic services since API version 11.
108
109**System capability**: SystemCapability.ArkUI.ArkUI.Full
110
111**Parameters**
112
113| Name| Type                                                        | Mandatory| Description                                                        |
114| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
115| value  | number | Yes  | Width of the sidebar.<br>Default value: **240vp**<br>Unit: vp<br>**NOTE**<br>In API version 9 and earlier versions, the default value is **200vp**. In API version 10, the default value is **240vp**.|
116
117### sideBarWidth<sup>9+</sup>
118
119sideBarWidth(value: Length)
120
121Sets the width of the sidebar. A value less than 0 evaluates to the default value. 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.
122
123**Atomic service API**: This API can be used in atomic services since API version 11.
124
125**System capability**: SystemCapability.ArkUI.ArkUI.Full
126
127**Parameters**
128
129| Name| Type                                                        | Mandatory| Description                                                        |
130| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
131| value  | [Length](ts-types.md#length) | Yes  | Width of the sidebar.<br>Default value: **240vp**<br>Unit: vp<br>**NOTE**<br>The default value is **200vp** in API version 9 and **240vp** in API version 10.|
132
133### minSideBarWidth
134
135minSideBarWidth(value: number)
136
137Sets the minimum width of the sidebar. A value less than 0 evaluates to the default value. The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
138
139**minSideBarWidth**, whether it is specified or kept at the default value, takes precedence over **minWidth** of the sidebar child components.
140
141**Atomic service API**: This API can be used in atomic services since API version 11.
142
143**System capability**: SystemCapability.ArkUI.ArkUI.Full
144
145**Parameters**
146
147| Name| Type                                                        | Mandatory| Description                                                        |
148| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
149| 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**.|
150
151### minSideBarWidth<sup>9+</sup>
152
153minSideBarWidth(value: Length)
154
155Sets the minimum width of the sidebar. A value less than 0 evaluates to the default value. The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
156
157**minSideBarWidth**, whether it is specified or kept at the default value, takes precedence over **minWidth** of the sidebar child components.
158
159**Atomic service API**: This API can be used in atomic services since API version 11.
160
161**System capability**: SystemCapability.ArkUI.ArkUI.Full
162
163**Parameters**
164
165| Name| Type                                                        | Mandatory| Description                                                        |
166| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
167| 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**.|
168
169### maxSideBarWidth
170
171maxSideBarWidth(value: number)
172
173Sets the maximum width of the sidebar. A value less than 0 evaluates to the default value. The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
174
175**maxSideBarWidth**, whether it is specified or kept at the default value, takes precedence over **maxWidth** of the sidebar child components.
176
177**Atomic service API**: This API can be used in atomic services since API version 11.
178
179**System capability**: SystemCapability.ArkUI.ArkUI.Full
180
181**Parameters**
182
183| Name| Type                                                        | Mandatory| Description                                               |
184| ------ | ------------------------------------------------------------ | ---- | --------------------------------------------------- |
185| value  | number | Yes  | Maximum width of the sidebar.<br>Default value: **280vp**<br>Unit: vp|
186
187### maxSideBarWidth<sup>9+</sup>
188
189maxSideBarWidth(value: Length)
190
191Sets the maximum width of the sidebar. A value less than 0 evaluates to the default value. The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
192
193**maxSideBarWidth**, whether it is specified or kept at the default value, takes precedence over **maxWidth** of the sidebar child components.
194
195**Atomic service API**: This API can be used in atomic services since API version 11.
196
197**System capability**: SystemCapability.ArkUI.ArkUI.Full
198
199**Parameters**
200
201| Name| Type                                                        | Mandatory| Description                                               |
202| ------ | ------------------------------------------------------------ | ---- | --------------------------------------------------- |
203| value  | [Length](ts-types.md#length) | Yes  | Maximum width of the sidebar.<br>Default value: **280vp**<br>Unit: vp|
204
205### autoHide<sup>9+</sup>
206
207autoHide(value: boolean)
208
209Specifies 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.
210
211Whether 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).
212
213**Atomic service API**: This API can be used in atomic services since API version 11.
214
215**System capability**: SystemCapability.ArkUI.ArkUI.Full
216
217**Parameters**
218
219| Name| Type   | Mandatory| Description                                                        |
220| ------ | ------- | ---- | ------------------------------------------------------------ |
221| 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**|
222
223### sideBarPosition<sup>9+</sup>
224
225sideBarPosition(value: SideBarPosition)
226
227Sets the position of the sidebar.
228
229**Atomic service API**: This API can be used in atomic services since API version 11.
230
231**System capability**: SystemCapability.ArkUI.ArkUI.Full
232
233**Parameters**
234
235| Name| Type                                        | Mandatory| Description                                              |
236| ------ | -------------------------------------------- | ---- | -------------------------------------------------- |
237| value  | [SideBarPosition](#sidebarposition9) | Yes  | Position of the sidebar.<br>Default value: **SideBarPosition.Start**|
238
239### divider<sup>10+</sup>
240
241divider(value: DividerStyle | null)
242
243Sets the divider style.
244
245**Atomic service API**: This API can be used in atomic services since API version 11.
246
247**System capability**: SystemCapability.ArkUI.ArkUI.Full
248
249**Parameters**
250
251| Name| Type                                                     | Mandatory| Description                                                        |
252| ------ | --------------------------------------------------------- | ---- | ------------------------------------------------------------ |
253| 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.|
254
255### minContentWidth<sup>10+</sup>
256
257minContentWidth(value: Dimension)
258
259Sets the minimum content area width of the sidebar container.
260
261If 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.
262
263In Embed mode, when the component size is increased, only the content area is enlarged;
264
265when 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
266
267until its width reaches the value defined by **minSideBarWidth**; if the component size is further decreased, then:
268
269- If **autoHide** is set to **false**, while respecting the **minSideBarWidth** and **minContentWidth** settings, the content area has its content clipped.
270- 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.
271
272**minContentWidth**, whether it is specified or kept at the default value, takes precedence over **minSideBarWidth** and **sideBarWidth** of the sidebar.
273
274**Atomic service API**: This API can be used in atomic services since API version 11.
275
276**System capability**: SystemCapability.ArkUI.ArkUI.Full
277
278**Parameters**
279
280| Name| Type                                | Mandatory| Description                                                        |
281| ------ | ------------------------------------ | ---- | ------------------------------------------------------------ |
282| value  | [Dimension](ts-types.md#dimension10) | Yes  | Minimum content area width of the sidebar container.<br>Default value: **360vp**<br>Unit: vp|
283
284## ButtonStyle
285
286**Atomic service API**: This API can be used in atomic services since API version 11.
287
288**System capability**: SystemCapability.ArkUI.ArkUI.Full
289
290| Name| Type| Mandatory| Description|
291| -------- | -------- | -------- | -------- |
292| left | number | No| Spacing between the sidebar control button and the left of the container.<br>Default value: **16vp**<br>Unit: vp|
293| top | number | No| Spacing between the sidebar control button and the top of the container.<br>Default value: **48vp**<br>Unit: vp|
294| 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|
295| 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|
296| icons | {<br>shown: string \| PixelMap \| [Resource](ts-types.md) ,<br>hidden: string \| PixelMap \| [Resource](ts-types.md) ,<br>switching?: string \| PixelMap \| [Resource](ts-types.md) <br>} | No| Icons of the sidebar control button.<br> </p> - **shown**: icon of the control button when the sidebar is shown.<br>**NOTE**<br>When an error occurs during resource obtaining, the default icon is used.<br>- **hidden**: icon of the control button when the sidebar is hidden.<br>- **switching**: icon of the control button when the sidebar is switching between the shown and hidden states.|
297
298## SideBarPosition<sup>9+</sup>
299
300Enumerates the positions of the sidebar.
301
302**Atomic service API**: This API can be used in atomic services since API version 11.
303
304**System capability**: SystemCapability.ArkUI.ArkUI.Full
305
306| Name| Description|
307| -------- | -------- |
308| Start | The sidebar is on the left side of the container.|
309| End | The sidebar is on the right side of the container.|
310
311## DividerStyle<sup>10+</sup>
312
313**Atomic service API**: This API can be used in atomic services since API version 11.
314
315**System capability**: SystemCapability.ArkUI.ArkUI.Full
316
317| Name       | Type     | Mandatory| Description                                    |
318| ----------- | ------------- | ---- | ---------------------------------------- |
319| strokeWidth | [Length](ts-types.md#length)        | Yes  | Stroke width of the divider.<br>Default value: **1vp**|
320| color       | [ResourceColor](ts-types.md#resourcecolor) | No  | Color of the divider.<br>Default value: **#000000, 3%**  |
321| startMargin | [Length](ts-types.md#length)        | No  | Distance between the divider and the top of the sidebar.<br>Default value: **0**|
322| endMargin   | [Length](ts-types.md#length)        | No  | Distance between the divider and the bottom of the sidebar.<br>Default value: **0**|
323>  **NOTE**
324>
325>  The settings of the [universal size attributes](ts-universal-attributes-size.md) **width** and **height** do not take effect for the sidebar child component.
326>  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.
327>
328>  If the **showSideBar** attribute is not set, the sidebar's visibility is subject to its size.
329>
330>  - If the size is less than the sum of **minSideBarWidth** and **minContentWidth**, the sidebar is not displayed by default.
331>  - If the size is greater than or equal to the sum of **minSideBarWidth** and **minContentWidth**, the sidebar is displayed by default.
332
333## Events
334
335In addition to the [universal events](ts-component-general-events.md), the following events are supported.
336
337### onChange
338
339onChange(callback: (value: boolean) =&gt; void)
340
341Triggered when the status of the sidebar switches between shown and hidden.
342
343This event is triggered when any of the following conditions is met:
344
3451. The value of **showSideBar** changes.
346
3472. The **showSideBar** attribute adapts to behavior changes.
348
3493. The **autoHide** API is triggered when the divider is dragged.
350
351**Atomic service API**: This API can be used in atomic services since API version 11.
352
353**System capability**: SystemCapability.ArkUI.ArkUI.Full
354
355**Parameters**
356
357| Name| Type   | Mandatory| Description                         |
358| ------ | ------- | ---- | ----------------------------- |
359| value  | boolean | Yes  | The value **true** means that the sidebar is displayed, and **false** means the opposite.|
360
361
362## Example
363
364This example demonstrates how to use the **SideBarContainer** component and implement the page layout.
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