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