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