1# ToolBar 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @fengluochenai--> 5<!--Designer: @YanSanzo--> 6<!--Tester: @tinygreyy--> 7<!--Adviser: @HelloCrease--> 8 9 10工具栏用于展示针对当前界面内容的操作选项，在界面底部显示。底部最多显示5个入口，超过则收纳入“更多”子项中，在最右侧显示。 11 12 13> **说明：** 14> 15> 该组件从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 16> 17 18 19## 导入模块 20 21```ts 22import { SymbolGlyphModifier, DividerModifier, ToolBar, ToolBarOptions, ToolBarModifier, ItemState, LengthMetrics } from '@kit.ArkUI'; 23``` 24 25 26## 子组件 27 28无 29 30## 属性 31不支持[通用属性](ts-component-general-attributes.md)。 32 33## ToolBar 34 35Toolbar({toolBarList: ToolBarOptions, activateIndex?: number, controller: TabsController, dividerModifier?: DividerModifier, toolBarModifier?: ToolBarModifier}) 36 37**装饰器类型：**\@Component 38 39**系统能力：** SystemCapability.ArkUI.ArkUI.Full 40 41**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 42 43| 名称 | 类型 | 必填 | 装饰器类型 | 说明 | 44| ----------------------------- | ------------------------------------------------------------ | ---- | ----------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------| 45| toolBarList | [ToolBarOptions](#toolbaroptions) | 是 | @ObjectLink | 工具栏列表。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 46| activateIndex | number | 否 | @Prop | 激活态的子项。<br/>取值范围：大于等于-1。<br/>默认值：-1，没有激活态的子项。若设置数值小于-1，按没有激活项处理。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 47| controller | [TabsController](ts-container-tabs.md#tabscontroller) | 是 | - | 工具栏控制器，不支持控制工具栏子项。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 48| dividerModifier<sup>13+</sup> | [DividerModifier](ts-universal-attributes-attribute-modifier.md#自定义modifier) | 否 | @Prop | 工具栏头部分割线属性，可设置分割线高度、颜色等。<br/>默认值：系统默认值。<br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 49| toolBarModifier<sup>13+</sup> | [ToolBarModifier](#toolbarmodifier13) | 否 | @Prop | 工具栏属性，可设置工具栏高度、背景色、内边距（仅在工具栏子项数量小于5时生效）、是否显示按压态。<br/>默认值：<br/>工具栏高度：56vp<br/>背景色：ohos_id_toolbar_bg<br/>内边距：24vp<br/>显示按压态。<br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 50 51## ToolBarOptions 52 53继承于 Array<[ToolBarOption](#toolbaroption)>。 54 55**装饰器类型：**\@Observed 56 57**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 58 59**系统能力：** SystemCapability.ArkUI.ArkUI.Full 60 61**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 62 63## ToolBarOption 64 65**装饰器类型：**\@Observed 66 67**系统能力：** SystemCapability.ArkUI.ArkUI.Full 68 69**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 70 71| 名称 | 类型 | 必填 | 说明 | 72|----------------------------------------|-----------------------------------------------------------| -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 73| content | [ResourceStr](ts-types.md#resourcestr) | 是 | 工具栏子项的文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 74| action | () => void | 否 | 工具栏子项点击事件。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 75| icon | [Resource](ts-types.md#resource) | 否 | 工具栏子项的图标。<br/>默认不设置或者设置为undefined，图标不显示。<br/>toolBarSymbolOptions有传入参数时，icon不生效。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 76| state | [ItemState](#itemstate) | 否 | 工具栏子项的状态。<br/>默认为ItemState.ENABLE。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 77| iconColor<sup>13+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 工具栏子项的图标填充颜色。<br/>默认值为$r('sys.color.icon_primary')。<br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 78| activatedIconColor<sup>13+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 工具栏子项激活态的图标填充颜色。<br/>默认值为$r('sys.color.icon_emphasize')。<br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 79| textColor<sup>13+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 工具栏子项的文本颜色。<br/>默认值为$r('sys.color.font_primary')。<br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 80| activatedTextColor<sup>13+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 工具栏子项激活态的文本颜色。<br/>默认值为$r('sys.color.font_emphasize')。<br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 81| toolBarSymbolOptions<sup>13+</sup> | [ToolBarSymbolGlyphOptions](#toolbarsymbolglyphoptions13) | 否 | 工具栏子项的图标属性，symbol类型。<br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 82| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 工具栏子项的无障碍文本属性。当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>默认值为当前项content属性内容。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 83| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 工具栏子项的无障碍描述。此描述用于向用户详细解释当前组件，开发人员应为组件的这一属性提供较为详尽的文本说明，以协助用户理解即将执行的操作及其可能产生的后果。特别是当这些后果无法仅从组件的属性和无障碍文本中直接获知时。如果组件同时具备文本属性和无障碍说明属性，当组件被选中时，系统将首先播报组件的文本属性，随后播报无障碍说明属性的内容。<br/>默认值为“单指双击即可执行”。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 84| accessibilityLevel<sup>18+</sup> | string | 否 | 工具栏子项无障碍重要性。用于控制当前项是否可被无障碍辅助服务所识别。<br/>支持的值为：<br/>"auto"：当前组件会转换"yes"。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto"<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 85 86## ToolBarModifier<sup>13+</sup> 87ToolBarModifier提供设置工具栏高度(height)、背景色(backgroundColor)、左右内边距（padding，仅在item小于5个时生效）、是否显示按压态（stateEffect）的方法。 88 89**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 90 91### backgroundColor<sup>13+</sup> 92 93backgroundColor(backgroundColor: ResourceColor): ToolBarModifier 94 95自定义绘制工具栏背景色的接口，若重载该方法则可进行工具栏背景色的自定义绘制。 96 97**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 98 99**系统能力：** SystemCapability.ArkUI.ArkUI.Full 100 101**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 102 103**参数：** 104 105| 参数名 | 类型 | 必填 | 说明 | 106| ------- | ------------------------------------------------------ | ---- |------------------------------------------------------------------| 107| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 是 | 工具栏背景色。<br/>默认背景色为$r('sys.color.ohos_id_color_toolbar_bg')。 | 108 109**返回值：** 110 111| 类型 | 说明 | 112|---------------------------------------|---------------------------------------| 113| [ToolBarModifier](#toolbarmodifier13) | 设置backgroundColor后的ToolBarModifier对象。 | 114 115### padding<sup>13+</sup> 116 117padding(padding: LengthMetrics): ToolBarModifier 118 119自定义绘制工具栏左右内边距的接口，若重载该方法则可进行工具栏左右内边距的自定义绘制。 120 121**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 122 123**系统能力：** SystemCapability.ArkUI.ArkUI.Full 124 125**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 126 127**参数：** 128 129| 参数名 | 类型 | 必填 | 说明 | 130| ------- |--------| ---- |-------------------------------------------------------------------------------------| 131| padding | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 是 | 工具栏左右内边距，仅在item小于5个时生效。<br/>工具栏默认在item小于5个时padding为24vp，大于等于5个时为0。 | 132 133**返回值：** 134 135| 类型 | 说明 | 136|---------------------------------------|---------------------------------------| 137| [ToolBarModifier](#toolbarmodifier13) | 设置padding后的ToolBarModifier对象。 | 138 139### height<sup>13+</sup> 140 141height(height: LengthMetrics): ToolBarModifier 142 143自定义绘制工具栏高度的接口，若重载该方法则可进行工具栏高度的自定义绘制，此高度不包含分割线高度。 144 145**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 146 147**系统能力：** SystemCapability.ArkUI.ArkUI.Full 148 149**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 150 151**参数：** 152 153| 参数名 | 类型 | 必填 | 说明 | 154| ------- |---------------------------------| ---- |------------------------------------| 155| height | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 是 | 工具栏高度。<br/>工具栏高度默认为56vp（不包含分割线）。 | 156 157**返回值：** 158 159| 类型 | 说明 | 160|---------------------------------------|---------------------------------------| 161| [ToolBarModifier](#toolbarmodifier13) | 设置height后的ToolBarModifier对象。 | 162 163 164### stateEffect<sup>13+</sup> 165 166stateEffect(stateEffect: boolean): ToolBarModifier 167 168设置是否显示按压态效果的接口。 169 170**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 171 172**系统能力：** SystemCapability.ArkUI.ArkUI.Full 173 174**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 175 176**参数：** 177 178| 参数名 | 类型 | 必填 | 说明 | 179| ------- |--------------------------------| ---- |----------------------------------------------------------| 180| stateEffect | boolean | 是 | 工具栏是否显示按压态效果。<br/>true为显示按压态效果，false为移除按压态效果，默认为true。 | 181 182**返回值：** 183 184| 类型 | 说明 | 185|---------------------------------------|---------------------------------------| 186| [ToolBarModifier](#toolbarmodifier13) | 设置stateEffect后的ToolBarModifier对象。 | 187 188## ItemState 189 190**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 191 192**系统能力：** SystemCapability.ArkUI.ArkUI.Full 193 194**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 195 196| 名称 | 值 | 说明 | 197| -------- | -------- | -------- | 198| ENABLE | 1 | 工具栏子项为正常可点击状态。 | 199| DISABLE | 2 | 工具栏子项为不可点击状态。 | 200| ACTIVATE | 3 | 工具栏子项为激活状态，可点击。 | 201 202## ToolBarSymbolGlyphOptions<sup>13+</sup> 203 204ToolBarSymbolGlyphOptions定义图标的属性。 205 206**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 207 208**系统能力：** SystemCapability.ArkUI.ArkUI.Full 209 210**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 211 212| 名称 | 类型 | 必填 | 说明 | 213| ------ | ---------- | ---- |------------------------------------------------------------------------------------------| 214| normal | [SymbolGlyphModifier](ts-universal-attributes-attribute-symbolglyphmodifier.md#symbolglyphmodifier) | 否 | 工具栏symbol图标普通态样式。<br/>默认值：fontColor：$r('sys.color.icon_primary')，fontSize：24vp。 | 215| activated| [SymbolGlyphModifier](ts-universal-attributes-attribute-symbolglyphmodifier.md#symbolglyphmodifier) | 否 | 工具栏symbol图标激活态样式。<br/>默认值：fontColor：$r('sys.color.icon_emphasize')，fontSize：24vp。 | 216 217## 事件 218不支持[通用事件](ts-component-general-events.md)。 219 220## 示例 221 222### 示例1（工具栏不同状态的默认效果） 223该示例展示了工具栏子项state属性分别设置ENABLE、DISABLE、ACTIVATE状态的不同显示效果。 224```ts 225import { ToolBar, ToolBarOptions, ItemState } from '@kit.ArkUI'; 226 227@Entry 228@Component 229struct Index { 230 @State toolbarList: ToolBarOptions = new ToolBarOptions(); 231 232 aboutToAppear() { 233 this.toolbarList.push({ 234 content: '剪贴我是超超超超超超超超超长样式', 235 icon: $r('sys.media.ohos_ic_public_share'), 236 action: () => { 237 }, 238 }) 239 this.toolbarList.push({ 240 content: '拷贝', 241 icon: $r('sys.media.ohos_ic_public_copy'), 242 action: () => { 243 }, 244 state: ItemState.DISABLE 245 }) 246 this.toolbarList.push({ 247 content: '粘贴', 248 icon: $r('sys.media.ohos_ic_public_paste'), 249 action: () => { 250 }, 251 state: ItemState.ACTIVATE 252 }) 253 this.toolbarList.push({ 254 content: '全选', 255 icon: $r('sys.media.ohos_ic_public_select_all'), 256 action: () => { 257 }, 258 }) 259 this.toolbarList.push({ 260 content: '分享', 261 icon: $r('sys.media.ohos_ic_public_share'), 262 action: () => { 263 }, 264 }) 265 this.toolbarList.push({ 266 content: '分享', 267 icon: $r('sys.media.ohos_ic_public_share'), 268 action: () => { 269 }, 270 }) 271 } 272 273 build() { 274 Row() { 275 Stack() { 276 Column() { 277 ToolBar({ 278 activateIndex: 2, 279 toolBarList: this.toolbarList, 280 }) 281 } 282 } 283 .align(Alignment.Bottom) 284 .width('100%') 285 .height('100%') 286 } 287 } 288} 289``` 290 291 292 293### 示例2（设置工具栏自定义样式） 294从API version 13开始，该示例通过设置属性ToolBarModifier自定义工具栏高度、背景色、按压效果等样式。 295```ts 296import { 297 SymbolGlyphModifier, 298 DividerModifier, 299 ToolBar, 300 ToolBarOptions, 301 ToolBarModifier, 302 ItemState, 303 LengthMetrics, 304} from '@kit.ArkUI'; 305 306@Entry 307@Component 308struct Index { 309 @State toolbarList: ToolBarOptions = new ToolBarOptions(); 310 // 自定义工具栏样式 311 private toolBarModifier: ToolBarModifier = 312 new ToolBarModifier().height(LengthMetrics.vp(52)).backgroundColor(Color.Transparent).stateEffect(false); 313 @State dividerModifier: DividerModifier = new DividerModifier().height(0); 314 315 aboutToAppear() { 316 // 添加工具栏子项 317 this.toolbarList.push({ 318 content: 'Long long long long long long long long text', 319 icon: $r('sys.media.ohos_ic_public_share'), 320 action: () => { 321 }, 322 state: ItemState.ACTIVATE, 323 toolBarSymbolOptions: { 324 normal: new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Green]), // 普通态symbol图标 325 activated: new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Red]), // 激活态symbol图标 326 }, 327 activatedTextColor: $r('sys.color.font_primary'), 328 }) 329 this.toolbarList.push({ 330 content: 'Copy', 331 icon: $r('sys.media.ohos_ic_public_copy'), 332 action: () => { 333 }, 334 state: ItemState.DISABLE, 335 iconColor: '#ff18cb53', 336 activatedIconColor: '#ffec5d5d', // 激活态icon颜色 337 activatedTextColor: '#ffec5d5d', // 激活态文本颜色 338 }) 339 this.toolbarList.push({ 340 content: 'Paste', 341 icon: $r('sys.media.ohos_ic_public_paste'), 342 action: () => { 343 }, 344 state: ItemState.ACTIVATE, 345 textColor: '#ff18cb53', 346 }) 347 this.toolbarList.push({ 348 content: 'All', 349 icon: $r('sys.media.ohos_ic_public_select_all'), 350 action: () => { 351 }, 352 state: ItemState.ACTIVATE, 353 }) 354 this.toolbarList.push({ 355 content: '分享', 356 icon: $r('sys.media.ohos_ic_public_share'), 357 action: () => { 358 }, 359 }) 360 this.toolbarList.push({ 361 content: '分享', 362 icon: $r('sys.media.ohos_ic_public_share'), 363 action: () => { 364 }, 365 }) 366 } 367 368 build() { 369 Row() { 370 Stack() { 371 Column() { 372 ToolBar({ 373 toolBarModifier: this.toolBarModifier, 374 dividerModifier: this.dividerModifier, 375 activateIndex: 0, 376 toolBarList: this.toolbarList, 377 }) 378 .height(52) 379 } 380 } 381 .align(Alignment.Bottom) 382 .width('100%') 383 .height('100%') 384 } 385 } 386} 387``` 388 389 390 391 392### 示例3（设置工具栏自定义播报） 393从API version 18开始，该示例通过设置工具栏子项属性accessibilityText、accessibilityDescription、accessibilityLevel自定义屏幕朗读播报文本。 394```ts 395import { ToolBar, ToolBarOptions, ItemState } from '@kit.ArkUI'; 396 397@Entry 398@Component 399struct Index { 400 @State toolbarList: ToolBarOptions = new ToolBarOptions(); 401 402 aboutToAppear() { 403 // 添加工具栏子项 404 this.toolbarList.push({ 405 content: '剪贴我是超超超超超超超超超长样式', 406 icon: $r('sys.media.ohos_ic_public_share'), 407 action: () => { 408 }, 409 accessibilityText: '剪贴', // 该项屏幕朗读播报文本为‘剪贴’ 410 accessibilityDescription: '单指双击即可剪贴', // 该项屏幕朗读播报描述为'单指双击即可剪贴' 411 accessibilityLevel: 'yes' // 该项可被无障碍屏幕朗读聚焦 412 }) 413 this.toolbarList.push({ 414 content: '拷贝', 415 icon: $r('sys.media.ohos_ic_public_copy'), 416 action: () => { 417 }, 418 state: ItemState.DISABLE, 419 accessibilityLevel: 'no' // 该项将无法被屏幕朗读服务所识别，屏幕朗读不可聚焦 420 }) 421 this.toolbarList.push({ 422 content: '粘贴', 423 icon: $r('sys.media.ohos_ic_public_paste'), 424 action: () => { 425 }, 426 state: ItemState.ACTIVATE 427 }) 428 this.toolbarList.push({ 429 content: '全选', 430 icon: $r('sys.media.ohos_ic_public_select_all'), 431 action: () => { 432 }, 433 }) 434 this.toolbarList.push({ 435 content: '分享', 436 icon: $r('sys.media.ohos_ic_public_share'), 437 action: () => { 438 }, 439 }) 440 this.toolbarList.push({ 441 content: '分享', 442 icon: $r('sys.media.ohos_ic_public_share'), 443 action: () => { 444 }, 445 }) 446 } 447 448 build() { 449 Row() { 450 Stack() { 451 Column() { 452 ToolBar({ 453 activateIndex: 2, 454 toolBarList: this.toolbarList, 455 }) 456 } 457 } 458 .align(Alignment.Bottom) 459 .width('100%') 460 .height('100%') 461 } 462 } 463} 464``` 465 466
