1# ToolBar 2 3 4The **Toolbar** component is designed to present a set of action options related to the current screen, displayed at the bottom of the screen. It can display up to five child components. If there are six or more child components, the first four are shown directly, and the additional ones are grouped under a **More** item on the rightmost side of the toolbar. 5 6 7> **NOTE** 8> 9> This component is supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. 10> 11> This component is not supported on wearables. 12 13 14## Modules to Import 15 16```ts 17import { SymbolGlyphModifier, DividerModifier, ToolBar, ToolBarOptions, ToolBarModifier, ItemState, LengthMetrics } from '@kit.ArkUI'; 18``` 19 20 21## Child Components 22 23Not supported 24 25## Attributes 26The [universal attributes](ts-component-general-attributes.md) are not supported. 27 28## ToolBar 29 30Toolbar({toolBarList: ToolBarOptions, activateIndex?: number, controller: TabsController, dividerModifier?: DividerModifier, toolBarModifier?: ToolBarModifier}) 31 32**Decorator**: @Component 33 34**System capability**: SystemCapability.ArkUI.ArkUI.Full 35 36| Name | Type | Mandatory| Decorator | Description | 37| ----------------------------- | ------------------------------------------------------------ | ---- | ----------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------| 38| toolBarList | [ToolBarOptions](#toolbaroptions) | Yes | @ObjectLink | Toolbar list.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 39| activateIndex | number | No | @Prop | Index of the active item.<br>The value must be greater than or equal to -1.<br>The default value is **-1**, indicating that there is no active item. Values less than -1 are treated as no active item.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 40| controller | [TabsController](ts-container-tabs.md#tabscontroller) | Yes | - | Toolbar controller, which cannot be used for controlling individual toolbar items.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 41| dividerModifier<sup>13+</sup> | [DividerModifier](ts-universal-attributes-attribute-modifier.md) | No | @Prop | Modifier for the toolbar header divider, which can be used to customize the divider's height, color, and other attributes.<br>Default value: system default value<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 42| toolBarModifier<sup>13+</sup> | [ToolBarModifier](#toolbarmodifier13) | No | @Prop | Modifier for the toolbar, which can be used to set the toolbar's height, background color, padding (which only takes effect when there are fewer than five toolbar items), and whether to display the pressed state.<br>Default value:<br>Height of the toolbar: **56vp**<br>Background color: **ohos_id_toolbar_bg**<br>Padding: **24vp**<br>Whether to display the pressed state: yes<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 43 44## ToolBarOptions 45 46Inherits Array<[ToolBarOption](#toolbaroption)>. 47 48**Decorator Type**: \@Observed 49 50**Atomic service API**: This API can be used in atomic services since API version 11. 51 52**System capability**: SystemCapability.ArkUI.ArkUI.Full 53 54## ToolBarOption 55 56**Decorator Type**: \@Observed 57 58**System capability**: SystemCapability.ArkUI.ArkUI.Full 59 60| Name | Type | Mandatory| Description | 61|----------------------------------------|-----------------------------------------------------------| -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 62| content | [ResourceStr](ts-types.md#resourcestr) | Yes| Text of the toolbar item.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 63| action | () => void | No| Click event of the toolbar item.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 64| icon | [Resource](ts-types.md#resource) | No| Icon of the toolbar item.<br>If **toolBarSymbolOptions** has input parameters, **icon** is ineffective.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 65| state | [ItemState](#itemstate) | No| State of the toolbar item.<br>Default value: **ENABLE**<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 66| iconColor<sup>13+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Icon fill color of the toolbar item.<br>Default value: **$r('sys.color.icon_primary')**<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 67| activatedIconColor<sup>13+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Icon fill color of the toolbar option in the activated state.<br>Default value: **$r('sys.color.icon_emphasize')**<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 68| textColor<sup>13+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Font color of the toolbar item.<br>Default value: **$r('sys.color.font_primary')**<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 69| activatedTextColor<sup>13+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Font color of the toolbar item in the activated state.<br>Default value: **$r('sys.color.font_emphasize')**<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 70| toolBarSymbolOptions<sup>13+</sup> | [ToolBarSymbolGlyphOptions](#toolbarsymbolglyphoptions13) | No| Icon symbol options of the toolbar item.<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 71| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Accessibility text, that is, accessible label name, of the toolbar item. If a component does not contain text information, it will not be announced by the screen reader when selected. In this case, the screen reader user cannot know which component is selected. To solve this problem, you can set accessibility text for components without text information. When such a component is selected, the screen reader announces the specified accessibility text, informing the user which component is selected.<br>Default value: value of **content**<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 72| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Accessible description of the toolbar item. You can provide comprehensive text explanations to help users understand the operation they are about to perform and its potential consequences, especially when these cannot be inferred from the component's attributes and accessibility text alone. If a component contains both text information and the accessible description, the text is announced first and then the accessible description, when the component is selected.<br>Default value: **"Double-tap to activate"**<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 73| accessibilityLevel<sup>18+</sup> | string | No| Accessibility level of the toolbar item. It determines whether the component can be recognized by accessibility services.<br>The options are as follows:<br>**"auto"**: It is treated as "yes" by the system.<br>**"yes"**: The component can be recognized by accessibility services.<br>**"no"**: The component cannot be recognized by accessibility services.<br>**"no-hide-descendants"**: Neither the component nor its child components can be recognized by accessibility services.<br>Default value: **"auto"**<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 74 75## ToolBarModifier<sup>13+</sup> 76Provides APIs for setting the height (**height**), background color (**backgroundColor**), left and right padding (**padding**, which only takes effect when there are fewer than five items) of the toolbar, and whether to display the pressed state effect (**stateEffect**). 77 78**Atomic service API**: This API can be used in atomic services since API version 13. 79 80### backgroundColor 81 82backgroundColor(backgroundColor: ResourceColor): ToolBarModifier 83 84Sets the background color of the toolbar. By overriding this API, you can implement custom drawing for the background color of the toolbar. 85 86**Atomic service API**: This API can be used in atomic services since API version 13. 87 88**System capability**: SystemCapability.ArkUI.ArkUI.Full 89 90**Parameters** 91 92| Name | Type | Mandatory| Description | 93| ------- | ------------------------------------------------------ | ---- |------------------------------------------------------------------| 94| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | Yes | Toolbar background color<br>Default value: **$r('sys.color.ohos_id_color_toolbar_bg')**| 95 96**Return value** 97 98| Type | Description | 99|---------------------------------------|---------------------------------------| 100| [ToolBarModifier](#toolbarmodifier13) | **ToolBarModifier** object after the background color is set.| 101 102### padding 103 104padding(padding: LengthMetrics): ToolBarModifier 105 106Sets the left and right padding of the toolbar. By overriding this API, you can implement custom drawing for the left and right padding of the toolbar. 107 108**Atomic service API**: This API can be used in atomic services since API version 13. 109 110**System capability**: SystemCapability.ArkUI.ArkUI.Full 111 112**Parameters** 113 114| Name | Type | Mandatory| Description | 115| ------- |--------| ---- |-------------------------------------------------------------------------------------| 116| padding | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12)<sup>12+</sup> | Yes | Left and right padding of the toolbar, which is effective only when there are fewer than five items.<br>By default, the padding is 24 vp when there are fewer than five items and 0 when there are five or more items.| 117 118**Return value** 119 120| Type | Description | 121|---------------------------------------|---------------------------------------| 122| [ToolBarModifier](#toolbarmodifier13) | **ToolBarModifier** object after the padding is set.| 123 124### height 125 126height(height: LengthMetrics): ToolBarModifier 127 128Sets the height of the toolbar. By overriding this API, you can implement custom drawing for the height of the toolbar, which does not include the height of the divider. 129 130**Atomic service API**: This API can be used in atomic services since API version 13. 131 132**System capability**: SystemCapability.ArkUI.ArkUI.Full 133 134**Parameters** 135 136| Name | Type | Mandatory| Description | 137| ------- |---------------------------------| ---- |------------------------------------| 138| height | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12)<sup>12+</sup> | Yes | Height of the toolbar.<br>The default height of the toolbar is 56 vp, which does not include the divider.| 139 140**Return value** 141 142| Type | Description | 143|---------------------------------------|---------------------------------------| 144| [ToolBarModifier](#toolbarmodifier13) | **ToolBarModifier** object after the height is set.| 145 146 147### stateEffect 148 149stateEffect(stateEffect: boolean): ToolBarModifier 150 151Sets whether to display the pressed state effect. 152 153**Atomic service API**: This API can be used in atomic services since API version 13. 154 155**System capability**: SystemCapability.ArkUI.ArkUI.Full 156 157**Parameters** 158 159| Name | Type | Mandatory| Description | 160| ------- |--------------------------------| ---- |----------------------------------------------------------| 161| stateEffect | boolean | Yes | Whether to display the pressed state effect on the toolbar.<br>The value **true** means to display the pressed state effect on the toolbar, and **false** means the opposite.<br>Default value: **true**| 162 163**Return value** 164 165| Type | Description | 166|---------------------------------------|---------------------------------------| 167| [ToolBarModifier](#toolbarmodifier13) | **ToolBarModifier** object after the pressed state effect is set.| 168 169## ItemState 170 171**Atomic service API**: This API can be used in atomic services since API version 11. 172 173**System capability**: SystemCapability.ArkUI.ArkUI.Full 174 175| Name| Value| Description| 176| -------- | -------- | -------- | 177| ENABLE | 1 | The toolbar item is enabled.| 178| DISABLE | 2 | The toolbar item is disabled.| 179| ACTIVATE | 3 | The toolbar item is activated.| 180 181## ToolBarSymbolGlyphOptions<sup>13+</sup> 182 183Defines the icon symbol options. 184 185**Atomic service API**: This API can be used in atomic services since API version 13. 186 187**System capability**: SystemCapability.ArkUI.ArkUI.Full 188 189| Name | Type | Mandatory| Description | 190| ------ | ---------- | ---- |------------------------------------------------------------------------------------------| 191| normal | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No | Icon symbol of the toolbar item in normal state.<br>Default value: **fontColor: $r('sys.color.icon_primary'), fontSize: 24vp** | 192| activated| [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No | Icon symbol of the toolbar item in activated state.<br>Default value: **fontColor: $r('sys.color.icon_emphasize'), fontSize: 24vp**| 193 194## Events 195The [universal events](ts-component-general-events.md) are not supported. 196 197## Example 198 199### Example 1: Setting Toolbar Items to Different States 200This example shows the various display effects when the **state** property of toolbar items is set to **ENABLE**, **DISABLE**, or **ACTIVATE**. 201```ts 202import { ToolBar, ToolBarOptions, ItemState } from '@kit.ArkUI'; 203 204@Entry 205@Component 206struct Index { 207 @State toolbarList: ToolBarOptions = new ToolBarOptions(); 208 209 aboutToAppear() { 210 this.toolbarList.push({ 211 content: 'Cut Super Long Text', 212 icon: $r('sys.media.ohos_ic_public_share'), 213 action: () => { 214 }, 215 }) 216 this.toolbarList.push({ 217 content: 'Copy', 218 icon: $r('sys.media.ohos_ic_public_copy'), 219 action: () => { 220 }, 221 state: ItemState.DISABLE 222 }) 223 this.toolbarList.push({ 224 content: 'Paste', 225 icon: $r('sys.media.ohos_ic_public_paste'), 226 action: () => { 227 }, 228 state: ItemState.ACTIVATE 229 }) 230 this.toolbarList.push({ 231 content: 'Select All', 232 icon: $r('sys.media.ohos_ic_public_select_all'), 233 action: () => { 234 }, 235 }) 236 this.toolbarList.push({ 237 content: 'Share', 238 icon: $r('sys.media.ohos_ic_public_share'), 239 action: () => { 240 }, 241 }) 242 this.toolbarList.push({ 243 content: 'Share', 244 icon: $r('sys.media.ohos_ic_public_share'), 245 action: () => { 246 }, 247 }) 248 } 249 250 build() { 251 Row() { 252 Stack() { 253 Column() { 254 ToolBar({ 255 activateIndex: 2, 256 toolBarList: this.toolbarList, 257 }) 258 } 259 } 260 .align(Alignment.Bottom) 261 .width('100%') 262 .height('100%') 263 } 264 } 265} 266``` 267 268 269 270### Example 2: Customizing the Toolbar Style 271This example demonstrates how to customize the toolbar's height, background color, and other styles using **ToolBarModifier**. This functionality is supported since API version 13. 272```ts 273import { 274 SymbolGlyphModifier, 275 DividerModifier, 276 ToolBar, 277 ToolBarOptions, 278 ToolBarModifier, 279 ItemState, 280 LengthMetrics, 281} from '@kit.ArkUI'; 282 283@Entry 284@Component 285struct Index { 286 @State toolbarList: ToolBarOptions = new ToolBarOptions(); 287 // Custom toolbar style 288 private toolBarModifier: ToolBarModifier = 289 new ToolBarModifier().height(LengthMetrics.vp(52)).backgroundColor(Color.Transparent).stateEffect(false); 290 @State dividerModifier: DividerModifier = new DividerModifier().height(0); 291 292 aboutToAppear() { 293 // Add toolbar items. 294 this.toolbarList.push({ 295 content: 'Long long long long long long long long text', 296 icon: $r('sys.media.ohos_ic_public_share'), 297 action: () => { 298 }, 299 state: ItemState.ACTIVATE, 300 toolBarSymbolOptions: { 301 normal: new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Green]), // Symbol icon in the normal state. 302 activated: new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Red]), // Symbol icon in the activated state. 303 }, 304 activatedTextColor: $r('sys.color.font_primary'), 305 }) 306 this.toolbarList.push({ 307 content: 'Copy', 308 icon: $r('sys.media.ohos_ic_public_copy'), 309 action: () => { 310 }, 311 state: ItemState.DISABLE, 312 iconColor: '#ff18cb53', 313 activatedIconColor: '#ffec5d5d', // Icon fill color of the toolbar item in the activated state. 314 activatedTextColor: '#ffec5d5d', // Font color of the toolbar item in the activated state. 315 }) 316 this.toolbarList.push({ 317 content: 'Paste', 318 icon: $r('sys.media.ohos_ic_public_paste'), 319 action: () => { 320 }, 321 state: ItemState.ACTIVATE, 322 textColor: '#ff18cb53', 323 }) 324 this.toolbarList.push({ 325 content: 'All', 326 icon: $r('sys.media.ohos_ic_public_select_all'), 327 action: () => { 328 }, 329 state: ItemState.ACTIVATE, 330 }) 331 this.toolbarList.push({ 332 content: 'Share', 333 icon: $r('sys.media.ohos_ic_public_share'), 334 action: () => { 335 }, 336 }) 337 this.toolbarList.push({ 338 content: 'Share', 339 icon: $r('sys.media.ohos_ic_public_share'), 340 action: () => { 341 }, 342 }) 343 } 344 345 build() { 346 Row() { 347 Stack() { 348 Column() { 349 ToolBar({ 350 toolBarModifier: this.toolBarModifier, 351 dividerModifier: this.dividerModifier, 352 activateIndex: 0, 353 toolBarList: this.toolbarList, 354 }) 355 .height(52) 356 } 357 } 358 .align(Alignment.Bottom) 359 .width('100%') 360 .height('100%') 361 } 362 } 363} 364``` 365 366 367 368 369### Example 3: Implementing Screen Reader Announcement 370This example customizes the screen reader announcement text by setting the **accessibilityText**, **accessibilityDescription**, and **accessibilityLevel** properties of the toolbar item. This functionality is supported since API version 18. 371```ts 372import { ToolBar, ToolBarOptions, ItemState } from '@kit.ArkUI'; 373 374@Entry 375@Component 376struct Index { 377 @State toolbarList: ToolBarOptions = new ToolBarOptions(); 378 379 aboutToAppear() { 380 // Add toolbar items. 381 this.toolbarList.push({ 382 content: 'Cut Super Long Text', 383 icon: $r('sys.media.ohos_ic_public_share'), 384 action: () => { 385 }, 386 accessibilityText: 'Clip', // Screen reader announcement for the item. 387 accessibilityDescription: 'Double-tap to clip', // Screen reader announcement for the item. 388 accessibilityLevel: 'yes' // Configure this element to be focused by accessibility screen readers. 389 }) 390 this.toolbarList.push({ 391 content: 'Copy', 392 icon: $r('sys.media.ohos_ic_public_copy'), 393 action: () => { 394 }, 395 state: ItemState.DISABLE, 396 accessibilityLevel: 'no' // Configure this button to be not recognizable by screen readers. 397 }) 398 this.toolbarList.push({ 399 content: 'Paste', 400 icon: $r('sys.media.ohos_ic_public_paste'), 401 action: () => { 402 }, 403 state: ItemState.ACTIVATE 404 }) 405 this.toolbarList.push({ 406 content: 'Select All', 407 icon: $r('sys.media.ohos_ic_public_select_all'), 408 action: () => { 409 }, 410 }) 411 this.toolbarList.push({ 412 content: 'Share', 413 icon: $r('sys.media.ohos_ic_public_share'), 414 action: () => { 415 }, 416 }) 417 this.toolbarList.push({ 418 content: 'Share', 419 icon: $r('sys.media.ohos_ic_public_share'), 420 action: () => { 421 }, 422 }) 423 } 424 425 build() { 426 Row() { 427 Stack() { 428 Column() { 429 ToolBar({ 430 activateIndex: 2, 431 toolBarList: this.toolbarList, 432 }) 433 } 434 } 435 .align(Alignment.Bottom) 436 .width('100%') 437 .height('100%') 438 } 439 } 440} 441``` 442 443
