1# SubHeader 2 3 4子标题，用于列表项顶部，将该组列表划分为一个区块，子标题名称用来概括该区块内容。也可以用于内容项顶部，子标题名称用来概括该区块内容。 5 6 7> **说明：** 8> 9> 该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 10> 11> 该组件不支持在Wearable设备上使用。 12 13 14## 导入模块 15 16```ts 17import { SubHeader } from '@kit.ArkUI'; 18``` 19 20 21## 子组件 22 23无 24 25## 属性 26 27不支持[通用属性](ts-component-general-attributes.md)。 28 29> **说明：** 30> 31> 不支持设置文本相关。 32 33## SubHeader 34 35SubHeader({icon?: ResourceStr, iconSymbolOptions?: SymbolOptions, primaryTitle?: ResourceStr, secondaryTitle?: 36ResourceStr, select?: SelectOptions, operationType?: OperationType, operationItem?: Array<OperationOption>, 37operationSymbolOptions?: Array<SymbolOptions>, primaryTitleModifier?: TextModifier, secondaryTitleModifier?: 38TextModifier, titleBuilder?: () => void, contentMargin?: LocalizedMargin, contentPadding?: LocalizedPadding}) 39 40**装饰器类型：**\@Component 41 42**系统能力：** SystemCapability.ArkUI.ArkUI.Full 43 44| 名称 | 类型 | 必填 | 装饰器类型 | 说明 | 45| -------- | -------- | -------- |---------------| -------- | 46| icon | [ResourceStr](ts-types.md#resourcestr) | 否 | \@Prop | 图标设置项。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 47| iconSymbolOptions<sup>12+</sup> | [SymbolOptions](#symboloptions12) | 否 | - | icon为[Symbol资源](ts-basic-components-symbolGlyph.md)时的设置项。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 48| primaryTitle | [ResourceStr](ts-types.md#resourcestr) | 否 | \@Prop | 标题内容。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 49| secondaryTitle | [ResourceStr](ts-types.md#resourcestr) | 否 | \@Prop | 副标题内容。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 50| select | [SelectOptions](#selectoptions) | 否 | - | select内容以及事件。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 51| operationType | [OperationType](#operationtype) | 否 | \@Prop | 操作区(右侧)元素样式。<br/>默认值：OperationType.BUTTON<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 52| operationItem | Array<[OperationOption](#operationoption)> | 否 | - | 操作区（右侧）的设置项。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 53| operationSymbolOptions<sup>12+</sup> | Array<[SymbolOptions](#symboloptions12)> | 否 | - | operationType为OperationType.ICON_GROUP，<br/>operationItem设置多个图标，图标为[Symbol资源](ts-basic-components-symbolGlyph.md)时的设置项。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 54| primaryTitleModifier<sup>12+</sup> | [TextModifier](ts-universal-attributes-attribute-modifier.md) | 否 | - | 设置标题文本属性，如设置标题颜色、字体大小、字重等。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 55| secondaryTitleModifier<sup>12+</sup> | [TextModifier](ts-universal-attributes-attribute-modifier.md) | 否 | - | 设置副标题文本属性，如设置标题颜色、字体大小、字重等。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 56| titleBuilder<sup>12+</sup> | () => void | 否 | @BuilderParam | 自定义标题区内容<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 57| contentMargin<sup>12+</sup> | [LocalizedMargin](ts-types.md#localizedmargin12) | 否 | @Prop | 子标题外边距，不支持设置负数。<br />默认值：<br /> `{start: LengthMetrics.resource(` <br /> `$r('sys.float.margin_left'))`, <br /> `end: LengthMetrics.resource(` <br /> `$r('sys.float.margin_right'))}`<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 58| contentPadding<sup>12+</sup> | [LocalizedPadding](ts-types.md#localizedpadding12) | 否 | @Prop | 子标题内边距。<br />默认值：<br />左侧为副标题或副标题加图标时：<br /> {start: LengthMetrics.vp(12), end: LengthMetrics.vp(12)}。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 59 60 61## OperationType 62 63**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 64 65**系统能力：** SystemCapability.ArkUI.ArkUI.Full 66 67| 名称 | 值 | 说明 | 68| -------- | -------- | -------- | 69| TEXT_ARROW | 0 | 文本按钮（带右箭头）。 | 70| BUTTON | 1 | 文本按钮（不带右箭头）。 | 71| ICON_GROUP | 2 | 图标按钮（最多支持配置三张图标）。 | 72| LOADING | 3 | 加载动画。 | 73 74## SelectOptions 75 76**系统能力：** SystemCapability.ArkUI.ArkUI.Full 77 78| 名称 | 类型 | 必填 | 说明 | 79| -------- | -------- | -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------| 80| options | Array<[SelectOption](ts-basic-components-select.md#selectoption对象说明)> | 是 | 下拉选项内容。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 81| selected | number | 否 | 设置下拉菜单初始选项的索引。<br/>取值范围：大于等于-1。<br/>第一项的索引为0。<br/>当不设置selected属性时，默认选择值为-1，菜单项不选中。<br/>若设置数值小于-1，按不选中处理。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 82| value | string | 否 | 设置下拉按钮本身的文本内容。<br/>默认值：空字符串。<br/>**说明**：如果文本大于列宽时，文本被截断。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 83| onSelect | (index: number, value?: string) => void | 否 | 下拉菜单选中某一项的回调。<br/>- index：选中项的索引。<br/>- value：选中项的值。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 84| defaultFocus<sup>18+</sup> | boolean | 否 | 下拉按钮是否为默认焦点。<br/>true：下拉按钮是默认焦点。<br/>false：下拉按钮不是默认焦点。<br />默认值：false <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 85 86## OperationOption 87 88**系统能力：** SystemCapability.ArkUI.ArkUI.Full 89 90| 名称 | 类型 | 必填 | 说明 | 91| -------- | -------- | -------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 92| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 文本内容。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 93| action | ()=>void | 否 | 事件。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 94| accessibilityLevel<sup>18+<sup> | string | 否 | 子标题右侧按钮无障碍重要性。用于控制当前项是否可被无障碍辅助服务所识别。<br/>支持的值为：<br/>"auto"：当前组件会转换'yes'。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto"。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 95| accessibilityText<sup>18+<sup> | ResourceStr | 否 | 子标题右侧按钮的无障碍文本属性。当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>默认值：类型为TEXT_ARROW和BUTTON时默认值为当前项value属性内容，其他类型默认值为“ ”。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 96| accessibilityDescription<sup>18+<sup> | ResourceStr | 否 | 子标题右侧按钮的无障碍描述。此描述用于向用户详细解释当前组件，开发人员应为组件的这一属性提供较为详尽的文本说明，以协助用户理解即将执行的操作及其可能产生的后果。特别是当这些后果无法仅从组件的属性和无障碍文本中直接获知时。如果组件同时具备文本属性和无障碍说明属性，当组件被选中时，系统将首先播报组件的文本属性，随后播报无障碍说明属性的内容。<br/>默认值：类型为LOADING时，默认值为“正在加载”，其他类型默认值为“单指双击即可执行”。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 97| defaultFocus<sup>18+</sup> | boolean | 否 | 子标题右侧按钮是否为默认焦点。<br/>true：子标题右侧按钮是默认焦点。<br/>false：子标题右侧按钮不是默认焦点。<br />默认值：false <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 98## SymbolOptions<sup>12+</sup> 99 100**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 101 102**系统能力：** SystemCapability.ArkUI.ArkUI.Full 103 104| 名称 | 类型 | 必填 | 说明 | 105| -------- | -------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 106| fontColor | Array<[ResourceColor](ts-types.md#resourcecolor)> | 否 | 设置[Symbol资源](ts-basic-components-symbolGlyph.md)颜色。<br/>默认值：不同渲染策略下默认值不同。 | 107| fontSize | number \|string \|[Resource](ts-types.md#Resource) | 否 | 设置[Symbol资源](ts-basic-components-symbolGlyph.md)大小。<br/>取值范围：大于等于0。<br/>默认值：系统默认值。 | 108| fontWeight | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | 否 | 设置[Symbol资源](ts-basic-components-symbolGlyph.md)粗细。<br/>number类型取值[100,900]，取值间隔为100，默认为400，取值越大，字体越粗。<br/>string类型仅支持number类型取值的字符串形式，例如“400”，以及“bold”、“bolder”、“lighter”、“regular” 、“medium”分别对应FontWeight中相应的枚举值。<br/>默认值：FontWeight.Normal。 | 109| renderingStrategy | [SymbolRenderingStrategy](ts-basic-components-symbolGlyph.md#symbolrenderingstrategy11枚举说明) | 否 | 设置[Symbol资源](ts-basic-components-symbolGlyph.md)渲染策略。<br/>默认值：SymbolRenderingStrategy.SINGLE。<br/>**说明：**<br/>$r('sys.symbol.ohos_*')中引用的资源仅ohos_trash_circle、ohos_folder_badge_plus、ohos_lungs支持分层与多色模式。 | 110| effectStrategy | [SymbolEffectStrategy](ts-basic-components-symbolGlyph.md#symboleffectstrategy11枚举说明) | 否 | 设置[Symbol资源](ts-basic-components-symbolGlyph.md)动效策略。<br/>默认值：SymbolEffectStrategy.NONE。<br/>**说明：**<br/>$r('sys.symbol.ohos_*')中引用的资源仅ohos_wifi支持层级动效模式。 | 111 112## 事件 113不支持[通用事件](ts-component-general-events.md)。 114 115## 示例 116### 示例1（效率型子标题） 117该示例主要演示子标题左侧为icon、secondaryTitle，右侧operationType为按钮类型。 118 119```ts 120import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 121 122@Entry 123@Component 124struct SubHeaderExample { 125 build() { 126 Column() { 127 SubHeader({ 128 icon: $r('sys.media.ohos_ic_public_email'), 129 secondaryTitle: '二级标题', 130 operationType: OperationType.BUTTON, 131 operationItem: [{ 132 value: '操作', 133 action: () => { 134 Prompt.showToast({ message: 'demo' }); 135 } 136 }] 137 }) 138 } 139 } 140} 141``` 142 143 144 145### 示例2（双行文本内容型子标题） 146该示例主要演示子标题左侧为primaryTitle、secondaryTitle，右侧operationType类型为TEXT_ARROW。 147 148```ts 149import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 150 151@Entry 152@Component 153struct SubHeaderExample { 154 build() { 155 Column() { 156 SubHeader({ 157 primaryTitle: '一级标题', 158 secondaryTitle: '二级标题', 159 operationType: OperationType.TEXT_ARROW, 160 operationItem: [{ 161 value: '更多', 162 action: () => { 163 Prompt.showToast({ message: 'demo' }); 164 } 165 }] 166 }) 167 } 168 } 169} 170``` 171 172 173 174### 示例3（spinner型内容型子标题） 175该示例主要演示子标题左侧为select，右侧operationType类型为ICON_GROUP。 176 177```ts 178import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 179 180@Entry 181@Component 182struct SubHeaderExample { 183 build() { 184 Column() { 185 SubHeader({ 186 // 左侧为select选择器 187 select: { 188 options: [{ value: 'aaa' }, { value: 'bbb' }, { value: 'ccc' }], 189 value: 'selectDemo', 190 selected: 2, 191 onSelect: () => { 192 Prompt.showToast({ message: 'demo' }); 193 } 194 }, 195 operationType: OperationType.ICON_GROUP, 196 // 右侧为三个icon图标 197 operationItem: [{ 198 value: $r('sys.media.ohos_ic_public_email'), 199 action: () => { 200 Prompt.showToast({ message: 'demo' }) 201 } 202 }, { 203 value: $r('sys.media.ohos_ic_public_email'), 204 action: () => { 205 Prompt.showToast({ message: 'demo' }); 206 } 207 }, { 208 value: $r('sys.media.ohos_ic_public_email'), 209 action: () => { 210 Prompt.showToast({ message: 'demo' }); 211 } 212 }] 213 }) 214 } 215 } 216} 217``` 218 219 220 221### 示例4（设置左侧symbol图标） 222该示例主要演示子标题左侧icon设置symbol图标。 223 224```ts 225 226import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 227 228@Entry 229@Component 230struct SubHeaderExample { 231 build() { 232 Column() { 233 SubHeader({ 234 // 设置icon为symbol图标 235 icon: $r('sys.symbol.ohos_wifi'), 236 iconSymbolOptions: { 237 effectStrategy: SymbolEffectStrategy.HIERARCHICAL, 238 }, 239 secondaryTitle: '标题', 240 operationType: OperationType.BUTTON, 241 operationItem: [{ 242 value: '操作', 243 action: () => { 244 Prompt.showToast({ message: 'demo' }); 245 } 246 }] 247 }) 248 } 249 } 250} 251``` 252 253 254 255### 示例5（设置右侧symbol图标） 256该示例主要演示子标题operationType设置为OperationType.ICON_GROUP，operationItem的value设置为symbol图标。 257 258```ts 259import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 260 261@Entry 262@Component 263struct SubHeaderExample { 264 build() { 265 Column() { 266 SubHeader({ 267 // 设置左侧select 268 select: { 269 options: [{ value: 'aaa' }, { value: 'bbb' }, { value: 'ccc' }], 270 value: 'selectDemo', 271 selected: 2, 272 onSelect: () => { 273 Prompt.showToast({ message: 'demo' }); 274 } 275 }, 276 operationType: OperationType.ICON_GROUP, 277 // 设置右侧icon 278 operationItem: [{ 279 value: $r('sys.symbol.ohos_lungs'), 280 action: () => { 281 Prompt.showToast({ message: 'icon1' }); 282 } 283 }, { 284 value: $r('sys.symbol.ohos_lungs'), 285 action: () => { 286 Prompt.showToast({ message: 'icon2' }); 287 } 288 }, { 289 value: $r('sys.symbol.ohos_lungs'), 290 action: () => { 291 Prompt.showToast({ message: 'icon3' }); 292 } 293 }], 294 // 设置右侧icon图标symbol样式 295 operationSymbolOptions: [{ 296 fontWeight: FontWeight.Lighter, 297 }, { 298 renderingStrategy: SymbolRenderingStrategy.MULTIPLE_COLOR, 299 fontColor: [Color.Blue, Color.Grey, Color.Green], 300 }, { 301 renderingStrategy: SymbolRenderingStrategy.MULTIPLE_OPACITY, 302 fontColor: [Color.Blue, Color.Grey, Color.Green], 303 }] 304 }) 305 } 306 } 307} 308``` 309 310 311 312### 示例6（自定义标题内容） 313 该示例主要演示SubHeader设置titleBuilder自定义标题内容的效果。 314 315```ts 316import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 317 318@Entry 319@Component 320struct SubHeaderExample { 321 // 自定义左侧标题 322 @Builder 323 TitleBuilder(): void { 324 Text('自定义标题') 325 .fontSize(24) 326 .fontColor(Color.Blue) 327 .fontWeight(FontWeight.Bold) 328 } 329 330 build() { 331 Column() { 332 SubHeader({ 333 // 调用TitleBuilder 334 titleBuilder: () => { 335 this.TitleBuilder(); 336 }, 337 primaryTitle: '一级标题', 338 secondaryTitle: '二级标题', 339 icon: $r('sys.symbol.ohos_star'), 340 operationType: OperationType.TEXT_ARROW, 341 operationItem: [{ 342 value: '更多信息', 343 action: () => { 344 Prompt.showToast({ message: 'demo' }); 345 } 346 }] 347 }) 348 } 349 } 350} 351``` 352 353 354### 示例7（自定义标题样式） 355该示例主要演示SubHeader设置标题和副标题字体样式以及标题内外边距的效果。 356 357```ts 358import { Prompt, OperationType, SubHeader, LengthMetrics, TextModifier } from '@kit.ArkUI'; 359 360@Entry 361@Component 362struct SubHeaderExample { 363 // 设置主副标题文本颜色 364 @State primaryModifier: TextModifier = new TextModifier().fontColor(Color.Blue); 365 @State secondaryModifier: TextModifier = new TextModifier().fontColor(Color.Blue); 366 367 build() { 368 Column() { 369 SubHeader({ 370 primaryTitle: 'primaryTitle', 371 secondaryTitle: 'secondaryTitle', 372 primaryTitleModifier: this.primaryModifier, 373 secondaryTitleModifier: this.secondaryModifier, 374 operationType: OperationType.TEXT_ARROW, 375 operationItem: [{ 376 value: '更多信息', 377 action: () => { 378 Prompt.showToast({ message: 'demo' }); 379 } 380 }], 381 // 标题内外间距 382 contentMargin: { start: LengthMetrics.vp(20), end: LengthMetrics.vp(20) }, 383 contentPadding: { start: LengthMetrics.vp(20), end: LengthMetrics.vp(20) } 384 }) 385 } 386 } 387} 388``` 389 390 391 392 393### 示例8（右侧按钮自定义播报） 394该示例通过设置subheader的右侧按钮属性accessibilityText、accessibilityDescription、accessibilityLevel自定义屏幕朗读播报文本。 395```ts 396import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 397 398@Entry 399@Component 400struct SubHeaderExample { 401 build() { 402 Column() { 403 Divider().color('grey').width('100%').height('2vp') 404 SubHeader({ 405 // 图标+二级标题, 右侧button 406 icon: $r('sys.media.ohos_ic_public_email'), 407 secondaryTitle: '二级标题', 408 operationType: OperationType.BUTTON, 409 operationItem: [{ 410 value: '操作', 411 action: () => { 412 Prompt.showToast({ message: 'demo' }) 413 } 414 }] 415 }) 416 Divider().color('grey').width('100%').height('2vp') 417 SubHeader({ 418 // 右侧text_arrow 419 primaryTitle: '一级标题', 420 secondaryTitle: '二级标题', 421 operationType: OperationType.TEXT_ARROW, 422 operationItem: [{ 423 value: '更多', 424 action: () => { 425 Prompt.showToast({ message: 'demo' }) 426 } 427 }] 428 }) 429 Divider().color('grey').width('100%').height('2vp') 430 SubHeader({ 431 //左侧select 右侧是icon_(依次获焦) 432 select: { 433 options: [{ value: 'aaa' }, { value: 'bbb' }, { value: 'ccc' }], 434 value: 'selectDemo', 435 selected: 0, 436 onSelect: (index: number, value?: string) => { 437 console.log(`subheader onselect index : ${index}, value: ${value}`); 438 } 439 }, 440 operationType: OperationType.ICON_GROUP, 441 operationItem: [{ 442 value: $r('sys.media.ohos_ic_public_email'), 443 accessibilityText: '图标1', 444 accessibilityLevel: 'yes', 445 }, { 446 value: $r('sys.media.ohos_ic_public_email'), 447 accessibilityText: '图标2', 448 accessibilityLevel: 'no', 449 }, { 450 value: $r('sys.media.ohos_ic_public_email'), 451 accessibilityText: '图标3', 452 accessibilityDescription: '点击操作图标3', 453 }] 454 }) 455 Divider().color('grey').width('100%').height('2vp') 456 } 457 } 458} 459``` 460 461 462### 示例9（右侧按钮设置默认获焦） 463该示例通过设置subheader的右侧按钮属性defaultFocus使其默认获焦。 464```ts 465import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 466 467@Entry 468@Component 469struct SubHeaderExample { 470 build() { 471 Column() { 472 SubHeader({ 473 // 图标+二级标题, 右侧button 474 icon: $r('app.media.app_icon'), 475 secondaryTitle: '二级标题', 476 operationType: OperationType.BUTTON, 477 operationItem: [{ 478 value: '操作', 479 defaultFocus: true, 480 action: () => { 481 Prompt.showToast({ message: 'demo' }) 482 } 483 }] 484 }) 485 } 486 } 487} 488``` 489 490
