1# SelectTitleBar 2 3 4The **SelectTitleBar** component represents a drop-down menu title bar - a title bar that contains a drop-down menu - for switching between pages of different levels (configured with the **Back** button). 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``` 15import { SelectTitleBar } 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## SelectTitleBar 27 28SelectTitleBar({selected: number, options: Array<SelectOption>, menuItems?: Array<SelectTitleBarMenuItem>, subtitle?: ResourceStr, badgeValue?: number, hidesBackButton?: boolean, onSelected?: (index: number) => void}) 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| selected | number | Yes| \@Prop | Index of the currently selected item.<br>The index of the first item is 0. If this attribute is not set, the default value **0** will be used.| 39| options | Array<[SelectOption](ts-basic-components-select.md#selectoption)> | Yes| - | Options in the drop-down menu.| 40| menuItems | Array<[SelectTitleBarMenuItem](#selecttitlebarmenuitem)> | No| - | List of menu items on the right of the title bar.| 41| subtitle | [ResourceStr](ts-types.md#resourcestr) | No| - | Subtitle.| 42| badgeValue | number | No| - | Value for the badge.<br>Value range: [-2147483648, 2147483647]<br>If the value is out of the range, 4294967296 is added or subtracted so that the value is within the range. If the value is not an integer, it is rounded off to the nearest integer. For example, 5.5 is rounded off to 5.<br>**NOTE**<br>The badge will not be displayed if the value is less than or equal to 0.<br>The maximum number of messages is 99. If this limit is exceeded, only **99+** is displayed. Extremely large values are considered exceptional and will result in the badge not being displayed.| 43| hidesBackButton | boolean | No| - | Whether to hide the back arrow on the left.<br>Default value: **false** The value **true** means to hide the provider, and **false** means the opposite.| 44| onSelected | (index: number) => void | No| - | Callback invoked when an option in the drop-down menu is selected. The index of the selected option is passed in.| 45 46> **NOTE** 47> 48> The input parameter cannot be **undefined**, that is, calling **SelectTitleBar(undefined)** is not allowed. 49 50## SelectTitleBarMenuItem 51 52**System capability**: SystemCapability.ArkUI.ArkUI.Full 53 54| Name| Type| Mandatory| Description| 55| -------- | -------- | -------- | -------- | 56| value | [ResourceStr](ts-types.md#resourcestr) | Yes| Icon resource.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 57| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No| Symbol icon resource, which has higher priority than **value**.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 58| label<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Icon label.<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 59| isEnabled | boolean | No| Whether to enable the item.<br>Default value: **false**<br> The value **true** means to enable the item, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 60| action | () => void | No| Action to perform.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 61| accessibilityLevel<sup>18+<sup> | string | No| Accessibility level. 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.| 62| accessibilityText<sup>18+<sup> | ResourceStr | No| Accessibility text, that is, accessible label name. 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 the **label** property if it is set and an empty string otherwise.<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 63| accessibilityDescription<sup>18+<sup> | ResourceStr | No| Accessible description. 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. | 64 65## Events 66The [universal events](ts-component-general-events.md) are not supported. 67 68## Example 69 70### Example 1: Implementing a Simple Drop-down Menu Title Bar 71This example demonstrates how to implement a simple drop-down menu title bar with various configurations, including one with a back arrow and one with a right-side menu item list. 72```ts 73import { SelectTitleBar, promptAction, SelectTitleBarMenuItem } from '@kit.ArkUI' 74 75 76@Entry 77@Component 78struct Index { 79 // Define an array of menu items for the right side of the title bar. 80 private menuItems: Array<SelectTitleBarMenuItem> = 81 [ 82 { 83 // Resource for the menu icon. 84 value: $r('sys.media.ohos_save_button_filled'), 85 // Enable the image. 86 isEnabled: true, 87 // Action triggered when the menu item is clicked. 88 action: () => promptAction.showToast({ message: 'show toast index 1' }), 89 }, 90 { 91 value: $r('sys.media.ohos_ic_public_copy'), 92 isEnabled: true, 93 action: () => promptAction.showToast({ message: 'show toast index 2' }), 94 }, 95 { 96 value: $r('sys.media.ohos_ic_public_edit'), 97 isEnabled: true, 98 action: () => promptAction.showToast({ message: 'show toast index 3' }), 99 }, 100 { 101 value: $r('sys.media.ohos_ic_public_remove'), 102 isEnabled: true, 103 action: () => promptAction.showToast({ message: 'show toast index 4' }), 104 }, 105 ] 106 107 build() { 108 Row() { 109 Column() { 110 Divider().height(2).color(0xCCCCCC) 111 SelectTitleBar({ 112 // Define items in the drop-down list. 113 options: [ 114 { value: 'All photos' }, 115 { value: 'Local (device)' }, 116 { value: 'Local (memory card)'} 117 ], 118 // Initially select the first item in the drop-down list. 119 selected: 0, 120 // Function triggered when the item is selected. 121 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 122 // Hide the back arrow on the left. 123 hidesBackButton: true, 124 }) 125 Divider().height(2).color(0xCCCCCC) 126 SelectTitleBar({ 127 options: [ 128 { value: 'All photos' }, 129 { value: 'Local (device)' }, 130 { value: 'Local (memory card)' }, 131 ], 132 selected: 0, 133 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 134 hidesBackButton: false, 135 }) 136 Divider().height(2).color(0xCCCCCC) 137 SelectTitleBar({ 138 options: [ 139 { value: 'All photos' }, 140 { value: 'Local (device)' }, 141 { value: 'Local (memory card)' }, 142 ], 143 selected: 1, 144 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 145 subtitle: 'example@example.com', 146 }) 147 Divider().height(2).color(0xCCCCCC) 148 SelectTitleBar({ 149 options: [ 150 { value: 'All photos' }, 151 { value: 'Local (device)' }, 152 { value: 'Local (memory card)' }, 153 ], 154 selected: 1, 155 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 156 subtitle: 'example@example.com', 157 menuItems: [{ isEnabled: true, value: $r('sys.media.ohos_save_button_filled'), 158 action: () => promptAction.showToast({ message: 'show toast index 1' }), 159 }], 160 }) 161 Divider().height(2).color(0xCCCCCC) 162 SelectTitleBar({ 163 options: [ 164 { value: 'All photos' }, 165 { value: 'Local (device)' }, 166 { value: 'Local (memory card)' }, 167 ], 168 selected: 0, 169 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 170 subtitle: 'example@example.com', 171 menuItems: this.menuItems, 172 badgeValue: 99, 173 hidesBackButton: true, 174 }) 175 Divider().height(2).color(0xCCCCCC) 176 }.width('100%') 177 }.height('100%') 178 } 179} 180``` 181 182 183 184### Example 2: Implementing Screen Reader Announcement for the Custom Button on the Right Side 185This example customizes the screen reader announcement text by setting the **accessibilityText**, **accessibilityDescription**, and **accessibilityLevel** properties of the custom button on the right side of the title bar. 186```ts 187import { SelectTitleBar, promptAction, SelectTitleBarMenuItem } from '@kit.ArkUI' 188 189@Entry 190@Component 191struct Index { 192 // Define an array of menu items for the right side of the title bar. 193 private menuItems: Array<SelectTitleBarMenuItem> = 194 [ 195 { 196 // Resource for the menu icon. 197 value: $r('sys.media.ohos_save_button_filled'), 198 // Enable the image. 199 isEnabled: true, 200 // Action triggered when the menu item is clicked. 201 action: () => promptAction.showToast({ message: 'show toast index 1' }), 202 // The screen reader will prioritize this text over the label. 203 accessibilityText: 'Save', 204 // The screen reader can focus on this item. 205 accessibilityLevel: 'yes', 206 // The screen reader will ultimately announce this text. 207 accessibilityDescription: 'Tap to save the icon', 208 }, 209 { 210 value: $r('sys.media.ohos_ic_public_copy'), 211 isEnabled: true, 212 action: () => promptAction.showToast({ message: 'show toast index 2' }), 213 accessibilityText: 'Copy', 214 // The screen reader will not focus on this item. 215 accessibilityLevel: 'no', 216 accessibilityDescription: 'Tap to copy the icon', 217 }, 218 { 219 value: $r('sys.media.ohos_ic_public_edit'), 220 isEnabled: true, 221 action: () => promptAction.showToast({ message: 'show toast index 3' }), 222 accessibilityText: 'Edit', 223 accessibilityLevel: 'yes', 224 accessibilityDescription: 'Tap to edit the icon', 225 }, 226 { 227 value: $r('sys.media.ohos_ic_public_remove'), 228 isEnabled: true, 229 action: () => promptAction.showToast({ message: "show toast index 4" }), 230 accessibilityText: 'Remove', 231 accessibilityLevel: 'yes', 232 accessibilityDescription: 'Tap to remove the icon', 233 } 234 ] 235 236 build() { 237 Row() { 238 Column() { 239 Divider().height(2).color(0xCCCCCC) 240 SelectTitleBar({ 241 // Define items in the drop-down list. 242 options: [ 243 { value: 'All photos' }, 244 { value: 'Local (device)' }, 245 { value: 'Local (memory card)' }, 246 ], 247 // Initially select the first item in the drop-down list. 248 selected: 0, 249 // Function triggered when the item is selected. 250 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 251 // Hide the back arrow on the left. 252 hidesBackButton: true, 253 }) 254 Divider().height(2).color(0xCCCCCC) 255 SelectTitleBar({ 256 options: [ 257 { value: 'All photos' }, 258 { value: 'Local (device)' }, 259 { value: 'Local (memory card)' }, 260 ], 261 selected: 0, 262 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 263 hidesBackButton: false, 264 }) 265 Divider().height(2).color(0xCCCCCC) 266 SelectTitleBar({ 267 options: [ 268 { value: 'All photos' }, 269 { value: 'Local (device)' }, 270 { value: 'Local (memory card)' }, 271 ], 272 selected: 1, 273 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 274 subtitle: 'example@example.com', 275 }) 276 Divider().height(2).color(0xCCCCCC) 277 SelectTitleBar({ 278 options: [ 279 { value: 'All photos' }, 280 { value: 'Local (device)' }, 281 { value: 'Local (memory card)' }, 282 ], 283 selected: 1, 284 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 285 subtitle: 'example@example.com', 286 menuItems: [{ isEnabled: true, value: $r('sys.media.ohos_save_button_filled'), 287 action: () => promptAction.showToast({ message: 'show toast index 1' }), 288 }], 289 }) 290 Divider().height(2).color(0xCCCCCC) 291 SelectTitleBar({ 292 options: [ 293 { value: 'All photos' }, 294 { value: 'Local (device)' }, 295 { value: 'Local (memory card)' }, 296 ], 297 selected: 0, 298 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 299 subtitle: 'example@example.com', 300 menuItems: this.menuItems, 301 badgeValue: 99, 302 hidesBackButton: true, 303 }) 304 Divider().height(2).color(0xCCCCCC) 305 }.width('100%') 306 }.height('100%') 307 } 308} 309``` 310 311 312### Example 3: Setting the Symbol Icon 313This example demonstrates how to use **symbolStyle** in **SelectTitleBarMenuItem** to set custom symbol icons. 314```ts 315import { SelectTitleBar, promptAction, SelectTitleBarMenuItem, SymbolGlyphModifier } from '@kit.ArkUI' 316 317@Entry 318@Component 319struct Index { 320 // Define an array of menu items for the right side of the title bar. 321 private menuItems: Array<SelectTitleBarMenuItem> = 322 [ 323 { 324 // Resource for the menu icon. 325 value: $r('sys.media.ohos_save_button_filled'), 326 // Resource for the menu symbol icon. 327 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.save')), 328 // Enable the image. 329 isEnabled: true, 330 // Action triggered when the menu item is clicked. 331 action: () => promptAction.showToast({ message: 'show toast index 1' }), 332 // The screen reader will prioritize this text over the label. 333 accessibilityText: 'Save', 334 // The screen reader can focus on this item. 335 accessibilityLevel: 'yes', 336 // The screen reader will ultimately announce this text. 337 accessibilityDescription: 'Tap to save the icon', 338 }, 339 { 340 value: $r('sys.media.ohos_ic_public_copy'), 341 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.car')), 342 isEnabled: true, 343 action: () => promptAction.showToast({ message: 'show toast index 2' }), 344 accessibilityText: 'Copy', 345 // The screen reader will not focus on this item. 346 accessibilityLevel: 'no', 347 accessibilityDescription: 'Tap to copy the icon', 348 }, 349 { 350 value: $r('sys.media.ohos_ic_public_edit'), 351 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.ai_edit')), 352 isEnabled: true, 353 action: () => promptAction.showToast({ message: 'show toast index 3' }), 354 accessibilityText: 'Edit', 355 accessibilityLevel: 'yes', 356 accessibilityDescription: 'Tap to edit the icon', 357 }, 358 { 359 value: $r('sys.media.ohos_ic_public_remove'), 360 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.remove_songlist')), 361 isEnabled: true, 362 action: () => promptAction.showToast({ message: "show toast index 4" }), 363 accessibilityText: 'Remove', 364 accessibilityLevel: 'yes', 365 accessibilityDescription: 'Tap to remove the icon', 366 } 367 ] 368 369 build() { 370 Row() { 371 Column() { 372 Divider().height(2).color(0xCCCCCC) 373 SelectTitleBar({ 374 // Define items in the drop-down list. 375 options: [ 376 { value: 'All photos' }, 377 { value: 'Local (device)' }, 378 { value: 'Local (memory card)' }, 379 ], 380 // Initially select the first item in the drop-down list. 381 selected: 0, 382 // Function triggered when the item is selected. 383 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 384 // Hide the back arrow on the left. 385 hidesBackButton: true, 386 }) 387 Divider().height(2).color(0xCCCCCC) 388 SelectTitleBar({ 389 options: [ 390 { value: 'All photos' }, 391 { value: 'Local (device)' }, 392 { value: 'Local (memory card)' }, 393 ], 394 selected: 0, 395 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 396 hidesBackButton: false, 397 }) 398 Divider().height(2).color(0xCCCCCC) 399 SelectTitleBar({ 400 options: [ 401 { value: 'All photos' }, 402 { value: 'Local (device)' }, 403 { value: 'Local (memory card)' }, 404 ], 405 selected: 1, 406 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 407 subtitle: 'example@example.com', 408 }) 409 Divider().height(2).color(0xCCCCCC) 410 SelectTitleBar({ 411 options: [ 412 { value: 'All photos' }, 413 { value: 'Local (device)' }, 414 { value: 'Local (memory card)' }, 415 ], 416 selected: 1, 417 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 418 subtitle: 'example@example.com', 419 menuItems: [{ 420 isEnabled: true, value: $r('sys.media.ohos_save_button_filled'), 421 action: () => promptAction.showToast({ message: 'show toast index 1' }), 422 }], 423 }) 424 Divider().height(2).color(0xCCCCCC) 425 SelectTitleBar({ 426 options: [ 427 { value: 'All photos' }, 428 { value: 'Local (device)' }, 429 { value: 'Local (memory card)' }, 430 ], 431 selected: 0, 432 onSelected: (index) => promptAction.showToast({ message: 'page index ' + index }), 433 subtitle: 'example@example.com', 434 menuItems: this.menuItems, 435 badgeValue: 99, 436 hidesBackButton: true, 437 }) 438 Divider().height(2).color(0xCCCCCC) 439 }.width('100%') 440 }.height('100%') 441 } 442} 443``` 444 445
