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