1# ComposeListItem 2 3 4The **ComposeListItem** component is a container that presents a series of items arranged in a column with the same width. You can use it to present data of the same type in a multiple and coherent row style, for example, images or text. 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``` 17import { ComposeListItem } from "@kit.ArkUI"; 18``` 19 20 21## Child Components 22 23Not supported 24 25## Attributes 26The [universal attributes](ts-component-general-attributes.md) are not supported. 27 28 29## ComposeListItem 30 31ComposeListItem({contentItem?: ContentItem, operateItem?: OperateItem}) 32 33Creates a **ComposeListItem** component that allows customization of the left, center, and right content areas. 34 35**Decorator**: @Component 36 37**System capability**: SystemCapability.ArkUI.ArkUI.Full 38 39 40| Name| Type| Mandatory| Decorator| Description| 41| -------- | -------- | -------- | -------- | -------- | 42| contentItem | [ContentItem](#contentitem) | No| \@Prop | Elements on the left and in the center.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 43| operateItem | [OperateItem](#operateitem) | No| \@Prop | Element on the right.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 44 45## ContentItem 46 47Defines elements for the left and center areas of the **ComposeListItem** component. 48 49**System capability**: SystemCapability.ArkUI.ArkUI.Full 50 51 52| Name| Type| Mandatory| Description| 53| -------- | -------- | -------- | -------- | 54| iconStyle | [IconType](#icontype) | No| Icon style of the element on the left.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 55| icon | [ResourceStr](ts-types.md#resourcestr) | No| Icon resource of the element on the left.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 56| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No| Symbol icon resource of the element on the left, which has higher priority than **icon**.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 57| primaryText | [ResourceStr](ts-types.md#resourcestr) | No| Primary text of the element in the center.<br>**Text processing rules**: Text will wrap to a new line when it exceeds the length limit.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 58| secondaryText | [ResourceStr](ts-types.md#resourcestr) | No| Secondary text of the element in the center.<br>**Text processing rules**: Text will wrap to a new line when it exceeds the length limit.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 59| description | [ResourceStr](ts-types.md#resourcestr) | No| Description of the element in the center.<br>**Text processing rules**: Text will wrap to a new line when it exceeds the length limit.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 60 61## IconType 62 63Defines the icon type of the element on the left of the **ComposeListItem** component. 64 65**Atomic service API**: This API can be used in atomic services since API version 11. 66 67**System capability**: SystemCapability.ArkUI.ArkUI.Full 68 69| Name| Value| Description| 70| -------- | -------- | -------- | 71| BADGE | 1 | Badge with an icon size of 8 x 8 vp.| 72| NORMAL_ICON | 2 | Small icon with an icon size of 16 x 16 vp.| 73| SYSTEM_ICON | 3 | System icon with an icon size of 24 x 24 vp.| 74| HEAD_SCULPTURE | 4 | Profile picture with an icon size of 40 x 40 vp.| 75| APP_ICON | 5 | Application icon with an icon size of 64 x 64 vp.| 76| PREVIEW | 6 | Preview image with an icon size of 96 x 96 vp.| 77| LONGITUDINAL | 7 | Icon with a horizontal special ratio (width is greater than height), keeping the longest side at 96 vp.| 78| VERTICAL | 8 | Icon with a vertical special ratio (height is greater than width), keeping the longest side at 96 vp.| 79 80## OperateItem 81 82Defines the element type and text content on the right of the **ComposeListItem** component. 83 84**System capability**: SystemCapability.ArkUI.ArkUI.Full 85 86| Name| Type| Mandatory| Description| 87| -------- | -------- | -------- | -------- | 88| arrow | [OperateIcon](#operateicon) | No| Arrow with a size of 12 x 24 vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 89| icon | [OperateIcon](#operateicon) | No| First icon with a size of 24 x 24 vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 90| subIcon | [OperateIcon](#operateicon) | No| Second icon with a size of 24 x 24 vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 91| button | [OperateButton](#operatebutton) | No| Button.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 92| switch | [OperateCheck](#operatecheck) | No| Switch.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 93| checkbox | [OperateCheck](#operatecheck) | No| Check box with a size of 24 x 24 vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 94| radio | [OperateCheck](#operatecheck) | No| Radio button with a size of 24 x 24 vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 95| image | [ResourceStr](ts-types.md#resourcestr) | No| Image with a size of 48 x 48 vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 96| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No| Symbol with a size of 48 x 48 vp.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 97| text | [ResourceStr](ts-types.md#resourcestr) | No| Text.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 98 99## OperateIcon 100 101Provides configuration options for icon elements on the right of the **ComposeListItem** component. 102 103**System capability**: SystemCapability.ArkUI.ArkUI.Full 104 105| Name| Type| Mandatory| Description | 106| -------- | -------- | -------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 107| value | [ResourceStr](ts-types.md#resourcestr) | Yes| Resource of the icon or arrow on the right.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 108| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | No| Resource of the symbol icon or arrow on the right, which has higher priority than **value**.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 109| action | ()=>void | No| Click event of the icon or arrow on the right.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 110| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Accessibility text, that is, accessible label name, of the icon or arrow on the right. 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: **""**<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 111| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Accessible description of the icon or arrow on the right. 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: **"Double-tap to activate"**<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 112| accessibilityLevel<sup>18+</sup> | string | No| Accessibility level of the icon or arrow on the right. It determines whether the component can be recognized by accessibility services.<br>The options are as follows:<br>**"auto"**: It is treated as "no" 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.| 113 114## OperateButton 115 116Provides configuration options for button-based elements on the right of the **ComposeListItem** component. 117 118**System capability**: SystemCapability.ArkUI.ArkUI.Full 119 120| Name| Type| Mandatory| Description| 121| -------- | -------- | -------- | -------- | 122| text | [ResourceStr](ts-types.md#resourcestr) | No| Text of the button on the right.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 123| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Accessibility text, that is, accessible label name, of the button on the right. 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>**Atomic service API**: This API can be used in atomic services since API version 18. | 124| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Accessible description of the button on the right. 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>**Atomic service API**: This API can be used in atomic services since API version 18. | 125| accessibilityLevel<sup>18+</sup> | string | No| Accessibility level of the button on the right. It determines whether the component can be recognized by accessibility services.<br>The options are as follows:<br>**"auto"**: It is treated as "no" 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.| 126 127## OperateCheck 128 129Provides configuration options for switch, check box, or radio button elements on the right of the **ComposeListItem** component. 130 131**System capability**: SystemCapability.ArkUI.ArkUI.Full 132 133| Name| Type| Mandatory| Description | 134| -------- | -------- | -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 135| isCheck | boolean | No| Whether the switch, check box, or radio button on the right is selected.<br> Default value: **false**.<br> **true**: selected.<br> **false**: not selected.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 136| onChange | (value: boolean)=>void | No| Callback invoked when the selected state of the switch, check box, or radio button on the right is changed.<br> **true**: from not selected to selected<br> **false**: from selected to not selected<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 137| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Accessibility text, that is, accessible label name, of the switch, check box, or radio button on the right. 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>**Atomic service API**: This API can be used in atomic services since API version 18. | 138| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Accessible description of the switch, check box, or radio button on the right. 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>By default, the announcement rules for the basic components **Switch**, **CheckBox**, and **Radio** are applied.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 139| accessibilityLevel<sup>18+</sup> | string | No| Accessibility level of the switch, check box, or radio button on the right. It determines whether the component can be recognized by accessibility services.<br>The options are as follows:<br>**"auto"**: It is treated as "no" 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. | 140 141## Events 142The [universal events](ts-component-general-events.md) are not supported. 143 144## Example 145 146### Example 1: Configuring a Simple List Item 147This example demonstrates how to create a simple list item that includes a primary text, a secondary text, a description, and a button with accompanying text on the right. 148```ts 149// This example demonstrates the basic functionality of the component, including the use of elements on the left and right. 150import { IconType, ComposeListItem } from '@kit.ArkUI'; 151 152@Entry 153@Component 154struct ComposeListItemExample { 155 build() { 156 Column() { 157 List() { 158 ListItem() { 159 ComposeListItem({ 160 contentItem: ({ 161 iconStyle: IconType.NORMAL_ICON, 162 icon: $r('sys.media.ohos_app_icon'), 163 primaryText: 'Double-line list', 164 secondaryText: 'Secondary text', 165 description: 'Description' 166 }), 167 operateItem: ({ 168 icon: { 169 value: $r('sys.media.ohos_app_icon'), 170 action: () => { 171 this.getUIContext().getPromptAction().showToast({ 172 message: 'icon' 173 }); 174 } }, 175 text: 'Text on the right' 176 }) 177 }) 178 } 179 } 180 } 181 } 182} 183``` 184 185 186### Example 2: Implementing Screen Reader Announcement for Right-Side Elements 187This example shows how to use the **accessibilityText**, **accessibilityDescription**, and **accessibilityLevel** properties to customize the screen reader announcements for different right-side elements such as icons, buttons, and radio buttons in a list item. This functionality is supported since API version 18. 188```ts 189import { IconType, ComposeListItem } from '@kit.ArkUI'; 190@Entry 191@Component 192struct ComposeListItemExample { 193 build() { 194 Column() { 195 List() { 196 ListItem() { 197 ComposeListItem({ 198 contentItem: ({ 199 iconStyle: IconType.NORMAL_ICON, 200 icon: $r('sys.media.ohos_app_icon'), 201 primaryText: 'Double-line list', 202 secondaryText: 'Secondary text', 203 description: 'Description' 204 }), 205 operateItem: ({ 206 radio: { 207 accessibilityText: 'Radio button', // Screen reader announcement for the radio button. 208 accessibilityDescription: 'Unselected', // Description read by screen reader when the radio button is unselected. 209 accessibilityLevel: 'yes' // Configure this element to be focused by accessibility screen readers. 210 } 211 }) 212 }) 213 } 214 215 ListItem() { 216 ComposeListItem({ 217 contentItem: ({ 218 iconStyle: IconType.NORMAL_ICON, 219 icon: $r('sys.media.ohos_app_icon'), 220 primaryText: 'Double-line list', 221 secondaryText: 'Secondary text', 222 description: 'Description' 223 }), 224 operateItem: ({ 225 button: { 226 text: 'OK', 227 accessibilityText: 'This is a button', 228 accessibilityDescription: 'Double tap to activate', 229 accessibilityLevel: 'no' // Configure this button to be not recognizable by screen readers. 230 } 231 }) 232 }) 233 } 234 235 ListItem() { 236 ComposeListItem({ 237 contentItem: ({ 238 iconStyle: IconType.NORMAL_ICON, 239 icon: $r('sys.media.ohos_app_icon'), 240 primaryText: 'Double-line list', 241 secondaryText: 'Secondary text', 242 description: 'Description' 243 }), 244 operateItem: ({ 245 icon: { 246 value: $r('sys.media.ohos_app_icon'), 247 action: () => { 248 this.getUIContext().getPromptAction().showToast({ 249 message: 'icon' 250 }); 251 }, 252 accessibilityText: 'This is an icon', // Screen reader announcement for the icon. 253 accessibilityDescription: 'Double-tap to show the toast', // Description read by screen reader for the icon action. 254 accessibilityLevel: 'yes' // Configure this element to be focused by screen readers. 255 } 256 }) 257 }) 258 } 259 } 260 } 261 } 262} 263``` 264 265 266### Example 3: Setting the Symbol Icon 267 268This example demonstrates how to use **symbolStyle** in **ContentItem**, **OperateItem**, and **OperateIcon** to set custom symbol icons. This functionality is supported since API version 18. 269 270```ts 271import { IconType, ComposeListItem, SymbolGlyphModifier } from '@kit.ArkUI'; 272@Entry 273@Component 274struct ComposeListItemExample { 275 build() { 276 Column() { 277 List() { 278 ListItem() { 279 ComposeListItem({ 280 contentItem: ({ 281 iconStyle: IconType.NORMAL_ICON, 282 icon: $r('sys.symbol.house'), 283 primaryText: 'Double-line list', 284 secondaryText: 'Secondary text', 285 description: 'Description' 286 }), 287 operateItem: ({ 288 image: $r('sys.symbol.car'), 289 }) 290 }) 291 } 292 293 ListItem() { 294 ComposeListItem({ 295 contentItem: ({ 296 iconStyle: IconType.NORMAL_ICON, 297 icon: $r('sys.symbol.house'), 298 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.bell')).fontColor([Color.Red]), 299 primaryText: 'Double-line list', 300 secondaryText: 'Secondary text', 301 description: 'Description' 302 }), 303 operateItem: ({ 304 image: $r('sys.symbol.car'), 305 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.heart')).fontColor([Color.Pink]), 306 }) 307 }) 308 } 309 310 ListItem() { 311 ComposeListItem({ 312 contentItem: ({ 313 iconStyle: IconType.NORMAL_ICON, 314 icon: $r('sys.symbol.house'), 315 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.bell')).fontColor([Color.Blue]), 316 primaryText: 'Double-line list', 317 secondaryText: 'Secondary text', 318 description: 'Description' 319 }), 320 operateItem: ({ 321 icon: { 322 value: $r('sys.symbol.car'), 323 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.heart')).fontColor([Color.Orange]), 324 action: () => { 325 this.getUIContext().getPromptAction().showToast({ 326 message: 'icon' 327 }); 328 } 329 } 330 }) 331 }) 332 } 333 } 334 } 335 } 336} 337``` 338 339 340
