1# SubHeader 2 3 4The **SubHeader** component represents a subheader that signifies the top of a list or the beginning a subdivision of content and tells the user what the list or subdivision is about. 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```ts 17import { SubHeader } from '@kit.ArkUI'; 18``` 19 20 21## Child Components 22 23Not supported 24 25## Attributes 26 27The [universal attributes](ts-component-general-attributes.md) are not supported. 28 29> **NOTE** 30> 31> Text-related settings are not supported. 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**Decorator**: @Component 41 42**System capability**: SystemCapability.ArkUI.ArkUI.Full 43 44| Name| Type| Mandatory| Decorator | Description| 45| -------- | -------- | -------- |---------------| -------- | 46| icon | [ResourceStr](ts-types.md#resourcestr) | No| \@Prop | Icon.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 47| iconSymbolOptions<sup>12+</sup> | [SymbolOptions](#symboloptions12) | No| - | Icon symbol options. This parameter is available when **icon** is set to a [symbol glyph](ts-basic-components-symbolGlyph.md).<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 48| primaryTitle | [ResourceStr](ts-types.md#resourcestr) | No| \@Prop | Primary title.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 49| secondaryTitle | [ResourceStr](ts-types.md#resourcestr) | No| \@Prop | Secondary title.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 50| select | [SelectOptions](#selectoptions) | No| - | Content and events for selection.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 51| operationType | [OperationType](#operationtype) | No| \@Prop | Type of operation in the operation area (right).<br>Default value: **OperationType.BUTTON**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 52| operationItem | Array<[OperationOption](#operationoption)> | No| - | Items in the operation area (right).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 53| operationSymbolOptions<sup>12+</sup> | Array<[SymbolOptions](#symboloptions12)> | No| - | Icon symbol options.<br>This parameter is available when **operationType** is set to **OperationType.ICON_GROUP** and **operationItem** is set to an array of [symbol glyphs](ts-basic-components-symbolGlyph.md).<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 54| primaryTitleModifier<sup>12+</sup> | [TextModifier](ts-universal-attributes-attribute-modifier.md) | No| - | Text attributes of the primary title, such as the font color, font size, and font weight.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 55| secondaryTitleModifier<sup>12+</sup> | [TextModifier](ts-universal-attributes-attribute-modifier.md) | No| - | Text attributes of the secondary title, such as the font color, font size, and font weight.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 56| titleBuilder<sup>12+</sup> | () => void | No| @BuilderParam | Content of the custom title area.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 57| 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(` <br> `$r('sys.float.margin_left'))`, <br> `end: LengthMetrics.resource(` <br> `$r('sys.float.margin_right'))}`<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 58| contentPadding<sup>12+</sup> | [LocalizedPadding](ts-types.md#localizedpadding12) | No| @Prop | Padding of the content.<br>Default value:<br>If a secondary title, with or without an icon, is displayed on the left:<br> {start: LengthMetrics.vp(12), end: LengthMetrics.vp(12)}<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 59 60 61## OperationType 62 63**Atomic service API**: This API can be used in atomic services since API version 11. 64 65**System capability**: SystemCapability.ArkUI.ArkUI.Full 66 67| Name| Value| Description| 68| -------- | -------- | -------- | 69| TEXT_ARROW | 0 | Text button with a right arrow.| 70| BUTTON | 1 | Text button without a right arrow.| 71| ICON_GROUP | 2 | Icon-attached button (A maximum of three icons can be configured.)| 72| LOADING | 3 | Loading animation.| 73 74## SelectOptions 75 76**System capability**: SystemCapability.ArkUI.ArkUI.Full 77 78| Name| Type| Mandatory| Description | 79| -------- | -------- | -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------| 80| options | Array<[SelectOption](ts-basic-components-select.md#selectoption)> | Yes| Options of an item in the drop-down list box.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 81| selected | number | No| Index of the initially selected item in the drop-down list box.<br>The value must be greater than or equal to -1.<br>The index of the first item is 0.<br>If this property is not set, the default value **-1** is used, indicating that the option is not selected.<br>Values less than -1 are treated as no selection.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 82| value | [ResourceStr](ts-types.md#resourcestr) | No| Text content of the drop-down list button itself.<br>The default value is an empty string.<br>**NOTE**<br>If the text length exceeds the column width, it will be truncated. The Resource type is supported since API version 20.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 83| onSelect | (index: number, value?: string) => void | No| Callback invoked when an item in the drop-down list box is selected.<br>- **index**: index of the selected option.<br>- **value**: value of the selected option.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 84| defaultFocus<sup>18+</sup> | boolean | No| Whether the drop-down button is the default focus.<br>**true**: The drop-down button is the default focus.<br>**false**: The drop-down button is not the default focus.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 85 86## OperationOption 87 88**System capability**: SystemCapability.ArkUI.ArkUI.Full 89 90| Name| Type| Mandatory| Description | 91| -------- | -------- | -------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 92| value | [ResourceStr](ts-types.md#resourcestr) | Yes| Text content.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 93| action | ()=>void | No| Event.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 94| 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.| 95| 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 **value** property if the operation type is **TEXT_ARROW** or **BUTTON** and an empty string otherwise.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 96| 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: "Loading" when the operation type is **LOADING** and **"Double-tap to activate"** otherwise.<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 97| defaultFocus<sup>18+</sup> | boolean | No| Whether to receive default focus.<br>**true**: Receive default focus.<br>**false**: Do not receive default focus.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 98## SymbolOptions<sup>12+</sup> 99 100**Atomic service API**: This API can be used in atomic services since API version 12. 101 102**System capability**: SystemCapability.ArkUI.ArkUI.Full 103 104| Name| Type| Mandatory| Description | 105| -------- | -------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 106| fontColor | Array<[ResourceColor](ts-types.md#resourcecolor)> | No| Color of the [symbol glyph](ts-basic-components-symbolGlyph.md).<br>Default value: depending on the rendering strategy | 107| fontSize | number \|string \|[Resource](ts-types.md#resource) | No| Size of the [symbol glyph](ts-basic-components-symbolGlyph.md).<br>The value must be greater than or equal to 0.<br>Default value: system default value | 108| fontWeight | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | No| Weight of the [symbol glyph](ts-basic-components-symbolGlyph.md).<br>For the number type, the value ranges from 100 to 900, at an interval of 100. A larger value indicates a heavier weight. The default value is **400**.<br>For the string type, only strings of the number type are supported, for example, **"400"**, **"bold"**, **"bolder"**, **"lighter"**, **"regular"**, and **"medium"**, which correspond to the enumerated values in **FontWeight**.<br>Default value: **FontWeight.Normal**.| 109| renderingStrategy | [SymbolRenderingStrategy](ts-basic-components-symbolGlyph.md#symbolrenderingstrategy11) | No| Rendering strategy of the [symbol glyph](ts-basic-components-symbolGlyph.md).<br>Default value: **SymbolRenderingStrategy.SINGLE**.<br>**NOTE**<br>For the resources referenced in **$r('sys.symbol.ohos_*')**, only **ohos_trash_circle**, **ohos_folder_badge_plus**, and **ohos_lungs** support the **MULTIPLE_COLOR** modes. | 110| effectStrategy | [SymbolEffectStrategy](ts-basic-components-symbolGlyph.md#symboleffectstrategy11) | No| Effect strategy of the [symbol glyph](ts-basic-components-symbolGlyph.md).<br>Default value: **SymbolEffectStrategy.NONE**<br>**NOTE**<br>For the resources referenced in **$r('sys.symbol.ohos_*')**, only **ohos_wifi** supports the hierarchical effect. | 111 112## Events 113The [universal events](ts-component-general-events.md) are not supported. 114 115## Example 116### Example 1: Implementing an Efficiency-Oriented Subheader 117This example demonstrates how to implement a subheader where the left side contains an icon and a secondary title, and the right side has a text button. 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: 'Secondary title', 130 operationType: OperationType.BUTTON, 131 operationItem: [{ 132 value: 'Operation', 133 action: () => { 134 Prompt.showToast({ message: 'demo' }); 135 } 136 }] 137 }) 138 } 139 } 140} 141``` 142 143 144 145### Example 2: Implementing a Double-Line Text Content-Rich Subheader 146This example showcases a subheader with a primary title and a secondary title on the left, and a text button with a right arrow on the right. 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: 'Primary title', 158 secondaryTitle: 'Secondary title', 159 operationType: OperationType.TEXT_ARROW, 160 operationItem: [{ 161 value: 'More', 162 action: () => { 163 Prompt.showToast({ message: 'demo' }); 164 } 165 }] 166 }) 167 } 168 } 169} 170``` 171 172 173 174### Example 3: Implementing a Spinner Content-Rich Subheader 175This example showcases a subheader with content and events for selection on the left, and an icon-attached button on the right. 176 177```ts 178import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 179 180@Entry 181@Component 182struct SubHeaderExample { 183 build() { 184 Column() { 185 SubHeader({ 186 // The left side is a drop-down box for selection. 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 // The right side has three icons. 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### Example 4: Setting the Icon Symbol for the Left Side 222This example demonstrates how to set the icon symbol for the left side of the subheader. 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 // Set the icon to a symbol icon. 235 icon: $r('sys.symbol.ohos_wifi'), 236 iconSymbolOptions: { 237 effectStrategy: SymbolEffectStrategy.HIERARCHICAL, 238 }, 239 secondaryTitle: 'Title', 240 operationType: OperationType.BUTTON, 241 operationItem: [{ 242 value: 'Operation', 243 action: () => { 244 Prompt.showToast({ message: 'demo' }); 245 } 246 }] 247 }) 248 } 249 } 250} 251``` 252 253 254 255### Example 5: Setting the Icon Symbol for the Right Side 256The following example shows how to set **operationType** to **OperationType.ICON_GROUP** for the right side of the subheader, with **operationItem** set to a symbol icon. 257 258```ts 259import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 260 261@Entry 262@Component 263struct SubHeaderExample { 264 build() { 265 Column() { 266 SubHeader({ 267 // Set the left side to a drop-down box for selection. 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 // Set the right side to icons. 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 // Set the symbol style for the right side icons. 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### Example 6: Customizing Title Content 313 This example demonstrates how to customize the title content with a **titleBuilder** object for the subheader. 314 315```ts 316import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 317 318@Entry 319@Component 320struct SubHeaderExample { 321 // Set the custom title on the left side. 322 @Builder 323 TitleBuilder(): void { 324 Text('Custom title') 325 .fontSize(24) 326 .fontColor(Color.Blue) 327 .fontWeight(FontWeight.Bold) 328 } 329 330 build() { 331 Column() { 332 SubHeader({ 333 // Call the custom title builder. 334 titleBuilder: () => { 335 this.TitleBuilder(); 336 }, 337 primaryTitle: 'Primary title', 338 secondaryTitle: 'Secondary title', 339 icon: $r('sys.symbol.ohos_star'), 340 operationType: OperationType.TEXT_ARROW, 341 operationItem: [{ 342 value: 'More info', 343 action: () => { 344 Prompt.showToast({ message: 'demo' }); 345 } 346 }] 347 }) 348 } 349 } 350} 351``` 352 353 354### Example 7: Customizing the Title Style 355This example demonstrates how to set the font style, margin, and padding for the primary and secondary titles in the subheader. 356 357```ts 358import { Prompt, OperationType, SubHeader, LengthMetrics, TextModifier } from '@kit.ArkUI'; 359 360@Entry 361@Component 362struct SubHeaderExample { 363 // Set the font color for the primary and secondary titles. 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: 'More info', 377 action: () => { 378 Prompt.showToast({ message: 'demo' }); 379 } 380 }], 381 // Set the margin and padding for the subheader. 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### Example 8: Implementing Announcement for the Button on the Right Side 394This example customizes the screen reader announcement text by setting the **accessibilityText**, **accessibilityDescription**, and **accessibilityLevel** properties of the button on the right side of the subheader. This functionality is supported since API version 18. 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 // Icon + secondary title, with a button on the right 406 icon: $r('sys.media.ohos_ic_public_email'), 407 secondaryTitle: 'Secondary title', 408 operationType: OperationType.BUTTON, 409 operationItem: [{ 410 value: 'Operation', 411 action: () => { 412 Prompt.showToast({ message: 'demo' }) 413 } 414 }] 415 }) 416 Divider().color('grey').width('100%').height('2vp') 417 SubHeader({ 418 // Text button with right arrow on the right 419 primaryTitle: 'Primary title', 420 secondaryTitle: 'Secondary title', 421 operationType: OperationType.TEXT_ARROW, 422 operationItem: [{ 423 value: 'More', 424 action: () => { 425 Prompt.showToast({ message: 'demo' }) 426 } 427 }] 428 }) 429 Divider().color('grey').width('100%').height('2vp') 430 SubHeader({ 431 // Selection on the left and icons (focused in sequence) on the right 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: 'Icon 1', 444 accessibilityLevel: 'yes', 445 }, { 446 value: $r('sys.media.ohos_ic_public_email'), 447 accessibilityText: 'Icon 2', 448 accessibilityLevel: 'no', 449 }, { 450 value: $r('sys.media.ohos_ic_public_email'), 451 accessibilityText: 'Icon 3', 452 accessibilityDescription: 'Tap to operate icon 3', 453 }] 454 }) 455 Divider().color('grey').width('100%').height('2vp') 456 } 457 } 458} 459``` 460 461 462### Example 9: Enabling the Button on the Right Side to Receive Default Focus 463This example demonstrates how to use **defaultFocus** to enable the button on the right side of the subheader to receive default focus. This functionality is supported since API version 18. 464```ts 465import { Prompt, OperationType, SubHeader } from '@kit.ArkUI'; 466 467@Entry 468@Component 469struct SubHeaderExample { 470 build() { 471 Column() { 472 SubHeader({ 473 // Icon + secondary title, with a button on the right 474 icon: $r('app.media.app_icon'), 475 secondaryTitle: 'Secondary title', 476 operationType: OperationType.BUTTON, 477 operationItem: [{ 478 value: 'Action', 479 defaultFocus: true, 480 action: () => { 481 Prompt.showToast({ message: 'demo' }) 482 } 483 }] 484 }) 485 } 486 } 487} 488``` 489 490
