1# ComposeTitleBar 2 3 4**ComposeTitleBar** represents a common title bar that contains a title, subtitle (optional), and profile picture (optional). It can come with a Back button for switching between pages of different levels. 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 { ComposeTitleBar } 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## ComposeTitleBar 29 30ComposeTitleBar({item?: ComposeTitleBarMenuItem, title: ResourceStr, subtitle?: ResourceStr, menuItems?: Array<ComposeTitleBarMenuItem>}) 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| Description| 39| -------- | -------- | -------- | -------- | 40| item | [ComposeTitleBarMenuItem](#composetitlebarmenuitem) | No| A single menu item for the profile picture on the left.| 41| title | [ResourceStr](ts-types.md#resourcestr) | Yes| Title.| 42| subtitle | [ResourceStr](ts-types.md#resourcestr) | No| Subtitle.| 43| menuItems | Array<[ComposeTitleBarMenuItem](#composetitlebarmenuitem)> | No| List of menu items on the right.| 44 45> **NOTE** 46> 47> The input parameter cannot be **undefined**, that is, calling **ComposeTitleBar(undefined)** is not allowed. 48 49## ComposeTitleBarMenuItem 50 51**System capability**: SystemCapability.ArkUI.ArkUI.Full 52 53| Name| Type| Mandatory| Description| 54| -------- | -------- | -------- | -------- | 55| 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.| 56| 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.| 57| 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.| 58| isEnabled | boolean | No| Whether to enable the item.<br>Default value: **false**<br> **true**: The item is enabled.<br> **false**: The item is disabled.<br>This property cannot be triggered by the **item** property.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 59| action | () => void | No| Action to perform. This parameter is not available for the item attribute.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 60| 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.| 61| 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. | 62| 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. | 63 64## Events 65The [universal events](ts-component-general-events.md) are not supported. 66 67## Example 68 69### Example 1: Implementing a Simple Title Bar 70This example showcases how to implement a simple title bar, a title bar with a back arrow, and a title bar with a list of menu items on the right side. 71```ts 72import { ComposeTitleBar, Prompt, ComposeTitleBarMenuItem } from '@kit.ArkUI'; 73 74@Entry 75@Component 76struct Index { 77 // Define an array of menu items for the right side of the title bar. 78 private menuItems: Array<ComposeTitleBarMenuItem> = [ 79 { 80 // Resource for the menu icon 81 value: $r('sys.media.ohos_save_button_filled'), 82 // Enable the icon. 83 isEnabled: true, 84 // Action triggered when the menu item is clicked. 85 action: () => Prompt.showToast({ message: 'icon 1' }), 86 }, 87 { 88 value: $r('sys.media.ohos_ic_public_copy'), 89 isEnabled: true, 90 action: () => Prompt.showToast({ message: 'icon 2' }), 91 }, 92 { 93 value: $r('sys.media.ohos_ic_public_edit'), 94 isEnabled: true, 95 action: () => Prompt.showToast({ message: 'icon 3' }), 96 }, 97 { 98 value: $r('sys.media.ohos_ic_public_remove'), 99 isEnabled: true, 100 action: () => Prompt.showToast({ message: 'icon 4' }), 101 }, 102 ] 103 104 build() { 105 Row() { 106 Column() { 107 // Divider. 108 Divider().height(2).color(0xCCCCCC) 109 ComposeTitleBar({ 110 title: 'Title', 111 subtitle: 'Subtitle', 112 menuItems: this.menuItems.slice(0, 1), 113 }) 114 Divider().height(2).color(0xCCCCCC) 115 ComposeTitleBar({ 116 title: 'Title', 117 subtitle: 'Subtitle', 118 menuItems: this.menuItems.slice(0, 2), 119 }) 120 Divider().height(2).color(0xCCCCCC) 121 ComposeTitleBar({ 122 title: 'Title', 123 subtitle: 'Subtitle', 124 menuItems: this.menuItems, 125 }) 126 Divider().height(2).color(0xCCCCCC) 127 // Define the title bar with a profile picture. 128 ComposeTitleBar({ 129 menuItems: [{ 130 isEnabled: true, value: $r('sys.media.ohos_save_button_filled'), 131 action: () => Prompt.showToast({ message: 'icon' }), 132 }], 133 title: 'Title', 134 subtitle: 'Subtitle', 135 item: { isEnabled: true, value: $r('sys.media.ohos_app_icon') } 136 }) 137 Divider().height(2).color(0xCCCCCC) 138 } 139 }.height('100%') 140 } 141} 142``` 143 144 145 146### Example 2: Implementing Screen Reader Announcement for the Custom Button on the Right Side 147This 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. 148```ts 149import { ComposeTitleBar, Prompt, ComposeTitleBarMenuItem } from '@kit.ArkUI'; 150 151@Entry 152@Component 153struct Index { 154 // Define an array of menu items for the right side of the title bar. 155 private menuItems: Array<ComposeTitleBarMenuItem> = [ 156 { 157 // Resource for the menu icon 158 value: $r('sys.media.ohos_save_button_filled'), 159 // Enable the icon. 160 isEnabled: true, 161 // Action triggered when the menu item is clicked. 162 action: () => Prompt.showToast({ message: 'icon 1' }), 163 // The screen reader will prioritize this text over the label. 164 accessibilityText: 'Save', 165 // The screen reader can focus on this item. 166 accessibilityLevel: 'yes', 167 // The screen reader will ultimately announce this text. 168 accessibilityDescription: 'Tap to save the current content', 169 }, 170 { 171 value: $r('sys.media.ohos_ic_public_copy'), 172 isEnabled: true, 173 action: () => Prompt.showToast({ message: 'icon 2' }), 174 accessibilityText: 'Copy', 175 // The screen reader will not focus on this item. 176 accessibilityLevel: 'no', 177 accessibilityDescription: 'Tap to copy the current content', 178 }, 179 { 180 value: $r('sys.media.ohos_ic_public_edit'), 181 isEnabled: true, 182 action: () => Prompt.showToast({ message: 'icon 3' }), 183 accessibilityText: 'Edit', 184 accessibilityLevel: 'yes', 185 accessibilityDescription: 'Tap to edit the current content', 186 }, 187 { 188 value: $r('sys.media.ohos_ic_public_remove'), 189 isEnabled: true, 190 action: () => Prompt.showToast({ message: 'icon 4' }), 191 accessibilityText: 'Remove', 192 accessibilityLevel: 'yes', 193 accessibilityDescription: 'Tap to remove the selected item', 194 }, 195 ] 196 197 build() { 198 Row() { 199 Column() { 200 // Divider. 201 Divider().height(2).color(0xCCCCCC) 202 ComposeTitleBar({ 203 title: 'Title', 204 subtitle: 'Subtitle', 205 menuItems: this.menuItems.slice(0, 1), 206 }) 207 Divider().height(2).color(0xCCCCCC) 208 ComposeTitleBar({ 209 title: 'Title', 210 subtitle: 'Subtitle', 211 menuItems: this.menuItems.slice(0, 2), 212 }) 213 Divider().height(2).color(0xCCCCCC) 214 ComposeTitleBar({ 215 title: 'Title', 216 subtitle: 'Subtitle', 217 menuItems: this.menuItems, 218 }) 219 Divider().height(2).color(0xCCCCCC) 220 // Define the title bar with a profile picture. 221 ComposeTitleBar({ 222 menuItems: [{ 223 isEnabled: true, value: $r('sys.media.ohos_save_button_filled'), 224 action: () => Prompt.showToast({ message: 'icon' }), 225 }], 226 title: 'Title', 227 subtitle: 'Subtitle', 228 item: { isEnabled: true, value: $r('sys.media.ohos_app_icon') }, 229 }) 230 Divider().height(2).color(0xCCCCCC) 231 } 232 }.height('100%') 233 } 234} 235``` 236 237 238 239### Example 3: Setting the Symbol Icon 240 241This example demonstrates how to use **symbolStyle** in **ComposeTitleBarMenuItem** to set custom symbol icons. This functionality is supported since API version 18. 242 243```ts 244import { ComposeTitleBar, Prompt, ComposeTitleBarMenuItem, SymbolGlyphModifier } from '@kit.ArkUI'; 245 246@Entry 247@Component 248struct Index { 249 // Define an array of menu items for the right side of the title bar. 250 private menuItems: Array<ComposeTitleBarMenuItem> = [ 251 { 252 // Resource for the menu icon 253 value: $r('sys.symbol.house'), 254 // Menu symbol icon 255 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.bell')).fontColor([Color.Red]), 256 // Enable the icon. 257 isEnabled: true, 258 // Action triggered when the menu item is clicked. 259 action: () => Prompt.showToast({ message: 'symbol icon 1' }), 260 }, 261 { 262 value: $r('sys.symbol.house'), 263 isEnabled: true, 264 action: () => Prompt.showToast({ message: 'symbol icon 2' }), 265 }, 266 { 267 value: $r('sys.symbol.car'), 268 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.heart')).fontColor([Color.Pink]), 269 isEnabled: true, 270 action: () => Prompt.showToast({ message: 'symbol icon 3' }), 271 }, 272 { 273 value: $r('sys.symbol.car'), 274 isEnabled: true, 275 action: () => Prompt.showToast({ message: 'symbol icon 4' }), 276 }, 277 ] 278 279 build() { 280 Row() { 281 Column() { 282 // Divider. 283 Divider().height(2).color(0xCCCCCC) 284 ComposeTitleBar({ 285 title: 'Title', 286 subtitle: 'Subtitle', 287 menuItems: this.menuItems.slice(0, 1), 288 }) 289 Divider().height(2).color(0xCCCCCC) 290 ComposeTitleBar({ 291 title: 'Title', 292 subtitle: 'Subtitle', 293 menuItems: this.menuItems.slice(0, 2), 294 }) 295 Divider().height(2).color(0xCCCCCC) 296 ComposeTitleBar({ 297 title: 'Title', 298 subtitle: 'Subtitle', 299 menuItems: this.menuItems, 300 }) 301 Divider().height(2).color(0xCCCCCC) 302 // Define the title bar with a profile picture. 303 ComposeTitleBar({ 304 menuItems: [{ 305 isEnabled: true, value: $r('sys.symbol.heart'), 306 action: () => Prompt.showToast({ message: 'symbol icon 1' }), 307 }], 308 title: 'Title', 309 subtitle: 'Subtitle', 310 item: { isEnabled: true, value: $r('sys.media.ohos_app_icon') }, 311 }) 312 Divider().height(2).color(0xCCCCCC) 313 } 314 }.height('100%') 315 } 316} 317``` 318 319 320
