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 12## Modules to Import 13 14```ts 15import { SymbolGlyphModifier, DividerModifier, ToolBar, ToolBarOptions, ToolBarModifier, ItemState, LengthMetrics } from '@kit.ArkUI'; 16``` 17 18 19## Child Components 20 21Not supported 22 23## Attributes 24The [universal attributes](ts-component-general-attributes.md) are not supported. 25 26## ToolBar 27 28Toolbar({toolBarList: ToolBarOptions, activateIndex?: number, controller: TabsController, dividerModifier?: DividerModifier, toolBarModifier?: ToolBarModifier}) 29 30**Decorator**: @Component 31 32**System capability**: SystemCapability.ArkUI.ArkUI.Full 33 34| Name | Type | Mandatory| Decorator | Description | 35| ----------------------------- | ------------------------------------------------------------ | ---- | ----------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------| 36| toolBarList | [ToolBarOptions](#toolbaroptions) | Yes | @ObjectLink | Toolbar list.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 37| 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. | 38| 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. | 39| 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. | 40| 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.| 41 42## ToolBarOptions 43 44Inherits Array<[ToolBarOption](#toolbaroption)>. 45 46**Decorator Type**: \@Observed 47 48**Atomic service API**: This API can be used in atomic services since API version 11. 49 50**System capability**: SystemCapability.ArkUI.ArkUI.Full 51 52## ToolBarOption 53 54**Decorator Type**: \@Observed 55 56**System capability**: SystemCapability.ArkUI.ArkUI.Full 57 58| Name | Type | Mandatory| Description | 59|----------------------------------------|-----------------------------------------------------------| -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 60| 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. | 61| 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. | 62| 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. | 63| 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. | 64| 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. | 65| 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. | 66| 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. | 67| 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. | 68| 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. | 69| 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. | 70| 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. | 71| 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.| 72 73## ToolBarModifier<sup>13+</sup> 74Provides 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**). 75 76**Atomic service API**: This API can be used in atomic services since API version 13. 77 78### backgroundColor 79 80backgroundColor(backgroundColor: ResourceColor): ToolBarModifier 81 82Sets the background color of the toolbar. By overriding this API, you can implement custom drawing for the background color of the toolbar. 83 84**Atomic service API**: This API can be used in atomic services since API version 13. 85 86**System capability**: SystemCapability.ArkUI.ArkUI.Full 87 88**Parameters** 89 90| Name | Type | Mandatory| Description | 91| ------- | ------------------------------------------------------ | ---- |------------------------------------------------------------------| 92| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | Yes | Toolbar background color<br>Default value: **$r('sys.color.ohos_id_color_toolbar_bg')**| 93 94### padding 95 96padding(padding: LengthMetrics): ToolBarModifier 97 98Sets 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. 99 100**Atomic service API**: This API can be used in atomic services since API version 13. 101 102**System capability**: SystemCapability.ArkUI.ArkUI.Full 103 104**Parameters** 105 106| Name | Type | Mandatory| Description | 107| ------- |--------| ---- |-------------------------------------------------------------------------------------| 108| 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.| 109 110### height 111 112height(height: LengthMetrics): ToolBarModifier 113 114Sets 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. 115 116**Atomic service API**: This API can be used in atomic services since API version 13. 117 118**System capability**: SystemCapability.ArkUI.ArkUI.Full 119 120**Parameters** 121 122| Name | Type | Mandatory| Description | 123| ------- |---------------------------------| ---- |------------------------------------| 124| 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.| 125 126### stateEffect 127 128stateEffect(stateEffect: boolean): ToolBarModifier 129 130Sets whether to display the pressed state effect. 131 132**Atomic service API**: This API can be used in atomic services since API version 13. 133 134**System capability**: SystemCapability.ArkUI.ArkUI.Full 135 136**Parameters** 137 138| Name | Type | Mandatory| Description | 139| ------- |--------------------------------| ---- |----------------------------------------------------------| 140| 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**| 141 142## ItemState 143 144**Atomic service API**: This API can be used in atomic services since API version 11. 145 146**System capability**: SystemCapability.ArkUI.ArkUI.Full 147 148| Name| Value| Description| 149| -------- | -------- | -------- | 150| ENABLE | 1 | The toolbar item is enabled.| 151| DISABLE | 2 | The toolbar item is disabled.| 152| ACTIVATE | 3 | The toolbar item is activated.| 153 154## ToolBarSymbolGlyphOptions<sup>13+</sup> 155 156Defines the icon symbol options. 157 158**Atomic service API**: This API can be used in atomic services since API version 13. 159 160**System capability**: SystemCapability.ArkUI.ArkUI.Full 161 162| Name | Type | Mandatory| Description | 163| ------ | ---------- | ---- |------------------------------------------------------------------------------------------| 164| 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** | 165| 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**| 166 167## Events 168The [universal events](ts-component-general-events.md) are not supported. 169 170## Example 171 172### Example 1: Setting Toolbar Items to Different States 173This example shows the various display effects when the **state** property of toolbar items is set to **ENABLE**, **DISABLE**, or **ACTIVATE**. 174```ts 175import { ToolBar, ToolBarOptions, ItemState } from '@kit.ArkUI'; 176 177@Entry 178@Component 179struct Index { 180 @State toolbarList: ToolBarOptions = new ToolBarOptions(); 181 182 aboutToAppear() { 183 this.toolbarList.push({ 184 content: 'Cut Super Long Text', 185 icon: $r('sys.media.ohos_ic_public_share'), 186 action: () => { 187 }, 188 }) 189 this.toolbarList.push({ 190 content: 'Copy', 191 icon: $r('sys.media.ohos_ic_public_copy'), 192 action: () => { 193 }, 194 state: ItemState.DISABLE 195 }) 196 this.toolbarList.push({ 197 content: 'Paste', 198 icon: $r('sys.media.ohos_ic_public_paste'), 199 action: () => { 200 }, 201 state: ItemState.ACTIVATE 202 }) 203 this.toolbarList.push({ 204 content: 'Select All', 205 icon: $r('sys.media.ohos_ic_public_select_all'), 206 action: () => { 207 }, 208 }) 209 this.toolbarList.push({ 210 content: 'Share', 211 icon: $r('sys.media.ohos_ic_public_share'), 212 action: () => { 213 }, 214 }) 215 this.toolbarList.push({ 216 content: 'Share', 217 icon: $r('sys.media.ohos_ic_public_share'), 218 action: () => { 219 }, 220 }) 221 } 222 223 build() { 224 Row() { 225 Stack() { 226 Column() { 227 ToolBar({ 228 activateIndex: 2, 229 toolBarList: this.toolbarList, 230 }) 231 } 232 } 233 .align(Alignment.Bottom) 234 .width('100%') 235 .height('100%') 236 } 237 } 238} 239``` 240 241 242 243### Example 2: Customizing the Toolbar Style 244This example demonstrates how to customize the toolbar's height, background color, and other styles using **ToolBarModifier**. 245```ts 246import { 247 SymbolGlyphModifier, 248 DividerModifier, 249 ToolBar, 250 ToolBarOptions, 251 ToolBarModifier, 252 ItemState, 253 LengthMetrics, 254} from '@kit.ArkUI'; 255 256@Entry 257@Component 258struct Index { 259 @State toolbarList: ToolBarOptions = new ToolBarOptions(); 260 // Custom toolbar style 261 private toolBarModifier: ToolBarModifier = 262 new ToolBarModifier().height(LengthMetrics.vp(52)).backgroundColor(Color.Transparent).stateEffect(false); 263 @State dividerModifier: DividerModifier = new DividerModifier().height(0); 264 265 aboutToAppear() { 266 // Add toolbar items. 267 this.toolbarList.push({ 268 content: 'Long long long long long long long long text', 269 icon: $r('sys.media.ohos_ic_public_share'), 270 action: () => { 271 }, 272 state: ItemState.ACTIVATE, 273 toolBarSymbolOptions: { 274 normal: new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Green]), // Symbol icon in the normal state. 275 activated: new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Red]), // Symbol icon in the activated state. 276 }, 277 activatedTextColor: $r('sys.color.font_primary'), 278 }) 279 this.toolbarList.push({ 280 content: 'Copy', 281 icon: $r('sys.media.ohos_ic_public_copy'), 282 action: () => { 283 }, 284 state: ItemState.DISABLE, 285 iconColor: '#ff18cb53', 286 activatedIconColor: '#ffec5d5d', // Icon fill color of the toolbar item in the activated state. 287 activatedTextColor: '#ffec5d5d', // Font color of the toolbar item in the activated state. 288 }) 289 this.toolbarList.push({ 290 content: 'Paste', 291 icon: $r('sys.media.ohos_ic_public_paste'), 292 action: () => { 293 }, 294 state: ItemState.ACTIVATE, 295 textColor: '#ff18cb53', 296 }) 297 this.toolbarList.push({ 298 content: 'All', 299 icon: $r('sys.media.ohos_ic_public_select_all'), 300 action: () => { 301 }, 302 state: ItemState.ACTIVATE, 303 }) 304 this.toolbarList.push({ 305 content: 'Share', 306 icon: $r('sys.media.ohos_ic_public_share'), 307 action: () => { 308 }, 309 }) 310 this.toolbarList.push({ 311 content: 'Share', 312 icon: $r('sys.media.ohos_ic_public_share'), 313 action: () => { 314 }, 315 }) 316 } 317 318 build() { 319 Row() { 320 Stack() { 321 Column() { 322 ToolBar({ 323 toolBarModifier: this.toolBarModifier, 324 dividerModifier: this.dividerModifier, 325 activateIndex: 0, 326 toolBarList: this.toolbarList, 327 }) 328 .height(52) 329 } 330 } 331 .align(Alignment.Bottom) 332 .width('100%') 333 .height('100%') 334 } 335 } 336} 337``` 338 339 340 341 342### Example 3: Implementing Screen Reader Announcement 343This example customizes the screen reader announcement text by setting the **accessibilityText**, **accessibilityDescription**, and **accessibilityLevel** properties of the toolbar item. 344```ts 345import { ToolBar, ToolBarOptions, ItemState } from '@kit.ArkUI'; 346 347@Entry 348@Component 349struct Index { 350 @State toolbarList: ToolBarOptions = new ToolBarOptions(); 351 352 aboutToAppear() { 353 // Add toolbar items. 354 this.toolbarList.push({ 355 content: 'Cut Super Long Text', 356 icon: $r('sys.media.ohos_ic_public_share'), 357 action: () => { 358 }, 359 accessibilityText: 'Clip', // Screen reader announcement for the item. 360 accessibilityDescription: 'Double-tap to clip', // Screen reader announcement for the item. 361 accessibilityLevel: 'yes' // Configure this element to be focused by accessibility screen readers. 362 }) 363 this.toolbarList.push({ 364 content: 'Copy', 365 icon: $r('sys.media.ohos_ic_public_copy'), 366 action: () => { 367 }, 368 state: ItemState.DISABLE, 369 accessibilityLevel: 'no' // Configure this button to be not recognizable by screen readers. 370 }) 371 this.toolbarList.push({ 372 content: 'Paste', 373 icon: $r('sys.media.ohos_ic_public_paste'), 374 action: () => { 375 }, 376 state: ItemState.ACTIVATE 377 }) 378 this.toolbarList.push({ 379 content: 'Select All', 380 icon: $r('sys.media.ohos_ic_public_select_all'), 381 action: () => { 382 }, 383 }) 384 this.toolbarList.push({ 385 content: 'Share', 386 icon: $r('sys.media.ohos_ic_public_share'), 387 action: () => { 388 }, 389 }) 390 this.toolbarList.push({ 391 content: 'Share', 392 icon: $r('sys.media.ohos_ic_public_share'), 393 action: () => { 394 }, 395 }) 396 } 397 398 build() { 399 Row() { 400 Stack() { 401 Column() { 402 ToolBar({ 403 activateIndex: 2, 404 toolBarList: this.toolbarList, 405 }) 406 } 407 } 408 .align(Alignment.Bottom) 409 .width('100%') 410 .height('100%') 411 } 412 } 413} 414``` 415 416
