1# ComposeListItem 2 3 4列表包含一系列相同宽度的列表项。内容包括适合连续、多行呈现同类数据的组合，例如图片和文本。 5 6 7> **说明：** 8> 9> 该组件从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 10> 11> 该组件不支持在Wearable设备上使用。 12 13 14## 导入模块 15 16``` 17import { ComposeListItem } from "@kit.ArkUI"; 18``` 19 20 21## 子组件 22 23无 24 25## 属性 26不支持[通用属性](ts-component-general-attributes.md)。 27 28 29## ComposeListItem 30 31ComposeListItem({contentItem?: ContentItem, operateItem?: OperateItem}) 32 33列表组件，可自定义列表左侧、中间元素以及右侧显示内容。 34 35**装饰器类型：**\@Component 36 37**系统能力：** SystemCapability.ArkUI.ArkUI.Full 38 39 40| 名称 | 类型 | 必填 | 装饰器类型 | 说明 | 41| -------- | -------- | -------- | -------- | -------- | 42| contentItem | [ContentItem](#contentitem) | 否 | \@Prop | 定义左侧以及中间元素。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 43| operateItem | [OperateItem](#operateitem) | 否 | \@Prop | 定义右侧元素。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 44 45## ContentItem 46 47列表左侧显示的图标、图标大小以及中间元素文字内容。 48 49**系统能力：** SystemCapability.ArkUI.ArkUI.Full 50 51 52| 名称 | 类型 | 必填 | 说明 | 53| -------- | -------- | -------- | -------- | 54| iconStyle | [IconType](#icontype) | 否 | 左侧元素的图标样式。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 55| icon | [ResourceStr](ts-types.md#resourcestr) | 否 | 左侧元素的图标资源。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 56| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | 否 | 左侧元素的Symbol图标资源，优先级大于icon。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 57| primaryText | [ResourceStr](ts-types.md#resourcestr) | 否 | 中间元素的标题内容。<br/>**文字处理规则：** 文本超长后无限换行显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 58| secondaryText | [ResourceStr](ts-types.md#resourcestr) | 否 | 中间元素的副标题内容。<br/>**文字处理规则：** 文本超长后无限换行显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 59| description | [ResourceStr](ts-types.md#resourcestr) | 否 | 中间元素的描述内容。<br/>**文字处理规则：** 文本超长后无限换行显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 60 61## IconType 62 63列表左侧图标大小。 64 65**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 66 67**系统能力：** SystemCapability.ArkUI.ArkUI.Full 68 69| 名称 | 值 | 说明 | 70| -------- | -------- | -------- | 71| BADGE | 1 | 左侧图标为badge类型，图标大小为8\*8vp。 | 72| NORMAL_ICON | 2 | 左侧图标为小图标类型，图标大小为16\*16vp。 | 73| SYSTEM_ICON | 3 | 左侧图标为系统图标类型，图标大小为24\*24vp。 | 74| HEAD_SCULPTURE | 4 | 左侧图标为头像类型，图标大小为40\*40vp。 | 75| APP_ICON | 5 | 左侧图标为应用图标类型，图标大小为64\*64vp。 | 76| PREVIEW | 6 | 左侧图标为预览图类型，图标大小为96\*96vp。 | 77| LONGITUDINAL | 7 | 左侧图标为横向特殊比例（宽比高大），保持最长边为96vp。 | 78| VERTICAL | 8 | 左侧图标为竖向特殊比例（高比宽大），保持最长边为96vp。 | 79 80## OperateItem 81 82列表右侧显示的元素类型以及文字内容。 83 84**系统能力：** SystemCapability.ArkUI.ArkUI.Full 85 86| 名称 | 类型 | 必填 | 说明 | 87| -------- | -------- | -------- | -------- | 88| arrow | [OperateIcon](#operateicon) | 否 | 右侧元素为箭头，大小为12\*24vp。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 89| icon | [OperateIcon](#operateicon) | 否 | 右侧元素的第一个图标，大小为24\*24vp。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 90| subIcon | [OperateIcon](#operateicon) | 否 | 右侧元素的第二个图标，大小为24\*24vp。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 91| button | [OperateButton](#operatebutton) | 否 | 右侧元素为按钮。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 92| switch | [OperateCheck](#operatecheck) | 否 | 右侧元素为开关。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 93| checkbox | [OperateCheck](#operatecheck) | 否 | 右侧元素为多选框，大小为24\*24vp。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 94| radio | [OperateCheck](#operatecheck) | 否 | 右侧元素为单选，大小为24\*24vp。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 95| image | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧元素为图片，大小为48\*48vp。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 96| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | 否 | 右侧元素为Symbol，大小为48\*48vp。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 97| text | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧元素为文字。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 98 99## OperateIcon 100 101列表右侧显示的元素为图标的参数。 102 103**系统能力：** SystemCapability.ArkUI.ArkUI.Full 104 105| 名称 | 类型 | 必填 | 说明 | 106| -------- | -------- | -------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 107| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 右侧图标/箭头资源。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 108| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) | 否 | 右侧Symbol图标/箭头资源，优先级大于value。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 109| action | ()=>void | 否 | 右侧图标/箭头点击事件。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 110| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧图标/箭头的无障碍文本属性。当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>默认值为""。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 111| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧图标/箭头的无障碍描述。此描述用于向用户详细解释当前组件，开发人员应为组件的这一属性提供较为详尽的文本说明，以协助用户理解即将执行的操作及其可能产生的后果。特别是当这些后果无法仅从组件的属性和无障碍文本中直接获知时。如果组件同时具备文本属性和无障碍说明属性，当组件被选中时，系统将首先播报组件的文本属性，随后播报无障碍说明属性的内容。<br/>默认值为“单指双击即可执行”。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 112| accessibilityLevel<sup>18+</sup> | string | 否 | 右侧图标/箭头的无障碍重要性。用于控制当前项是否可被无障碍辅助服务所识别。<br/>支持的值为：<br/>"auto"：当前组件会转换"no"。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto" <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 113 114## OperateButton 115 116列表右侧显示的元素为按钮的参数。 117 118**系统能力：** SystemCapability.ArkUI.ArkUI.Full 119 120| 名称 | 类型 | 必填 | 说明 | 121| -------- | -------- | -------- | -------- | 122| text | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧按钮文字。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 123| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧按钮的无障碍文本属性。当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 124| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧按钮的无障碍描述。此描述用于向用户详细解释当前组件，开发人员应为组件的这一属性提供较为详尽的文本说明，以协助用户理解即将执行的操作及其可能产生的后果。特别是当这些后果无法仅从组件的属性和无障碍文本中直接获知时。如果组件同时具备文本属性和无障碍说明属性，当组件被选中时，系统将首先播报组件的文本属性，随后播报无障碍说明属性的内容。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 125| accessibilityLevel<sup>18+</sup> | string | 否 | 右侧按钮的无障碍重要性。用于控制当前项是否可被无障碍辅助服务所识别。<br/>支持的值为：<br/>"auto"：当前组件会转换"no"。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto" <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 126 127## OperateCheck 128 129列表右侧显示元素类型为Switch、CheckBox、Radio的参数。 130 131**系统能力：** SystemCapability.ArkUI.ArkUI.Full 132 133| 名称 | 类型 | 必填 | 说明 | 134| -------- | -------- | -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 135| isCheck | boolean | 否 | 右侧Switch/CheckBox/Radio选中状态。<br> isCheck默认值为false。<br> isCheck为true时，表示为选中。<br> isCheck为false时，表示为未选中。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 136| onChange | (value: boolean)=>void | 否 | 右侧Switch/CheckBox/Radio选中状态改变时触发回调。<br> value为true时，表示从未选中变为选中。<br> value为false时，表示从选中变为未选中。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 137| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧Switch/CheckBox/Radio的无障碍文本属性。当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 138| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧Switch/CheckBox/Radio的无障碍描述。此描述用于向用户详细解释当前组件，开发人员应为组件的这一属性提供较为详尽的文本说明，以协助用户理解即将执行的操作及其可能产生的后果。特别是当这些后果无法仅从组件的属性和无障碍文本中直接获知时。如果组件同时具备文本属性和无障碍说明属性，当组件被选中时，系统将首先播报组件的文本属性，随后播报无障碍说明属性的内容。<br/>默认跟随基础组件Switch/CheckBox/Radio播报规则。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 139| accessibilityLevel<sup>18+</sup> | string | 否 | 右侧Switch/CheckBox/Radio的无障碍重要性。用于控制当前项是否可被无障碍辅助服务所识别。<br/>支持的值为：<br/>"auto"：当前组件会转换"no"。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto" <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 140 141## 事件 142不支持[通用事件](ts-component-general-events.md)。 143 144## 示例 145 146### 示例1（设置简单列表项） 147该示例实现了带有主标题、副标题、描述、右侧按钮及文本的简单列表项。 148```ts 149// 该示例主要演示该组件的基础功能使用，包含左侧右侧元素的情况 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: '双行列表', 164 secondaryText: '辅助文字', 165 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: '右侧文本' 176 }) 177 }) 178 } 179 } 180 } 181 } 182} 183``` 184 185 186### 示例2（设置右侧不同元素自定义播报） 187该示例通过设置属性accessibilityText、accessibilityDescription、accessibilityLevel，实现右侧图标、按钮、单选框自定义屏幕朗读播报文本。 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: '双行列表', 202 secondaryText: '辅助文字', 203 description: '描述内容文字' 204 }), 205 operateItem: ({ 206 radio: { 207 accessibilityText: '单选框', // 该单选框屏幕朗读播报文本为‘单选框’ 208 accessibilityDescription: '未选中', // 该单选框屏幕朗读播报描述为'未选中' 209 accessibilityLevel: 'yes' // 该项可被无障碍屏幕朗读聚焦 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: '双行列表', 221 secondaryText: '辅助文字', 222 description: '描述内容文字' 223 }), 224 operateItem: ({ 225 button: { 226 text: '确定', 227 accessibilityText: '这是一个按钮', 228 accessibilityDescription: '单指双击即可执行', 229 accessibilityLevel: 'no' // 该按钮不可被屏幕朗读服务识别 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: '双行列表', 241 secondaryText: '辅助文字', 242 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: '这是一个icon', // 该icon屏幕朗读播报文本为‘这是一个icon’ 253 accessibilityDescription: '单指双击即可弹出', // 该icon屏幕朗读播报描述为'单指双击即可弹出' 254 accessibilityLevel: 'yes' // 该项可被无障碍屏幕朗读聚焦 255 } 256 }) 257 }) 258 } 259 } 260 } 261 } 262} 263``` 264 265 266### 示例3（设置Symbol类型图标） 267 268该示例通过设置ContentItem、OperateItem、OperateIcon的属性symbolStyle，展示了自定义Symbol类型图标。 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: '双行列表', 284 secondaryText: '辅助文字', 285 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: '双行列表', 300 secondaryText: '辅助文字', 301 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: '双行列表', 317 secondaryText: '辅助文字', 318 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
