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 12## Modules to Import 13 14```ts 15import { SubHeader } from '@kit.ArkUI' 16``` 17 18 19## Child Components 20 21Not supported 22 23## Attributes 24 25The [universal attributes](ts-component-general-attributes.md) are not supported. 26 27> **NOTE** 28> 29> Text-related settings are not supported. 30 31## SubHeader 32 33SubHeader({icon?: ResourceStr, iconSymbolOptions?: SymbolOptions, primaryTitle?: ResourceStr, secondaryTitle?: 34ResourceStr, select?: SelectOptions, operationType?: OperationType, operationItem?: Array<OperationOption>, 35operationSymbolOptions?: Array<SymbolOptions>, primaryTitleModifier?: TextModifier, secondaryTitleModifier?: 36TextModifier, titleBuilder?: () => void, contentMargin?: LocalizedMargin, contentPadding?: LocalizedPadding}) 37 38**Decorator**: @Component 39 40**System capability**: SystemCapability.ArkUI.ArkUI.Full 41 42| Name| Type| Mandatory| Decorator | Description| 43| -------- | -------- | -------- |---------------| -------- | 44| 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.| 45| 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.| 46| 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.| 47| 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.| 48| 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.| 49| 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.| 50| 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.| 51| 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.| 52| 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.| 53| 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.| 54| 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.| 55| 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.| 56| 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.| 57 58 59## OperationType 60 61**Atomic service API**: This API can be used in atomic services since API version 11. 62 63**System capability**: SystemCapability.ArkUI.ArkUI.Full 64 65| Name| Value| Description| 66| -------- | -------- | -------- | 67| TEXT_ARROW | 0 | Text button with a right arrow.| 68| BUTTON | 1 | Text button without a right arrow.| 69| ICON_GROUP | 2 | Icon-attached button (A maximum of three icons can be configured.)| 70| LOADING | 3 | Loading animation.| 71 72## SelectOptions 73 74**System capability**: SystemCapability.ArkUI.ArkUI.Full 75 76| Name| Type| Mandatory| Description | 77| -------- | -------- | -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------| 78| 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. | 79| 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.| 80| value | string | No| Text content of the drop-down list button itself.<br>The default value is an empty string.<br>**NOTE**<br>If the text is longer than the column width, it will be truncated.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 81| 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. | 82| 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. | 83 84## OperationOption 85 86**System capability**: SystemCapability.ArkUI.ArkUI.Full 87 88| Name| Type| Mandatory| Description | 89| -------- | -------- | -------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 90| 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. | 91| action | ()=>void | No| Event.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 92| 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.| 93| 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.| 94| 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. | 95| 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. | 96## SymbolOptions<sup>12+</sup> 97 98**Atomic service API**: This API can be used in atomic services since API version 12. 99 100**System capability**: SystemCapability.ArkUI.ArkUI.Full 101 102| Name| Type| Mandatory| Description | 103| -------- | -------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 104| 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 | 105| 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 | 106| fontWeight | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | No| Font 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 font 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**| 107| 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. | 108| 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. | 109 110## Events 111The [universal events](ts-component-general-events.md) are not supported. 112 113## Example 114### Example 1: Implementing an Efficiency-Oriented Subheader 115This 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. 116 117```ts 118import { promptAction, OperationType, SubHeader } from '@kit.ArkUI'; 119 120@Entry 121@Component 122struct SubHeaderExample { 123 build() { 124 Column() { 125 SubHeader({ 126 icon: $r('sys.media.ohos_ic_public_email'), 127 secondaryTitle: 'Secondary title', 128 operationType: OperationType.BUTTON, 129 operationItem: [{ 130 value: 'Operation', 131 action: () => { 132 promptAction.showToast({ message: 'demo' }); 133 } 134 }] 135 }) 136 } 137 } 138} 139``` 140 141 142 143### Example 2: Implementing a Double-Line Text Content-rich Subheader 144This 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. 145 146```ts 147import { promptAction, OperationType, SubHeader } from '@kit.ArkUI'; 148 149@Entry 150@Component 151struct SubHeaderExample { 152 build() { 153 Column() { 154 SubHeader({ 155 primaryTitle: 'Primary title', 156 secondaryTitle: 'Secondary title', 157 operationType: OperationType.TEXT_ARROW, 158 operationItem: [{ 159 value: 'More', 160 action: () => { 161 promptAction.showToast({ message: 'demo' }); 162 } 163 }] 164 }) 165 } 166 } 167} 168``` 169 170 171 172### Example 3: Implementing a Spinner Content-rich Subheader 173This example showcases a subheader with content and events for selection on the left, and an icon-attached button on the right. 174 175```ts 176import { promptAction, OperationType, SubHeader } from '@kit.ArkUI'; 177 178@Entry 179@Component 180struct SubHeaderExample { 181 build() { 182 Column() { 183 SubHeader({ 184 // The left side is a drop-down box for selection. 185 select: { 186 options: [{ value: 'aaa' }, { value: 'bbb' }, { value: 'ccc' }], 187 value: 'selectDemo', 188 selected: 2, 189 onSelect: () => { 190 promptAction.showToast({ message: 'demo' }); 191 } 192 }, 193 operationType: OperationType.ICON_GROUP, 194 // The right side has three icons. 195 operationItem: [{ 196 value: $r('sys.media.ohos_ic_public_email'), 197 action: () => { 198 promptAction.showToast({ message: 'demo' }) 199 } 200 }, { 201 value: $r('sys.media.ohos_ic_public_email'), 202 action: () => { 203 promptAction.showToast({ message: 'demo' }); 204 } 205 }, { 206 value: $r('sys.media.ohos_ic_public_email'), 207 action: () => { 208 promptAction.showToast({ message: 'demo' }); 209 } 210 }] 211 }) 212 } 213 } 214} 215``` 216 217 218 219### Example 4: Setting the Icon Symbol for the Left Side 220This example demonstrates how to set the icon symbol for the left side of the subheader. 221 222```ts 223 224import { promptAction, OperationType, SubHeader } from '@kit.ArkUI'; 225 226@Entry 227@Component 228struct SubHeaderExample { 229 build() { 230 Column() { 231 SubHeader({ 232 // Set the icon to a symbol icon. 233 icon: $r('sys.symbol.ohos_wifi'), 234 iconSymbolOptions: { 235 effectStrategy: SymbolEffectStrategy.HIERARCHICAL, 236 }, 237 secondaryTitle: 'Title', 238 operationType: OperationType.BUTTON, 239 operationItem: [{ 240 value: 'Operation', 241 action: () => { 242 promptAction.showToast({ message: 'demo' }); 243 } 244 }] 245 }) 246 } 247 } 248} 249``` 250 251 252 253### Example 5: Setting the Icon Symbol for the Right Side 254The 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. 255 256```ts 257import { promptAction, OperationType, SubHeader } from '@kit.ArkUI'; 258 259@Entry 260@Component 261struct SubHeaderExample { 262 build() { 263 Column() { 264 SubHeader({ 265 // Set the left side to a drop-down box for selection. 266 select: { 267 options: [{ value: 'aaa' }, { value: 'bbb' }, { value: 'ccc' }], 268 value: 'selectDemo', 269 selected: 2, 270 onSelect: () => { 271 promptAction.showToast({ message: 'demo' }); 272 } 273 }, 274 operationType: OperationType.ICON_GROUP, 275 // Set the right side to icons. 276 operationItem: [{ 277 value: $r('sys.symbol.ohos_lungs'), 278 action: () => { 279 promptAction.showToast({ message: 'icon1' }); 280 } 281 }, { 282 value: $r('sys.symbol.ohos_lungs'), 283 action: () => { 284 promptAction.showToast({ message: 'icon2' }); 285 } 286 }, { 287 value: $r('sys.symbol.ohos_lungs'), 288 action: () => { 289 promptAction.showToast({ message: 'icon3' }); 290 } 291 }], 292 // Set the symbol style for the right side icons. 293 operationSymbolOptions: [{ 294 fontWeight: FontWeight.Lighter, 295 }, { 296 renderingStrategy: SymbolRenderingStrategy.MULTIPLE_COLOR, 297 fontColor: [Color.Blue, Color.Grey, Color.Green], 298 }, { 299 renderingStrategy: SymbolRenderingStrategy.MULTIPLE_OPACITY, 300 fontColor: [Color.Blue, Color.Grey, Color.Green], 301 }] 302 }) 303 } 304 } 305} 306``` 307 308 309 310### Example 6: Customizing Title Content 311 This example demonstrates how to customize the title content with a **titleBuilder** object for the subheader. 312 313```ts 314import { promptAction, OperationType, SubHeader } from '@kit.ArkUI'; 315 316@Entry 317@Component 318struct SubHeaderExample { 319 // Set the custom title on the left side. 320 @Builder 321 TitleBuilder(): void { 322 Text('Custom title') 323 .fontSize(24) 324 .fontColor(Color.Blue) 325 .fontWeight(FontWeight.Bold) 326 } 327 328 build() { 329 Column() { 330 SubHeader({ 331 // Call the custom title builder. 332 titleBuilder: () => { 333 this.TitleBuilder(); 334 }, 335 primaryTitle: 'Primary title', 336 secondaryTitle: 'Secondary title', 337 icon: $r('sys.symbol.ohos_star'), 338 operationType: OperationType.TEXT_ARROW, 339 operationItem: [{ 340 value: 'More info', 341 action: () => { 342 promptAction.showToast({ message: 'demo' }); 343 } 344 }] 345 }) 346 } 347 } 348} 349``` 350 351 352### Example 7: Customizing the Title Style 353This example demonstrates how to set the font style, margin, and padding for the primary and secondary titles in the subheader. 354 355```ts 356import { promptAction, OperationType, SubHeader, LengthMetrics, TextModifier } from '@kit.ArkUI'; 357 358@Entry 359@Component 360struct SubHeaderExample { 361 // Set the font color for the primary and secondary titles. 362 @State primaryModifier: TextModifier = new TextModifier().fontColor(Color.Blue); 363 @State secondaryModifier: TextModifier = new TextModifier().fontColor(Color.Blue); 364 365 build() { 366 Column() { 367 SubHeader({ 368 primaryTitle: 'primaryTitle', 369 secondaryTitle: 'secondaryTitle', 370 primaryTitleModifier: this.primaryModifier, 371 secondaryTitleModifier: this.secondaryModifier, 372 operationType: OperationType.TEXT_ARROW, 373 operationItem: [{ 374 value: 'More info', 375 action: () => { 376 promptAction.showToast({ message: 'demo' }); 377 } 378 }], 379 // Set the margin and padding for the subheader. 380 contentMargin: { start: LengthMetrics.vp(20), end: LengthMetrics.vp(20) }, 381 contentPadding: { start: LengthMetrics.vp(20), end: LengthMetrics.vp(20) } 382 }) 383 } 384 } 385} 386``` 387 388 389 390 391### Example 8: Implementing Announcement for the Button on the Right Side 392This 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. 393```ts 394import { promptAction, OperationType, SubHeader } from '@kit.ArkUI'; 395 396@Entry 397@Component 398struct SubHeaderExample { 399 build() { 400 Column() { 401 Divider().color('grey').width('100%').height('2vp') 402 SubHeader({ 403 // Icon + secondary title, with a button on the right 404 icon: $r('sys.media.ohos_ic_public_email'), 405 secondaryTitle: 'Secondary title', 406 operationType: OperationType.BUTTON, 407 operationItem: [{ 408 value: 'Operation', 409 action: () => { 410 promptAction.showToast({ message: 'demo' }) 411 } 412 }] 413 }) 414 Divider().color('grey').width('100%').height('2vp') 415 SubHeader({ 416 // Text button with right arrow on the right 417 primaryTitle: 'Primary title', 418 secondaryTitle: 'Secondary title', 419 operationType: OperationType.TEXT_ARROW, 420 operationItem: [{ 421 value: 'More', 422 action: () => { 423 promptAction.showToast({ message: 'demo' }) 424 } 425 }] 426 }) 427 Divider().color('grey').width('100%').height('2vp') 428 SubHeader({ 429 // Selection on the left and icons (focused in sequence) on the right 430 select: { 431 options: [{ value: 'aaa' }, { value: 'bbb' }, { value: 'ccc' }], 432 value: 'selectDemo', 433 selected: 0, 434 onSelect: (index: number, value?: string) => { 435 console.log(`subheader onselect index : ${index}, value: ${value}`); 436 } 437 }, 438 operationType: OperationType.ICON_GROUP, 439 operationItem: [{ 440 value: $r('sys.media.ohos_ic_public_email'), 441 accessibilityText: 'Icon 1', 442 accessibilityLevel: 'yes', 443 }, { 444 value: $r('sys.media.ohos_ic_public_email'), 445 accessibilityText: 'Icon 2', 446 accessibilityLevel: 'no', 447 }, { 448 value: $r('sys.media.ohos_ic_public_email'), 449 accessibilityText: 'Icon 3', 450 accessibilityDescription: 'Tap to operate icon 3', 451 }] 452 }) 453 Divider().color('grey').width('100%').height('2vp') 454 } 455 } 456} 457``` 458 459 460### Example 9: Enabling the Button on the Right Side to Receive Default Focus 461This example demonstrates how to use **defaultFocus** to enable the button on the right side of the subheader to receive default focus. 462```ts 463import { promptAction, OperationType, SubHeader } from '@kit.ArkUI'; 464 465@Entry 466@Component 467struct SubHeaderExample { 468 build() { 469 Column() { 470 SubHeader({ 471 // Icon + secondary title, with a button on the right 472 icon: $r('app.media.app_icon'), 473 secondaryTitle: 'Secondary title', 474 operationType: OperationType.BUTTON, 475 operationItem: [{ 476 value: 'Action', 477 defaultFocus: true, 478 action: () => { 479 promptAction.showToast({ message: 'demo' }) 480 } 481 }] 482 }) 483 } 484 } 485} 486``` 487 488
