1# EditableTitleBar 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @fengluochenai--> 5<!--Designer: @YanSanzo--> 6<!--Tester: @tinygreyy--> 7<!--Adviser: @HelloCrease--> 8 9 10编辑型标题栏，适用于多选界面或者内容的编辑界面，一般采取左叉右勾的形式。 11 12 13> **说明：** 14> 15> 该组件从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 16> 17 18 19## 导入模块 20 21``` 22import { EditableTitleBar } from '@kit.ArkUI'; 23``` 24 25 26## 子组件 27 28无 29 30## 属性 31不支持[通用属性](ts-component-general-attributes.md)。 32 33 34## EditableTitleBar 35 36EditableTitleBar({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}) 37 38**装饰器类型：**\@Component 39 40**系统能力：** SystemCapability.ArkUI.ArkUI.Full 41 42**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 43 44| 名称 | 类型 | 必填 | 装饰器类型 | 说明 | 45| -------- | -------- | -------- | -------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 46| leftIconStyle | [EditableLeftIconType](#editablelefticontype) | 是 | - | 左侧按钮类型。<br />默认值：EditableLeftIconType.Back，表示返回。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 47| imageItem<sup>12+</sup> | [EditableTitleBarItem](#editabletitlebaritem12) | 否 | - | 用于左侧头像的单个菜单项目。<br />默认值：undefined。<br/>**说明：** 左侧头像不支持配置无障碍属性。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 48| title | [ResourceStr](ts-types.md#resourcestr) | 是 | - | 标题。<br />默认值：''，表示标题内容为空。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 49| subtitle<sup>12+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | - | 副标题。<br />默认值：''，表示副标题内容为空。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 50| menuItems | Array<[EditableTitleBarMenuItem](#editabletitlebarmenuitem)> | 否 | - | 右侧菜单项目列表。<br />默认值：undefined。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 51| isSaveIconRequired<sup>12+</sup> | boolean | 是 | - | 是否需要右侧的保存按钮。<br />默认值：true，表示需要右侧的保存按钮。<br/>**说明：** 未使用@Require装饰，构造时不强制校验参数。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 52| onSave | () => void | 否 | - | 点击保存时的事件。<br />默认值：() => void。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 53| onCancel | () => void | 否 | - | 当左侧按钮类型为 Cancel，触发取消时的事件。<br />默认值：() => void。<br />从API version 12开始，当左侧按钮类型为 Back，触发返回时的事件。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 54| options<sup>12+</sup> | [EditableTitleBarOptions](#editabletitlebaroptions12) | 是 | - | 标题样式。<br />默认值：<br />{<br />safeAreaTypes: [SafeAreaType.SYSTEM],<br />safeAreaEdges: [SafeAreaEdge.TOP], <br />backgroundColor: '#00000000'<br />}。<br/>**说明：** 未使用@Require装饰，构造时不强制校验参数。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 55| contentMargin<sup>12+</sup> | [LocalizedMargin](ts-types.md#localizedmargin12) | 否 | @Prop | 标题栏外边距，不支持设置负数。<br />默认值：<br /> {start: LengthMetrics.resource(`$r('sys.float.margin_left')`), end: LengthMetrics.resource(`$r('sys.float.margin_right')`)}。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 56| leftIconDefaultFocus<sup>18+</sup> | boolean | 否 | - | 左侧图标是否为默认焦点。<br />默认值：false，表示不是默认焦点。 <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 57| saveIconDefaultFocus<sup>18+</sup> | boolean | 否 | - | 保存图标是否为默认焦点。<br />默认值：false，表示不是默认焦点。 <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 58 59> **说明：** 60> 61> 入参对象不可为undefined，即`EditableTitleBar(undefined)`。 62> 若同时有多个可操作区域设置值默认焦点，则设置过默认焦点的可操作区域中显示顺序的第一个为默认焦点。 63 64## EditableLeftIconType 65 66**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 67 68**系统能力：** SystemCapability.ArkUI.ArkUI.Full 69 70**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 71 72| 名称 | 值 | 说明 | 73| -------- | -------- | -------- | 74| Back | 0 | 返回按钮。 | 75| Cancel | 1 | 取消按钮。 | 76 77## EditableTitleBarMenuItem 78 79**系统能力：** SystemCapability.ArkUI.ArkUI.Full 80 81**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 82 83| 名称 | 类型 | 必填 | 说明 | 84| -------- | -------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 85| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 图标资源。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 86| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-symbolglyphmodifier.md#symbolglyphmodifier) | 否 | Symbol图标资源，优先级大于value。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 87| label<sup>12+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 图标标签描述。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 88| isEnabled | boolean | 否 | 是否启用，默认启用。<br> isEnabled为true时，表示为启用。<br> isEnabled为false时，表示为禁用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 89| action | () => void | 否 | 标题栏右侧自定义按钮点击事件。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 90| accessibilityLevel<sup>18+<sup> | string | 否 | 标题栏右侧自定义按钮无障碍重要性。用于控制当前项是否可被无障碍辅助服务所识别。<br/>支持的值为：<br/>"auto"：当前组件会转换"yes"。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto"<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 91| accessibilityText<sup>18+<sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 标题栏右侧自定义按钮的无障碍文本属性。当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>默认值：有label默认值为当前项label属性内容，没有设置label时，默认值为“ ”。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 92| accessibilityDescription<sup>18+<sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 标题栏右侧自定义按钮的无障碍描述。此描述用于向用户详细解释当前组件，开发人员应为组件的这一属性提供较为详尽的文本说明，以协助用户理解即将执行的操作及其可能产生的后果。特别是当这些后果无法仅从组件的属性和无障碍文本中直接获知时。如果组件同时具备文本属性和无障碍说明属性，当组件被选中时，系统将首先播报组件的文本属性，随后播报无障碍说明属性的内容。<br/>默认值为“单指双击即可执行”。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 93| defaultFocus<sup>18+<sup> | boolean | 否 | 是否设置为默认获焦。<br/>true: 获焦 <br/>false: 不获焦 <br/>默认值：false <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 94 95## EditableTitleBarItem<sup>12+</sup> 96 97type EditableTitleBarItem = EditableTitleBarMenuItem 98 99**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 100 101**系统能力：** SystemCapability.ArkUI.ArkUI.Full 102 103**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 104 105| 类型 | 说明 | 106| -------- | -------- | 107| [EditableTitleBarMenuItem](#editabletitlebarmenuitem) | 左侧头像的单个菜单类型。 | 108 109## EditableTitleBarOptions<sup>12+</sup> 110 111**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 112 113**系统能力：** SystemCapability.ArkUI.ArkUI.Full 114 115**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 116 117| 名称 | 类型 | 必填 | 说明 | 118| -------- | -------- | -------- | -------- | 119| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 标题栏背景色。<br />默认值: '#00000000'| 120| backgroundBlurStyle | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | 否 | 标题栏背景模糊样式。<br />默认值: BlurStyle.NONE| 121| safeAreaTypes | Array <[SafeAreaType](ts-universal-attributes-expand-safe-area.md#safeareatype)> | 否 | 非必填，配置扩展安全区域的类型。<br />默认值: [SafeAreaType.SYSTEM] | 122| safeAreaEdges | Array <[SafeAreaEdge](ts-universal-attributes-expand-safe-area.md#safeareaedge)> | 否 | 非必填，配置扩展安全区域的方向。<br />默认值: [SafeAreaEdge.TOP] | 123 124## 事件 125不支持[通用事件](ts-component-general-events.md)。 126 127## 示例 128 129### 示例1（右侧图标自定义标题栏） 130 该示例主要演示EditableTitleBar设置左侧图标、主标题及自定义右侧图标区的效果。 131 132```ts 133import { EditableLeftIconType, EditableTitleBar, Prompt } from '@kit.ArkUI'; 134 135@Entry 136@Component 137struct Index { 138 build() { 139 Row() { 140 Column() { 141 Divider().height(2).color(0xCCCCCC) 142 // 左侧取消按钮，右侧保存按钮。 143 EditableTitleBar({ 144 leftIconStyle: EditableLeftIconType.Cancel, 145 title: '编辑页面', 146 menuItems: [], 147 onCancel: () => { 148 Prompt.showToast({ message: 'on cancel' }); 149 }, 150 onSave: () => { 151 Prompt.showToast({ message: 'on save' }); 152 } 153 }) 154 Divider().height(2).color(0xCCCCCC) 155 // 左侧返回按钮，右侧自定义取消按钮（disabled）、保存按钮。 156 EditableTitleBar({ 157 leftIconStyle: EditableLeftIconType.Back, 158 title: '编辑页面', 159 menuItems: [ 160 { 161 value: $r('sys.media.ohos_ic_public_cancel'), 162 isEnabled: false, 163 action: () => { 164 Prompt.showToast({ message: 'show toast index 2' }); 165 } 166 } 167 ], 168 onSave: () => { 169 Prompt.showToast({ message: 'on save' }) 170 } 171 }) 172 Divider().height(2).color(0xCCCCCC) 173 }.width('100%') 174 }.height('100%') 175 } 176} 177``` 178 179 180 181### 示例2（头像与背景模糊标题栏） 182该示例主要演示EditableTitleBar设置背景模糊、头像；取消右侧保存图标及自定义标题栏外边距的效果。 183 184```ts 185import { EditableLeftIconType, EditableTitleBar, LengthMetrics, Prompt } from '@kit.ArkUI'; 186 187@Entry 188@Component 189struct Index { 190 @State titleBarMargin: LocalizedMargin = { 191 start: LengthMetrics.vp(35), 192 end: LengthMetrics.vp(35), 193 }; 194 195 build() { 196 Row() { 197 Column() { 198 EditableTitleBar({ 199 leftIconStyle: EditableLeftIconType.Cancel, 200 title: '主标题', 201 subtitle: '副标题', 202 // 设置背景模糊效果 203 options: { 204 backgroundBlurStyle: BlurStyle.COMPONENT_THICK, 205 }, 206 onSave: () => { 207 Prompt.showToast({ message: "on save" }); 208 }, 209 }) 210 Divider().height(2).color(0xCCCCCC); 211 EditableTitleBar({ 212 leftIconStyle: EditableLeftIconType.Cancel, 213 title: '主标题', 214 subtitle: '副标题', 215 // 取消右侧保存按钮 216 isSaveIconRequired: false, 217 }) 218 Divider().height(2).color(0xCCCCCC); 219 EditableTitleBar({ 220 leftIconStyle: EditableLeftIconType.Back, 221 title: '主标题', 222 subtitle: '副标题', 223 isSaveIconRequired: false, 224 onCancel: () => { 225 this.getUIContext()?.getRouter()?.back(); 226 }, 227 }) 228 Divider().height(2).color(0xCCCCCC); 229 EditableTitleBar({ 230 leftIconStyle: EditableLeftIconType.Back, 231 title: '主标题', 232 subtitle: '副标题', 233 menuItems: [ 234 { 235 value: $r('sys.media.ohos_ic_public_remove'), 236 isEnabled: true, 237 action: () => { 238 Prompt.showToast({ message: "show toast index 1" }); 239 } 240 } 241 ], 242 isSaveIconRequired: false, 243 // 点击左侧Back图标，触发的动作。 244 onCancel: () => { 245 this.getUIContext()?.getRouter()?.back(); 246 }, 247 }) 248 Divider().height(2).color(0xCCCCCC); 249 EditableTitleBar({ 250 leftIconStyle: EditableLeftIconType.Back, 251 title: '主标题', 252 subtitle: '副标题', 253 // 设置可点击头像 254 imageItem: { 255 value: $r('sys.media.ohos_ic_normal_white_grid_image'), 256 isEnabled: true, 257 action: () => { 258 Prompt.showToast({ message: "show toast index 2" }); 259 } 260 }, 261 // 设置标题栏外边距 262 contentMargin: this.titleBarMargin, 263 // 右侧图标配置 264 menuItems: [ 265 { 266 value: $r('sys.media.ohos_ic_public_remove'), 267 isEnabled: true, 268 action: () => { 269 Prompt.showToast({ message: "show toast index 3" }); 270 } 271 } 272 ], 273 onCancel: () => { 274 this.getUIContext()?.getRouter()?.back(); 275 }, 276 }) 277 } 278 } 279 } 280} 281``` 282 283 284 285### 示例3（右侧自定义按钮播报） 286从API version 18开始，该示例通过设置标题栏的右侧自定义按钮属性accessibilityText、accessibilityDescription、accessibilityLevel自定义屏幕朗读播报文本。 287```ts 288 289import { Prompt, EditableLeftIconType, EditableTitleBar } from '@kit.ArkUI'; 290 291@Entry 292@Component 293struct Index1 { 294 build() { 295 Row() { 296 Column() { 297 Divider().height(2).color(0xCCCCCC) 298 EditableTitleBar({ 299 leftIconStyle: EditableLeftIconType.Cancel, 300 title: '编辑页面', 301 menuItems: [], 302 onCancel: () => { 303 Prompt.showToast({ message: 'on cancel' }); 304 }, 305 onSave: () => { 306 Prompt.showToast({ message: 'on save' }); 307 } 308 }) 309 Divider().height(2).color(0xCCCCCC) 310 EditableTitleBar({ 311 // 头像、自定义按钮不可用 312 leftIconStyle: EditableLeftIconType.Back, 313 title: '主标题', 314 subtitle: '副标题', 315 imageItem: { 316 value: $r('sys.media.ohos_ic_normal_white_grid_image'), 317 isEnabled: true, 318 action: () => { 319 Prompt.showToast({ message: "show toast index 1" }); 320 } 321 }, 322 menuItems: [ 323 { 324 value: $r('sys.media.ohos_ic_public_remove'), 325 label: '取消', 326 isEnabled: false, 327 accessibilityText: '删除', 328 accessibilityDescription: '点击即可删除', 329 action: () => { 330 Prompt.showToast({ message: "show toast index 2" }); 331 } 332 } 333 ], 334 onCancel: () => { 335 this.getUIContext()?.getRouter()?.back(); 336 }, 337 }) 338 Divider().height(2).color(0xCCCCCC) 339 } 340 } 341 } 342} 343``` 344 345 346### 示例4（左侧图标设置为默认焦点） 347从API version 18开始，该示例通过设置标题栏属性leftIconDefaultFocus使左侧图标默认获焦。 348```ts 349 350import { Prompt, EditableLeftIconType, EditableTitleBar } from '@kit.ArkUI'; 351 352@Entry 353@Component 354struct Index { 355 build() { 356 Column() { 357 EditableTitleBar({ 358 leftIconStyle: EditableLeftIconType.Back, 359 leftIconDefaultFocus: true, //设置左侧图标默认获焦。 360 title: '编辑页面', 361 menuItems: [], 362 onSave: () => { 363 Prompt.showToast({ message: 'on save' }); 364 } 365 }) 366 } 367 .height('100%') 368 .width('100%') 369 } 370} 371``` 372 373 374### 示例5（右侧自定义图标设置为默认焦点） 375从API version 18开始，该示例通过设置标题栏右侧图标属性defaultFocus使右侧图标默认获焦。 376```ts 377 378import { Prompt, EditableLeftIconType, EditableTitleBar } from '@kit.ArkUI'; 379 380@Entry 381@Component 382struct Index { 383 build() { 384 Column() { 385 EditableTitleBar({ 386 leftIconStyle: EditableLeftIconType.Back, 387 title: '主标题', 388 subtitle: '副标题', 389 // 右侧图标配置 390 menuItems: [ 391 { 392 value: $r('sys.media.ohos_ic_public_remove'), 393 isEnabled: true, 394 action: () => { 395 Prompt.showToast({ message: "show toast index 1" }); 396 } 397 }, 398 { 399 value: $r('sys.media.ohos_ic_public_remove'), 400 isEnabled: true, 401 defaultFocus: true, 402 action: () => { 403 Prompt.showToast({ message: "show toast index 2" }); 404 } 405 } 406 ], 407 onCancel: () => { 408 this.getUIContext()?.getRouter()?.back(); 409 }, 410 }) 411 } 412 .height('100%') 413 .width('100%') 414 } 415} 416``` 417 418 419### 示例6（设置Symbol类型图标） 420 421从API version 18开始，该示例通过设置EditableTitleBarMenuItem的属性symbolStyle，展示了自定义Symbol类型图标。 422 423```ts 424import { EditableLeftIconType, EditableTitleBar, Prompt, SymbolGlyphModifier } from '@kit.ArkUI'; 425 426@Entry 427@Component 428struct Index { 429 build() { 430 Row() { 431 Column() { 432 Divider().height(2).color(0xCCCCCC) 433 EditableTitleBar({ 434 leftIconStyle: EditableLeftIconType.Cancel, 435 title: '主标题', 436 subtitle: '副标题', 437 menuItems: [ 438 { 439 value: $r('sys.symbol.house'), 440 isEnabled: true, 441 action: () => { 442 Prompt.showToast({ message: 'show toast index 2' }); 443 } 444 }, 445 { 446 value: $r('sys.symbol.car'), 447 isEnabled: false, 448 } 449 ], 450 }) 451 Divider().height(2).color(0xCCCCCC) 452 EditableTitleBar({ 453 leftIconStyle: EditableLeftIconType.Back, 454 title: '主标题', 455 subtitle: '副标题', 456 imageItem: { 457 value: $r('sys.media.ohos_app_icon'), 458 isEnabled: true, 459 action: () => { 460 Prompt.showToast({ message: "show toast index 1" }); 461 } 462 }, 463 menuItems: [ 464 { 465 value: $r('sys.symbol.house'), 466 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.bell')).fontColor([Color.Red]), 467 isEnabled: true, 468 action: () => { 469 Prompt.showToast({ message: 'show toast index 2' }); 470 } 471 }, 472 { 473 value: $r('sys.symbol.car'), 474 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.heart')).fontColor([Color.Blue]), 475 isEnabled: false, 476 } 477 ], 478 }) 479 Divider().height(2).color(0xCCCCCC) 480 }.width('100%') 481 }.height('100%') 482 } 483} 484``` 485 486
