1# EditableTitleBar 2 3 4The editable title bar is a title bar that comes with button icons, typically **Cancel** on the left and **Confirm** on the right, on a multi-select or editing page. 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 { EditableTitleBar } 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 29## EditableTitleBar 30 31EditableTitleBar({leftIconStyle: EditableLeftIconType, imageItem?: EditableTitleBarItem, title: ResourceStr, subtitle?: ResourceStr, menuItems?: Array<EditableTitleBarMenuItem>, isSaveIconRequired: boolean, onSave?: () => void, onCancel?: () =>void, options: EditableTitleBarOptions, contentMargin?: LocalizedMargin, leftIconDefaultFocus?: boolean, saveIconDefaultFocus?: boolean}) 32 33**Decorator**: @Component 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37| Name| Type| Mandatory| Decorator| Description | 38| -------- | -------- | -------- | -------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 39| leftIconStyle | [EditableLeftIconType](#editablelefticontype) | Yes| - | Type of the icon on the left.<br>Default value: **EditableLeftIconType.Back**<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 40| imageItem<sup>12+</sup> | [EditableTitleBarItem](#editabletitlebaritem12) | No| - | A single menu item for the profile picture on the left.<br>Default value: **undefined**.<br>**NOTE**<br>Accessibility properties not supported.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 41| title | [ResourceStr](ts-types.md#resourcestr) | Yes| - | Title.<br>Default value: **''**, indicating that the title is empty<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 42| subtitle<sup>12+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| - | Subtitle.<br>Default value: **''**, indicating that the subtitle is empty<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 43| menuItems | Array<[EditableTitleBarMenuItem](#editabletitlebarmenuitem)> | No| - | List of menu items on the right.<br>Default value: **undefined**.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 44| isSaveIconRequired<sup>12+</sup> | boolean | Yes| - | Whether the save button on the right is required.<br>Default value: **true**, indicating that the save button on the right is required.<br>**NOTE**<br>If not decorated by @Require, this parameter is not subject to mandatory validation during construction.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 45| onSave | () => void | No| - | Callback invoked when the Save icon is clicked.<br>Default value: **() => void**<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 46| onCancel | () => void | No| - | Callback that is triggered when the cancel action is performed with the left Cancel icon.<br>Default value: **() => void**<br>Since API version 12: Callback that is triggered when the back action is performed with the left Back icon.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 47| options<sup>12+</sup> | [EditableTitleBarOptions](#editabletitlebaroptions12) | Yes| - | Title style.<br>Default value:<br>{<br>safeAreaTypes: [SafeAreaType.SYSTEM],<br>safeAreaEdges: [SafeAreaEdge.TOP], <br>backgroundColor: '#00000000'<br>}<br>**NOTE**<br>If not decorated by @Require, this parameter is not subject to mandatory validation during construction.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 48| contentMargin<sup>12+</sup> | [LocalizedMargin](ts-types.md#localizedmargin12) | No| @Prop | Margin of the content. Negative numbers are not supported.<br>Default value:<br> {start: LengthMetrics.resource(*$r('sys.float.margin_left')*), end: LengthMetrics.resource(*$r('sys.float.margin_right')*)}<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 49| leftIconDefaultFocus<sup>18+</sup> | boolean | No| - | Whether the left icon is the default focus.<br>Default value: **false**, indicating that the left icon is not the default focus.<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 50| saveIconDefaultFocus<sup>18+</sup> | boolean | No| - | Whether the save icon is the default focus.<br>Default value: **false**, indicating that the save icon is not the default focus.<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 51 52> **NOTE** 53> 54> The input parameter cannot be **undefined**, that is, calling **EditableTitleBar(undefined)** is not allowed. 55> If multiple operable areas are set as default focus, the first one in the display order that is set as the default focus will be the default focus. 56 57## EditableLeftIconType 58 59**Atomic service API**: This API can be used in atomic services since API version 11. 60 61**System capability**: SystemCapability.ArkUI.ArkUI.Full 62 63| Name| Value| Description| 64| -------- | -------- | -------- | 65| Back | 0 | Back.| 66| Cancel | 1 | Cancel.| 67 68## EditableTitleBarMenuItem 69 70**System capability**: SystemCapability.ArkUI.ArkUI.Full 71 72| Name| Type| Mandatory| Description | 73| -------- | -------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 74| 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. | 75| 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.| 76| label<sup>12+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Icon label.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 77| isEnabled | boolean | No| Whether to enable the item.<br>Default value: **true**<br><br> **true**: The item is enabled.<br> **false**: The item is disabled.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 78| action | () => void | No| Action to perform.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 79| 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.| 80| 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. | 81| 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. | 82| defaultFocus<sup>18+<sup> | boolean | No| Whether to set the item as the default focus.<br>**true**: Set the item as the default focus.<br>**false**: Do not set the item as the default focus.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 83 84## EditableTitleBarItem<sup>12+</sup> 85 86type EditableTitleBarItem = EditableTitleBarMenuItem 87 88**Atomic service API**: This API can be used in atomic services since API version 12. 89 90**System capability**: SystemCapability.ArkUI.ArkUI.Full 91 92| Type| Description| 93| -------- | -------- | 94| [EditableTitleBarMenuItem](#editabletitlebarmenuitem) | A single menu item for the profile picture on the left.| 95 96## EditableTitleBarOptions<sup>12+</sup> 97 98**Atomic service API**: This API can be used in atomic services since API version 12. 99 100**System capability**: SystemCapability.ArkUI.ArkUI.Full 101 102| Name| Type| Mandatory| Description| 103| -------- | -------- | -------- | -------- | 104| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No| Background color of the title bar.<br>Default value: **'#00000000'**| 105| backgroundBlurStyle | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Background blur style of the title bar.<br>Default value: **[BlurStyle.NONE]**| 106| safeAreaTypes | Array <[SafeAreaType](ts-types.md#safeareatype10)> | No | Types of the expanded safe areas.<br>Default value: **[SafeAreaType.SYSTEM]**| 107| safeAreaEdges | Array <[SafeAreaEdge](ts-types.md#safeareaedge10)> | No | Edges for expanding the safe area.<br>Default value: **[SafeAreaEdge.TOP]**| 108 109## Events 110The [universal events](ts-component-general-events.md) are not supported. 111 112## Example 113 114### Example 1: Implementing an Editable Title Bar with a Custom Right Icon 115 This example demonstrates how to implement an editable title bar with a left icon, main title, and custom right icon area. 116 117```ts 118import { EditableLeftIconType, EditableTitleBar, Prompt } from '@kit.ArkUI'; 119 120@Entry 121@Component 122struct Index { 123 build() { 124 Row() { 125 Column() { 126 Divider().height(2).color(0xCCCCCC) 127 // Cancel button on the left and save button on the right. 128 EditableTitleBar({ 129 leftIconStyle: EditableLeftIconType.Cancel, 130 title: 'Edit', 131 menuItems: [], 132 onCancel: () => { 133 Prompt.showToast({ message: 'on cancel' }); 134 }, 135 onSave: () => { 136 Prompt.showToast({ message: 'on save' }); 137 } 138 }) 139 Divider().height(2).color(0xCCCCCC) 140 // Back button on the left, and custom cancel (disabled) and save buttons on the right. 141 EditableTitleBar({ 142 leftIconStyle: EditableLeftIconType.Back, 143 title: 'Edit', 144 menuItems: [ 145 { 146 value: $r('sys.media.ohos_ic_public_cancel'), 147 isEnabled: false, 148 action: () => { 149 Prompt.showToast({ message: 'show toast index 2' }); 150 } 151 } 152 ], 153 onSave: () => { 154 Prompt.showToast({ message: 'on save' }) 155 } 156 }) 157 Divider().height(2).color(0xCCCCCC) 158 }.width('100%') 159 }.height('100%') 160 } 161} 162``` 163 164 165 166### Example 2: Implementing an Editable Title Bar with Background Blur and a Profile Picture 167This example shows how to implement an editable title bar with background blur, a profile picture, and custom margins. 168 169```ts 170import { EditableLeftIconType, EditableTitleBar, LengthMetrics, Prompt } from '@kit.ArkUI'; 171 172@Entry 173@Component 174struct Index { 175 @State titleBarMargin: LocalizedMargin = { 176 start: LengthMetrics.vp(35), 177 end: LengthMetrics.vp(35), 178 }; 179 180 build() { 181 Row() { 182 Column() { 183 EditableTitleBar({ 184 leftIconStyle: EditableLeftIconType.Cancel, 185 title: 'Main title', 186 subtitle: 'Subtitle', 187 // Set the background blur effect. 188 options: { 189 backgroundBlurStyle: BlurStyle.COMPONENT_THICK, 190 }, 191 onSave: () => { 192 Prompt.showToast({ message: "on save" }); 193 }, 194 }) 195 Divider().height(2).color(0xCCCCCC); 196 EditableTitleBar({ 197 leftIconStyle: EditableLeftIconType.Cancel, 198 title: 'Main title', 199 subtitle: 'Subtitle', 200 // Remove the save button on the right. 201 isSaveIconRequired: false, 202 }) 203 Divider().height(2).color(0xCCCCCC); 204 EditableTitleBar({ 205 leftIconStyle: EditableLeftIconType.Back, 206 title: 'Main title', 207 subtitle: 'Subtitle', 208 isSaveIconRequired: false, 209 onCancel: () => { 210 this.getUIContext()?.getRouter()?.back(); 211 }, 212 }) 213 Divider().height(2).color(0xCCCCCC); 214 EditableTitleBar({ 215 leftIconStyle: EditableLeftIconType.Back, 216 title: 'Main title', 217 subtitle: 'Subtitle', 218 menuItems: [ 219 { 220 value: $r('sys.media.ohos_ic_public_remove'), 221 isEnabled: true, 222 action: () => { 223 Prompt.showToast({ message: "show toast index 1" }); 224 } 225 } 226 ], 227 isSaveIconRequired: false, 228 // Action triggered when the Back icon on the left is clicked. 229 onCancel: () => { 230 this.getUIContext()?.getRouter()?.back(); 231 }, 232 }) 233 Divider().height(2).color(0xCCCCCC); 234 EditableTitleBar({ 235 leftIconStyle: EditableLeftIconType.Back, 236 title: 'Main title', 237 subtitle: 'Subtitle', 238 // Set a clickable profile picture. 239 imageItem: { 240 value: $r('sys.media.ohos_ic_normal_white_grid_image'), 241 isEnabled: true, 242 action: () => { 243 Prompt.showToast({ message: "show toast index 2" }); 244 } 245 }, 246 // Set the content margin of the title bar. 247 contentMargin: this.titleBarMargin, 248 // Configure the icon on the right. 249 menuItems: [ 250 { 251 value: $r('sys.media.ohos_ic_public_remove'), 252 isEnabled: true, 253 action: () => { 254 Prompt.showToast({ message: "show toast index 3" }); 255 } 256 } 257 ], 258 onCancel: () => { 259 this.getUIContext()?.getRouter()?.back(); 260 }, 261 }) 262 } 263 } 264 } 265} 266``` 267 268 269 270### Example 3: Implementing Screen Reader Announcement for the Custom Button on the Right Side 271This 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. 272```ts 273 274import { Prompt, EditableLeftIconType, EditableTitleBar } from '@kit.ArkUI'; 275 276@Entry 277@Component 278struct Index1 { 279 build() { 280 Row() { 281 Column() { 282 Divider().height(2).color(0xCCCCCC) 283 EditableTitleBar({ 284 leftIconStyle: EditableLeftIconType.Cancel, 285 title: 'Edit', 286 menuItems: [], 287 onCancel: () => { 288 Prompt.showToast({ message: 'on cancel' }); 289 }, 290 onSave: () => { 291 Prompt.showToast({ message: 'on save' }); 292 } 293 }) 294 Divider().height(2).color(0xCCCCCC) 295 EditableTitleBar({ 296 // The profile picture and custom buttons are unavailable. 297 leftIconStyle: EditableLeftIconType.Back, 298 title: 'Main title', 299 subtitle: 'Subtitle', 300 imageItem: { 301 value: $r('sys.media.ohos_ic_normal_white_grid_image'), 302 isEnabled: true, 303 action: () => { 304 Prompt.showToast({ message: "show toast index 1" }); 305 } 306 }, 307 menuItems: [ 308 { 309 value: $r('sys.media.ohos_ic_public_remove'), 310 label: 'Cancel', 311 isEnabled: false, 312 accessibilityText: 'Delete', 313 accessibilityDescription: 'Tap to delete', 314 action: () => { 315 Prompt.showToast({ message: "show toast index 2" }); 316 } 317 } 318 ], 319 onCancel: () => { 320 this.getUIContext()?.getRouter()?.back(); 321 }, 322 }) 323 Divider().height(2).color(0xCCCCCC) 324 } 325 } 326 } 327} 328``` 329 330 331### Example 4: Setting the Left Icon as the Default Focus 332This example demonstrates how to set the left icon as the default focus using **leftIconDefaultFocus**. This functionality is supported since API version 18. 333```ts 334 335import { Prompt, EditableLeftIconType, EditableTitleBar } from '@kit.ArkUI'; 336 337@Entry 338@Component 339struct Index { 340 build() { 341 Column() { 342 EditableTitleBar({ 343 leftIconStyle: EditableLeftIconType.Back, 344 leftIconDefaultFocus: true, // Set the left icon as the default focus. 345 title: 'Edit', 346 menuItems: [], 347 onSave: () => { 348 Prompt.showToast({ message: 'on save' }); 349 } 350 }) 351 } 352 .height('100%') 353 .width('100%') 354 } 355} 356``` 357 358 359### Example 5: Setting a Custom Right Icon as the Default Focus 360This example demonstrates how to set a custom right icon as the default focus using **defaultFocus**. This functionality is supported since API version 18. 361```ts 362 363import { Prompt, EditableLeftIconType, EditableTitleBar } from '@kit.ArkUI'; 364 365@Entry 366@Component 367struct Index { 368 build() { 369 Column() { 370 EditableTitleBar({ 371 leftIconStyle: EditableLeftIconType.Back, 372 title: 'Main title', 373 subtitle: 'Subtitle', 374 // Configure the icon on the right. 375 menuItems: [ 376 { 377 value: $r('sys.media.ohos_ic_public_remove'), 378 isEnabled: true, 379 action: () => { 380 Prompt.showToast({ message: "show toast index 1" }); 381 } 382 }, 383 { 384 value: $r('sys.media.ohos_ic_public_remove'), 385 isEnabled: true, 386 defaultFocus: true, 387 action: () => { 388 Prompt.showToast({ message: "show toast index 2" }); 389 } 390 } 391 ], 392 onCancel: () => { 393 this.getUIContext()?.getRouter()?.back(); 394 }, 395 }) 396 } 397 .height('100%') 398 .width('100%') 399 } 400} 401``` 402 403 404### Example 6: Setting the Symbol Icon 405 406This example demonstrates how to use **symbolStyle** in **EditableTitleBarMenuItem** to set custom symbol icons. This functionality is supported since API version 18. 407 408```ts 409import { EditableLeftIconType, EditableTitleBar, Prompt, SymbolGlyphModifier } from '@kit.ArkUI'; 410 411@Entry 412@Component 413struct Index { 414 build() { 415 Row() { 416 Column() { 417 Divider().height(2).color(0xCCCCCC) 418 EditableTitleBar({ 419 leftIconStyle: EditableLeftIconType.Cancel, 420 title: 'Main title', 421 subtitle: 'Subtitle', 422 menuItems: [ 423 { 424 value: $r('sys.symbol.house'), 425 isEnabled: true, 426 action: () => { 427 Prompt.showToast({ message: 'show toast index 2' }); 428 } 429 }, 430 { 431 value: $r('sys.symbol.car'), 432 isEnabled: false, 433 } 434 ], 435 }) 436 Divider().height(2).color(0xCCCCCC) 437 EditableTitleBar({ 438 leftIconStyle: EditableLeftIconType.Back, 439 title: 'Main title', 440 subtitle: 'Subtitle', 441 imageItem: { 442 value: $r('sys.media.ohos_app_icon'), 443 isEnabled: true, 444 action: () => { 445 Prompt.showToast({ message: "show toast index 1" }); 446 } 447 }, 448 menuItems: [ 449 { 450 value: $r('sys.symbol.house'), 451 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.bell')).fontColor([Color.Red]), 452 isEnabled: true, 453 action: () => { 454 Prompt.showToast({ message: 'show toast index 2' }); 455 } 456 }, 457 { 458 value: $r('sys.symbol.car'), 459 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.heart')).fontColor([Color.Blue]), 460 isEnabled: false, 461 } 462 ], 463 }) 464 Divider().height(2).color(0xCCCCCC) 465 }.width('100%') 466 }.height('100%') 467 } 468} 469``` 470 471 472
