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