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-universal-attributes-size.md) are supported. 25 26## ToolBar 27 28Toolbar({toolBarList: ToolBarOptions, activateIndex?: number, controller: TabsController, dividerModifier: DividerModifier, toolBarModifier: ToolBarModifier}) 29 30**Decorator**: \@Component 31 32**Atomic service API**: This API can be used in atomic services since API version 11. 33 34**System capability**: SystemCapability.ArkUI.ArkUI.Full 35 36| Name | Type | Mandatory| Decorator | Description | 37| ----------------------------- | ------------------------------------------------------------ | ---- | ----------- | ------------------------------------------------------------ | 38| toolBarList | [ToolBarOptions](#toolbaroptions) | Yes | @ObjectLink | Toolbar list. | 39| activateIndex | number | No | @Prop | Index of the active item.<br>Default value: **-1** | 40| controller | [TabsController](ts-container-tabs.md#tabscontroller) | Yes | - | Toolbar controller. | 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>**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>**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 item 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 72## ToolBarModifier<sup>13+</sup> 73Provides 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**). 74 75**Atomic service API**: This API can be used in atomic services since API version 13. 76 77### backgroundColor 78 79backgroundColor(backgroundColor: ResourceColor): ToolBarModifier 80 81Sets the background color of the toolbar. By overriding this API, you can implement custom drawing for the background color of the toolbar. 82 83**Atomic service API**: This API can be used in atomic services since API version 13. 84 85**System capability**: SystemCapability.ArkUI.ArkUI.Full 86 87**Parameters** 88 89| Name | Type | Mandatory| Description | 90| ------- | ------------------------------------------------------ | ---- |------------------------------------------------------------------| 91| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | Yes | Toolbar background color<br>Default value: **$r('sys.color.ohos_id_color_toolbar_bg')**| 92 93### padding 94 95padding(padding: LengthMetrics): ToolBarModifier 96 97Sets 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. 98 99**Atomic service API**: This API can be used in atomic services since API version 13. 100 101**System capability**: SystemCapability.ArkUI.ArkUI.Full 102 103**Parameters** 104 105| Name | Type | Mandatory| Description | 106| ------- |--------| ---- |-------------------------------------------------------------------------------------| 107| 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.| 108 109### height 110 111height(height: LengthMetrics): ToolBarModifier 112 113Sets 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. 114 115**Atomic service API**: This API can be used in atomic services since API version 13. 116 117**System capability**: SystemCapability.ArkUI.ArkUI.Full 118 119**Parameters** 120 121| Name | Type | Mandatory| Description | 122| ------- |---------------------------------| ---- |------------------------------------| 123| 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.| 124 125### stateEffect 126 127stateEffect(stateEffect: boolean): ToolBarModifier 128 129Sets whether to display the pressed state effect. 130 131**Atomic service API**: This API can be used in atomic services since API version 13. 132 133**System capability**: SystemCapability.ArkUI.ArkUI.Full 134 135**Parameters** 136 137| Name | Type | Mandatory| Description | 138| ------- |--------------------------------| ---- |----------------------------------------------------------| 139| 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**| 140 141## ItemState 142 143**Atomic service API**: This API can be used in atomic services since API version 11. 144 145**System capability**: SystemCapability.ArkUI.ArkUI.Full 146 147| Name| Value| Description| 148| -------- | -------- | -------- | 149| ENABLE | 1 | The toolbar item is enabled.| 150| DISABLE | 2 | The toolbar item is disabled.| 151| ACTIVATE | 3 | The toolbar item is activated.| 152 153## ToolBarSymbolGlyphOptions<sup>13+</sup> 154 155Defines the icon symbol options. 156 157**Atomic service API**: This API can be used in atomic services since API version 13. 158 159**System capability**: SystemCapability.ArkUI.ArkUI.Full 160 161| Name | Type | Mandatory| Description | 162| ------ | ---------- | ---- |------------------------------------------------------------------------------------------| 163| 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** | 164| 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**| 165 166## Events 167The [universal events](ts-universal-events-click.md) are supported. 168 169## Example 170 171### Example 1: Setting Toolbar Items to Different States 172This example shows the various display effects when the **state** property of toolbar items is set to **ENABLE**, **DISABLE**, or **ACTIVATE**. 173```ts 174import { ToolBar, ToolBarOptions, ItemState } from '@kit.ArkUI' 175 176@Entry 177@Component 178struct Index { 179 @State toolbarList: ToolBarOptions = new ToolBarOptions() 180 aboutToAppear() { 181 this.toolbarList.push({ 182 content: 'Cut Super Long Text', 183 icon: $r('sys.media.ohos_ic_public_share'), 184 action: () => { 185 }, 186 }) 187 this.toolbarList.push({ 188 content: 'Copy', 189 icon: $r('sys.media.ohos_ic_public_copy'), 190 action: () => { 191 }, 192 state:ItemState.DISABLE 193 }) 194 this.toolbarList.push({ 195 content: 'Paste', 196 icon: $r('sys.media.ohos_ic_public_paste'), 197 action: () => { 198 }, 199 state:ItemState.ACTIVATE 200 }) 201 this.toolbarList.push({ 202 content: 'Select All', 203 icon: $r('sys.media.ohos_ic_public_select_all'), 204 action: () => { 205 }, 206 }) 207 this.toolbarList.push({ 208 content: 'Share', 209 icon: $r('sys.media.ohos_ic_public_share'), 210 action: () => { 211 }, 212 }) 213 this.toolbarList.push({ 214 content: 'Share', 215 icon: $r('sys.media.ohos_ic_public_share'), 216 action: () => { 217 }, 218 }) 219 } 220 build() { 221 Row() { 222 Stack() { 223 Column() { 224 ToolBar({ 225 activateIndex: 2, 226 toolBarList: this.toolbarList, 227 }) 228 } 229 }.align(Alignment.Bottom) 230 .width('100%').height('100%') 231 } 232 } 233} 234``` 235 236 237 238### Example 2 (Customizing the Toolbar Style) 239In this example, you can set the ToolBarModifier attribute to customize the toolbar height, background color, and pressing effect. 240```ts 241import { SymbolGlyphModifier, DividerModifier, ToolBar, ToolBarOptions, ToolBarModifier, ItemState, LengthMetrics } from '@kit.ArkUI'; 242 243@Entry 244@Component 245struct Index { 246 @State toolbarList: ToolBarOptions = new ToolBarOptions(); 247 private toolBarModifier: ToolBarModifier = 248 new ToolBarModifier().height(LengthMetrics.vp(52)).backgroundColor(Color.Transparent).stateEffect(false); 249 @State dividerModifier: DividerModifier = new DividerModifier().height(0); 250 251 aboutToAppear() { 252 this.toolbarList.push({ 253 content: 'Long long long long long long long long text', 254 icon: $r('sys.media.ohos_ic_public_share'), 255 action: () => { 256 }, 257 state: ItemState.ACTIVATE, 258 toolBarSymbolOptions: { 259 normal: new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Green]), 260 activated: new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Red]), 261 }, 262 activatedTextColor: $r('sys.color.font_primary'), 263 }) 264 this.toolbarList.push({ 265 content: 'Copy', 266 icon: $r('sys.media.ohos_ic_public_copy'), 267 action: () => { 268 }, 269 state:ItemState.DISABLE, 270 iconColor: '#ff18cb53', 271 activatedIconColor: '#ffec5d5d', 272 activatedTextColor: '#ffec5d5d', 273 }) 274 this.toolbarList.push({ 275 content: 'Paste', 276 icon: $r('sys.media.ohos_ic_public_paste'), 277 action: () => { 278 }, 279 state:ItemState.ACTIVATE, 280 textColor: '#ff18cb53', 281 }) 282 this.toolbarList.push({ 283 content: 'All', 284 icon: $r('sys.media.ohos_ic_public_select_all'), 285 action: () => { 286 }, 287 state:ItemState.ACTIVATE, 288 }) 289 this.toolbarList.push({ 290 content: 'Share', 291 icon: $r('sys.media.ohos_ic_public_share'), 292 action: () => { 293 }, 294 }) 295 this.toolbarList.push({ 296 content: 'Share', 297 icon: $r('sys.media.ohos_ic_public_share'), 298 action: () => { 299 }, 300 }) 301 } 302 build() { 303 Row() { 304 Stack() { 305 Column() { 306 ToolBar({ 307 toolBarModifier: this.toolBarModifier, 308 dividerModifier: this.dividerModifier, 309 activateIndex: 0, 310 toolBarList: this.toolbarList, 311 }) 312 .height(52) 313 } 314 }.align(Alignment.Bottom) 315 .width('100%').height('100%') 316 } 317 } 318} 319``` 320 321 322
