1# SelectTitleBar 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 { SelectTitleBar } from '@kit.ArkUI'; 23``` 24 25 26## 子组件 27 28无 29 30## 属性 31不支持[通用属性](ts-component-general-attributes.md)。 32 33## SelectTitleBar 34 35SelectTitleBar({selected: number, options: Array<SelectOption>, menuItems?: Array<SelectTitleBarMenuItem>, subtitle?: ResourceStr, badgeValue?: number, hidesBackButton?: boolean, onSelected?: ((index: number) => void)}) 36 37**装饰器类型：**\@Component 38 39**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.ArkUI.ArkUI.Full 42 43**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 44 45| 名称 | 类型 | 必填 | 装饰器类型 | 说明 | 46| -------- | -------- | -------- | -------- | -------- | 47| selected | number | 是 | \@Prop | 当前选中项目的索引。<br>第一项的索引为0。如果不设置该属性，则默认值为0。 | 48| options | Array<[SelectOption](ts-basic-components-select.md#selectoption对象说明)> | 是 | - | 下拉菜单中的项目。 | 49| menuItems | Array<[SelectTitleBarMenuItem](#selecttitlebarmenuitem)> | 否 | - | 右侧菜单项目列表，定义标题栏右侧的菜单项目。 | 50| subtitle | [ResourceStr](ts-types.md#resourcestr) | 否 | - | 子标题。 | 51| badgeValue | number | 否 | - | 新事件标记。<br>取值范围：[-2147483648,2147483647]，超出范围时会加上或减去4294967296，使得值仍在范围内，非整数时会舍去小数部分取整数部分，如5.5取5。<br>**说明：** 小于等于0时不显示信息标记。<br>最大消息数99，超过最大消息时仅显示99+。超大数值属于异常值，不显示信息标记。 | 52| hidesBackButton | boolean | 否 | - | 是否隐藏左侧的返回箭头。<br>默认值：false。true：隐藏，false：显示。| 53| onSelected | ((index: number) => void) | 否 | - | 下拉菜单项目选中触发的回调函数，传入选中项的索引。 | 54 55> **说明：** 56> 57> 入参对象不可为undefined，即`SelectTitleBar(undefined)`。 58 59## SelectTitleBarMenuItem 60 61**系统能力：** SystemCapability.ArkUI.ArkUI.Full 62 63**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 64 65| 名称 | 类型 | 必填 | 说明 | 66| -------- | -------- | -------- | -------- | 67| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 图标资源。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 68| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-symbolglyphmodifier.md#symbolglyphmodifier) | 否 | Symbol图标资源，优先级大于value。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 69| label<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 图标标签描述。<br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 70| isEnabled | boolean | 否 | 是否启用。<br>默认值：false。true：启用，false：禁用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 71| action | () => void | 否 | 触发时的动作闭包。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 72| accessibilityLevel<sup>18+<sup> | string | 否 | 标题栏右侧自定义按钮无障碍重要性。用于控制当前项是否可被无障碍辅助服务所识别。<br/>支持的值为：<br/>"auto"：当前组件会转换'yes'。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto"。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 73| accessibilityText<sup>18+<sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 标题栏右侧自定义按钮的无障碍文本属性。当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>默认值：有label默认值为当前项label属性内容，没有设置label时，默认值为“ ”。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 74| accessibilityDescription<sup>18+<sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 标题栏右侧自定义按钮的无障碍描述。此描述用于向用户详细解释当前组件，开发人员应为组件的这一属性提供较为详尽的文本说明，以协助用户理解即将执行的操作及其可能产生的后果。特别是当这些后果无法仅从组件的属性和无障碍文本中直接获知时。如果组件同时具备文本属性和无障碍说明属性，当组件被选中时，系统将首先播报组件的文本属性，随后播报无障碍说明属性的内容。<br/>默认值为“单指双击即可执行”。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 75 76## 事件 77不支持[通用事件](ts-component-general-events.md)。 78 79## 示例 80 81### 示例1（下拉菜单标题栏） 82该示例实现了简单的下拉菜单标题栏，带有返回箭头的下拉菜单标题栏和带有右侧菜单项目列表的下拉菜单标题栏。 83```ts 84import { SelectTitleBar, Prompt, SelectTitleBarMenuItem } from '@kit.ArkUI'; 85 86@Entry 87@Component 88struct Index { 89 // 定义右侧菜单项目列表 90 private menuItems: Array<SelectTitleBarMenuItem> = 91 [ 92 { 93 // 菜单图片资源 94 value: $r('sys.media.ohos_save_button_filled'), 95 // 启用图片 96 isEnabled: true, 97 // 点击菜单时触发事件 98 action: () => Prompt.showToast({ message: 'show toast index 1' }), 99 }, 100 { 101 value: $r('sys.media.ohos_ic_public_copy'), 102 isEnabled: true, 103 action: () => Prompt.showToast({ message: 'show toast index 2' }), 104 }, 105 { 106 value: $r('sys.media.ohos_ic_public_edit'), 107 isEnabled: true, 108 action: () => Prompt.showToast({ message: 'show toast index 3' }), 109 }, 110 { 111 value: $r('sys.media.ohos_ic_public_remove'), 112 isEnabled: true, 113 action: () => Prompt.showToast({ message: 'show toast index 4' }), 114 }, 115 ] 116 117 build() { 118 Row() { 119 Column() { 120 Divider().height(2).color(0xCCCCCC) 121 SelectTitleBar({ 122 // 定义下拉列表选项 123 options: [ 124 { value: '所有照片' }, 125 { value: '本地（设备）' }, 126 { value: '本地本地本地本地本地（储存卡）' } 127 ], 128 // 初始选择第一个下拉选项 129 selected: 0, 130 // 选中时触发函数 131 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 132 // 隐藏左侧返回箭头 133 hidesBackButton: true, 134 }) 135 Divider().height(2).color(0xCCCCCC) 136 SelectTitleBar({ 137 options: [ 138 { value: '所有照片' }, 139 { value: '本地（设备）' }, 140 { value: '本地本地本地本地本地（储存卡）' }, 141 ], 142 selected: 0, 143 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 144 hidesBackButton: false, 145 }) 146 Divider().height(2).color(0xCCCCCC) 147 SelectTitleBar({ 148 options: [ 149 { value: '所有照片' }, 150 { value: '本地（设备）' }, 151 { value: '本地本地本地本地本地（储存卡）' }, 152 ], 153 selected: 1, 154 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 155 subtitle: 'example@example.com', 156 }) 157 Divider().height(2).color(0xCCCCCC) 158 SelectTitleBar({ 159 options: [ 160 { value: '所有照片' }, 161 { value: '本地（设备）' }, 162 { value: '本地本地本地本地本地（储存卡）' }, 163 ], 164 selected: 1, 165 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 166 subtitle: 'example@example.com', 167 menuItems: [{ isEnabled: true, value: $r('sys.media.ohos_save_button_filled'), 168 action: () => Prompt.showToast({ message: 'show toast index 1' }), 169 }], 170 }) 171 Divider().height(2).color(0xCCCCCC) 172 SelectTitleBar({ 173 options: [ 174 { value: '所有照片' }, 175 { value: '本地（设备）' }, 176 { value: '本地本地本地本地本地（储存卡）' }, 177 ], 178 selected: 0, 179 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 180 subtitle: 'example@example.com', 181 menuItems: this.menuItems, 182 badgeValue: 99, 183 hidesBackButton: true, 184 }) 185 Divider().height(2).color(0xCCCCCC) 186 }.width('100%') 187 }.height('100%') 188 } 189} 190``` 191 192 193 194### 示例2（右侧自定义按钮播报） 195从API version 18开始，该示例通过设置标题栏右侧自定义按钮属性accessibilityText、accessibilityDescription、accessibilityLevel自定义屏幕朗读播报文本。 196```ts 197import { SelectTitleBar, Prompt, SelectTitleBarMenuItem } from '@kit.ArkUI'; 198 199@Entry 200@Component 201struct Index { 202 // 定义右侧菜单项目列表 203 private menuItems: Array<SelectTitleBarMenuItem> = 204 [ 205 { 206 // 菜单图片资源 207 value: $r('sys.media.ohos_save_button_filled'), 208 // 启用图片 209 isEnabled: true, 210 // 点击菜单时触发事件 211 action: () => Prompt.showToast({ message: 'show toast index 1' }), 212 // 屏幕朗读播报文本，优先级比label高 213 accessibilityText: '保存', 214 // 屏幕朗读是否可以聚焦到 215 accessibilityLevel: 'yes', 216 // 屏幕朗读最后播报的描述文本 217 accessibilityDescription: '点击操作保存图标', 218 }, 219 { 220 value: $r('sys.media.ohos_ic_public_copy'), 221 isEnabled: true, 222 action: () => Prompt.showToast({ message: 'show toast index 2' }), 223 accessibilityText: '复制', 224 // 此处为no，屏幕朗读不聚焦 225 accessibilityLevel: 'no', 226 accessibilityDescription: '点击操作复制图标', 227 }, 228 { 229 value: $r('sys.media.ohos_ic_public_edit'), 230 isEnabled: true, 231 action: () => Prompt.showToast({ message: 'show toast index 3' }), 232 accessibilityText: '编辑', 233 accessibilityLevel: 'yes', 234 accessibilityDescription: '点击操作编辑图标', 235 }, 236 { 237 value: $r('sys.media.ohos_ic_public_remove'), 238 isEnabled: true, 239 action: () => Prompt.showToast({ message: "show toast index 4" }), 240 accessibilityText: '移除', 241 accessibilityLevel: 'yes', 242 accessibilityDescription: '点击操作移除图标', 243 } 244 ] 245 246 build() { 247 Row() { 248 Column() { 249 Divider().height(2).color(0xCCCCCC) 250 SelectTitleBar({ 251 // 定义下拉列表选项 252 options: [ 253 { value: '所有照片' }, 254 { value: '本地（设备）' }, 255 { value: '本地本地本地本地本地（储存卡）' }, 256 ], 257 // 初始选择第一个下拉选项 258 selected: 0, 259 // 选中时触发函数 260 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 261 // 隐藏左侧返回箭头 262 hidesBackButton: true, 263 }) 264 Divider().height(2).color(0xCCCCCC) 265 SelectTitleBar({ 266 options: [ 267 { value: '所有照片' }, 268 { value: '本地（设备）' }, 269 { value: '本地本地本地本地本地（储存卡）' }, 270 ], 271 selected: 0, 272 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 273 hidesBackButton: false, 274 }) 275 Divider().height(2).color(0xCCCCCC) 276 SelectTitleBar({ 277 options: [ 278 { value: '所有照片' }, 279 { value: '本地（设备）' }, 280 { value: '本地本地本地本地本地（储存卡）' }, 281 ], 282 selected: 1, 283 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 284 subtitle: 'example@example.com', 285 }) 286 Divider().height(2).color(0xCCCCCC) 287 SelectTitleBar({ 288 options: [ 289 { value: '所有照片' }, 290 { value: '本地（设备）' }, 291 { value: '本地本地本地本地本地（储存卡）' }, 292 ], 293 selected: 1, 294 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 295 subtitle: 'example@example.com', 296 menuItems: [{ isEnabled: true, value: $r('sys.media.ohos_save_button_filled'), 297 action: () => Prompt.showToast({ message: 'show toast index 1' }), 298 }], 299 }) 300 Divider().height(2).color(0xCCCCCC) 301 SelectTitleBar({ 302 options: [ 303 { value: '所有照片' }, 304 { value: '本地（设备）' }, 305 { value: '本地本地本地本地本地（储存卡）' }, 306 ], 307 selected: 0, 308 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 309 subtitle: 'example@example.com', 310 menuItems: this.menuItems, 311 badgeValue: 99, 312 hidesBackButton: true, 313 }) 314 Divider().height(2).color(0xCCCCCC) 315 }.width('100%') 316 }.height('100%') 317 } 318} 319``` 320 321 322### 示例3（设置Symbol类型图标） 323从API version 18开始，该示例通过设置SelectTitleBarMenuItem的属性symbolStyle，展示了自定义Symbol类型图标。 324```ts 325import { SelectTitleBar, Prompt, SelectTitleBarMenuItem, SymbolGlyphModifier } from '@kit.ArkUI'; 326 327@Entry 328@Component 329struct Index { 330 // 定义右侧菜单项目列表 331 private menuItems: Array<SelectTitleBarMenuItem> = 332 [ 333 { 334 // 菜单图片资源 335 value: $r('sys.media.ohos_save_button_filled'), 336 // 菜单图片symbol资源 337 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.save')), 338 // 启用图片 339 isEnabled: true, 340 // 点击菜单时触发事件 341 action: () => Prompt.showToast({ message: 'show toast index 1' }), 342 // 屏幕朗读播报文本，优先级比label高 343 accessibilityText: '保存', 344 // 屏幕朗读是否可以聚焦到 345 accessibilityLevel: 'yes', 346 // 屏幕朗读最后播报的描述文本 347 accessibilityDescription: '点击操作保存图标', 348 }, 349 { 350 value: $r('sys.media.ohos_ic_public_copy'), 351 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.car')), 352 isEnabled: true, 353 action: () => Prompt.showToast({ message: 'show toast index 2' }), 354 accessibilityText: '复制', 355 // 此处为no，屏幕朗读不聚焦 356 accessibilityLevel: 'no', 357 accessibilityDescription: '点击操作复制图标', 358 }, 359 { 360 value: $r('sys.media.ohos_ic_public_edit'), 361 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.ai_edit')), 362 isEnabled: true, 363 action: () => Prompt.showToast({ message: 'show toast index 3' }), 364 accessibilityText: '编辑', 365 accessibilityLevel: 'yes', 366 accessibilityDescription: '点击操作编辑图标', 367 }, 368 { 369 value: $r('sys.media.ohos_ic_public_remove'), 370 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.remove_songlist')), 371 isEnabled: true, 372 action: () => Prompt.showToast({ message: "show toast index 4" }), 373 accessibilityText: '移除', 374 accessibilityLevel: 'yes', 375 accessibilityDescription: '点击操作移除图标', 376 } 377 ] 378 379 build() { 380 Row() { 381 Column() { 382 Divider().height(2).color(0xCCCCCC) 383 SelectTitleBar({ 384 // 定义下拉列表选项 385 options: [ 386 { value: '所有照片' }, 387 { value: '本地（设备）' }, 388 { value: '本地本地本地本地本地（储存卡）' }, 389 ], 390 // 初始选择第一个下拉选项 391 selected: 0, 392 // 选中时触发函数 393 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 394 // 隐藏左侧返回箭头 395 hidesBackButton: true, 396 }) 397 Divider().height(2).color(0xCCCCCC) 398 SelectTitleBar({ 399 options: [ 400 { value: '所有照片' }, 401 { value: '本地（设备）' }, 402 { value: '本地本地本地本地本地（储存卡）' }, 403 ], 404 selected: 0, 405 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 406 hidesBackButton: false, 407 }) 408 Divider().height(2).color(0xCCCCCC) 409 SelectTitleBar({ 410 options: [ 411 { value: '所有照片' }, 412 { value: '本地（设备）' }, 413 { value: '本地本地本地本地本地（储存卡）' }, 414 ], 415 selected: 1, 416 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 417 subtitle: 'example@example.com', 418 }) 419 Divider().height(2).color(0xCCCCCC) 420 SelectTitleBar({ 421 options: [ 422 { value: '所有照片' }, 423 { value: '本地（设备）' }, 424 { value: '本地本地本地本地本地（储存卡）' }, 425 ], 426 selected: 1, 427 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 428 subtitle: 'example@example.com', 429 menuItems: [{ 430 isEnabled: true, value: $r('sys.media.ohos_save_button_filled'), 431 action: () => Prompt.showToast({ message: 'show toast index 1' }), 432 }], 433 }) 434 Divider().height(2).color(0xCCCCCC) 435 SelectTitleBar({ 436 options: [ 437 { value: '所有照片' }, 438 { value: '本地（设备）' }, 439 { value: '本地本地本地本地本地（储存卡）' }, 440 ], 441 selected: 0, 442 onSelected: (index) => Prompt.showToast({ message: 'page index ' + index }), 443 subtitle: 'example@example.com', 444 menuItems: this.menuItems, 445 badgeValue: 99, 446 hidesBackButton: true, 447 }) 448 Divider().height(2).color(0xCCCCCC) 449 }.width('100%') 450 }.height('100%') 451 } 452} 453``` 454
