1# ComposeListItem 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @fengluochenai--> 5<!--Designer: @YanSanzo--> 6<!--Tester: @tinygreyy--> 7<!--Adviser: @HelloCrease--> 8 9 10该组件用于展示一系列宽度相同的列表项，适用于展示连续、多行的同类数据组合（如图片与文本）。 11 12 13> **说明：** 14> 15> 该组件从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 16> 17 18 19## 导入模块 20 21``` 22import { ComposeListItem } from "@kit.ArkUI"; 23``` 24 25 26## 子组件 27 28无 29 30## 属性 31不支持[通用属性](ts-component-general-attributes.md)。 32 33 34## ComposeListItem 35 36ComposeListItem({contentItem?: ContentItem, operateItem?: OperateItem}) 37 38列表组件，可自定义列表左侧、中间元素以及右侧显示内容。 39 40**装饰器类型：**\@Component 41 42**系统能力：** SystemCapability.ArkUI.ArkUI.Full 43 44**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 45 46 47| 名称 | 类型 | 必填 | 装饰器类型 | 说明 | 48| -------- | -------- | -------- | -------- | -------- | 49| contentItem | [ContentItem](#contentitem) | 否 | \@Prop | 定义左侧以及中间元素。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 50| operateItem | [OperateItem](#operateitem) | 否 | \@Prop | 定义右侧元素。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 51 52## ContentItem 53 54列表左侧显示的图标、图标大小以及中间元素文字内容。 55 56**系统能力：** SystemCapability.ArkUI.ArkUI.Full 57 58**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 59 60 61| 名称 | 类型 | 必填 | 说明 | 62| -------- | -------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------| 63| iconStyle | [IconType](#icontype) | 否 | 左侧元素的图标样式。<br/>默认不设置或设置为undefined，icon图标资源不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 64| icon | [ResourceStr](ts-types.md#resourcestr) | 否 | 左侧元素的图标资源。<br/>默认不设置或设置为undefined，icon图标资源不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 65| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-symbolglyphmodifier.md#symbolglyphmodifier) | 否 | 左侧元素的Symbol图标资源，优先级大于icon，同时设置了icon和Symbol图标，只显示Symbol图标。<br/>默认不设置或设置为undefined，Symbol图标不显示。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 66| primaryText | [ResourceStr](ts-types.md#resourcestr) | 否 | 中间元素的标题内容。<br/>默认不设置或设置为undefined，标题内容不显示。<br/>**文字处理规则：** 文本超长后无限换行显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 67| secondaryText | [ResourceStr](ts-types.md#resourcestr) | 否 | 中间元素的副标题内容。<br/>默认不设置或设置为undefined，副标题内容不显示。<br/>**文字处理规则：** 文本超长后无限换行显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 68| description | [ResourceStr](ts-types.md#resourcestr) | 否 | 中间元素的描述内容。<br/>默认不设置或设置为undefined，描述内容不显示。<br/>**文字处理规则：** 文本超长后无限换行显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 69 70## IconType 71 72列表左侧图标类型。 73 74**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 75 76**系统能力：** SystemCapability.ArkUI.ArkUI.Full 77 78**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 79 80| 名称 | 值 | 说明 | 81| -------- | -------- | -------- | 82| BADGE | 1 | 左侧图标为badge类型，图标大小为8\*8vp。 | 83| NORMAL_ICON | 2 | 左侧图标为小图标类型，图标大小为16\*16vp。 | 84| SYSTEM_ICON | 3 | 左侧图标为系统图标类型，图标大小为24\*24vp。 | 85| HEAD_SCULPTURE | 4 | 左侧图标为头像类型，图标大小为40\*40vp。 | 86| APP_ICON | 5 | 左侧图标为应用图标类型，图标大小为64\*64vp。 | 87| PREVIEW | 6 | 左侧图标为预览图类型，图标大小为96\*96vp。 | 88| LONGITUDINAL | 7 | 左侧图标为横向特殊比例（宽比高大），保持最长边为96vp。 | 89| VERTICAL | 8 | 左侧图标为竖向特殊比例（高比宽大），保持最长边为96vp。 | 90 91## OperateItem 92 93列表右侧显示的元素类型。 94 95**系统能力：** SystemCapability.ArkUI.ArkUI.Full 96 97**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 98 99| 名称 | 类型 | 必填 | 说明 | 100| -------- | -------- | -------- |--------------------------------------------------------------------------------------------------------------------| 101| arrow | [OperateIcon](#operateicon) | 否 | 右侧元素为箭头，大小为12\*24vp。<br/>默认不设置或设置为undefined，右侧箭头不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 102| icon | [OperateIcon](#operateicon) | 否 | 右侧元素的第一个图标，大小为24\*24vp。<br/>默认不设置或设置为undefined，右侧图标不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 103| subIcon | [OperateIcon](#operateicon) | 否 | 右侧元素的第二个图标，大小为24\*24vp。<br/>默认不设置或设置为undefined，右侧第二个图标不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 104| button | [OperateButton](#operatebutton) | 否 | 右侧元素为按钮。<br/>默认不设置或设置为undefined，右侧按钮不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 105| switch | [OperateCheck](#operatecheck) | 否 | 右侧元素为开关。<br/>默认不设置或设置为undefined，右侧开关不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 106| checkbox | [OperateCheck](#operatecheck) | 否 | 右侧元素为多选框，大小为24\*24vp。<br/>默认不设置或设置为undefined，右侧多选框不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 107| radio | [OperateCheck](#operatecheck) | 否 | 右侧元素为单选框，大小为24\*24vp。<br/>默认不设置或设置为undefined，右侧单选框不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 108| image | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧元素为图片，大小为48\*48vp。<br/>默认不设置或设置为undefined，右侧图片不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 109| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-symbolglyphmodifier.md#symbolglyphmodifier) | 否 | 右侧元素为Symbol图标资源，大小为48\*48vp。<br/>默认不设置或设置为undefined，右侧Symbol图标不显示。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 110| text | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧元素为文字。 <br/>默认不设置或设置为undefined，右侧文字不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 111 112## OperateIcon 113 114列表右侧图标元素的类型。 115 116**系统能力：** SystemCapability.ArkUI.ArkUI.Full 117 118**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 119 120| 名称 | 类型 | 必填 | 说明 | 121| -------- | -------- | -------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 122| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 右侧图标/箭头资源。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 123| symbolStyle<sup>18+</sup> | [SymbolGlyphModifier](ts-universal-attributes-attribute-symbolglyphmodifier.md#symbolglyphmodifier) | 否 | 右侧Symbol图标/箭头资源，优先级大于value。<br/>默认不设置或设置为undefined，Symbol图标不显示。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 124| action | ()=>void | 否 | 右侧图标/箭头点击事件。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 125| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧图标/箭头的无障碍文本属性。当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>默认值：""<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 126| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧图标/箭头的无障碍描述。此描述用于向用户详细解释当前组件，开发人员应为组件的这一属性提供较为详尽的文本说明，以协助用户理解即将执行的操作及其可能产生的后果。特别是当这些后果无法仅从组件的属性和无障碍文本中直接获知时。如果组件同时具备文本属性和无障碍说明属性，当组件被选中时，系统将首先播报组件的文本属性，随后播报无障碍说明属性的内容。<br/>默认值为“单指双击即可执行”。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 127| accessibilityLevel<sup>18+</sup> | string | 否 | 右侧图标/箭头的无障碍重要性。用于控制当前项是否可被无障碍辅助服务所识别。<br/>支持的值为：<br/>"auto"：当前组件会转换"no"。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto" <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 128 129## OperateButton 130 131列表右侧按钮元素的类型。 132 133**系统能力：** SystemCapability.ArkUI.ArkUI.Full 134 135**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 136 137| 名称 | 类型 | 必填 | 说明 | 138| -------- | -------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 139| text | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧按钮文字。<br/>默认值：""<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 140| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧按钮的无障碍文本属性。当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>默认值：""<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 141| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧按钮的无障碍描述。此描述用于向用户详细解释当前组件，开发人员应为组件的这一属性提供较为详尽的文本说明，以协助用户理解即将执行的操作及其可能产生的后果。特别是当这些后果无法仅从组件的属性和无障碍文本中直接获知时。如果组件同时具备文本属性和无障碍说明属性，当组件被选中时，系统将首先播报组件的文本属性，随后播报无障碍说明属性的内容。<br/>默认值："单指双击即可执行"。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 142| accessibilityLevel<sup>18+</sup> | string | 否 | 右侧按钮的无障碍重要性。用于控制当前项是否可被无障碍辅助服务所识别。<br/>支持的值为：<br/>"auto"：当前组件会转换"no"。<br/>"yes"：当前组件可被无障碍辅助服务所识别。<br/>"no"：当前组件不可被无障碍辅助服务所识别。<br/>"no-hide-descendants"：当前组件及其所有子组件不可被无障碍辅助服务所识别。<br/>默认值："auto" <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 143 144## OperateCheck 145 146列表右侧元素为Switch、CheckBox、Radio的类型。 147 148**系统能力：** SystemCapability.ArkUI.ArkUI.Full 149 150**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常， 异常信息中提示接口未定义，在其他设备中可正常调用。 151 152| 名称 | 类型 | 必填 | 说明 | 153| -------- | -------- | -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 154| isCheck | boolean | 否 | 右侧Switch/CheckBox/Radio选中状态。<br> isCheck默认值为false。<br> isCheck为true时，表示为选中。<br> isCheck为false时，表示为未选中。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 155| onChange | (value: boolean)=>void | 否 | 右侧Switch/CheckBox/Radio选中状态改变时触发回调。<br> value为true时，表示从未选中变为选中。<br> value为false时，表示从选中变为未选中。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 156| accessibilityText<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧Switch/CheckBox/Radio的无障碍文本属性。当组件不包含文本属性时，屏幕朗读选中此组件时不播报，使用者无法清楚地知道当前选中了什么组件。为了解决此场景，开发人员可为不包含文字信息的组件设置无障碍文本，当屏幕朗读选中此组件时播报无障碍文本的内容，帮助屏幕朗读的使用者清楚地知道自己选中了什么组件。<br/>默认值：""<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 157| accessibilityDescription<sup>18+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 右侧Switch/CheckBox/Radio的无障碍描述。此描述用于向用户详细解释当前组件，开发人员应为组件的这一属性提供较为详尽的文本说明，以协助用户理解即将执行的操作及其可能产生的后果。特别是当这些后果无法仅从组件的属性和无障碍文本中直接获知时。如果组件同时具备文本属性和无障碍说明属性，当组件被选中时，系统将首先播报组件的文本属性，随后播报无障碍说明属性的内容。<br/>默认跟随基础组件Switch/CheckBox/Radio播报规则。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 158| 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开始，该接口支持在原子化服务中使用。 | 159 160## 事件 161不支持[通用事件](ts-component-general-events.md)。 162 163## 示例 164 165### 示例1（设置简单列表项） 166该示例实现了带有主标题、副标题、描述、右侧按钮及文本的简单列表项。 167```ts 168// 该示例主要演示该组件的基础功能使用，包含左侧右侧元素的情况 169import { IconType, ComposeListItem } from '@kit.ArkUI'; 170 171@Entry 172@Component 173struct ComposeListItemExample { 174 build() { 175 Column() { 176 List() { 177 ListItem() { 178 ComposeListItem({ 179 contentItem: ({ 180 iconStyle: IconType.NORMAL_ICON, 181 icon: $r('sys.media.ohos_app_icon'), 182 primaryText: '双行列表', 183 secondaryText: '辅助文字', 184 description: '描述内容文字' 185 }), 186 operateItem: ({ 187 icon: { 188 value: $r('sys.media.ohos_app_icon'), 189 action: () => { 190 this.getUIContext().getPromptAction().showToast({ 191 message: 'icon' 192 }); 193 } }, 194 text: '右侧文本' 195 }) 196 }) 197 } 198 } 199 } 200 } 201} 202``` 203 204 205### 示例2（设置右侧不同元素自定义播报） 206从API version 18开始，该示例通过设置属性accessibilityText、accessibilityDescription、accessibilityLevel，实现右侧图标、按钮、单选框自定义屏幕朗读播报文本。 207```ts 208import { IconType, ComposeListItem } from '@kit.ArkUI'; 209@Entry 210@Component 211struct ComposeListItemExample { 212 build() { 213 Column() { 214 List() { 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 radio: { 226 accessibilityText: '单选框', // 该单选框屏幕朗读播报文本为‘单选框’ 227 accessibilityDescription: '未选中', // 该单选框屏幕朗读播报描述为'未选中' 228 accessibilityLevel: 'yes' // 该项可被无障碍屏幕朗读聚焦 229 } 230 }) 231 }) 232 } 233 234 ListItem() { 235 ComposeListItem({ 236 contentItem: ({ 237 iconStyle: IconType.NORMAL_ICON, 238 icon: $r('sys.media.ohos_app_icon'), 239 primaryText: '双行列表', 240 secondaryText: '辅助文字', 241 description: '描述内容文字' 242 }), 243 operateItem: ({ 244 button: { 245 text: '确定', 246 accessibilityText: '这是一个按钮', 247 accessibilityDescription: '单指双击即可执行', 248 accessibilityLevel: 'no' // 该按钮不可被屏幕朗读服务识别 249 } 250 }) 251 }) 252 } 253 254 ListItem() { 255 ComposeListItem({ 256 contentItem: ({ 257 iconStyle: IconType.NORMAL_ICON, 258 icon: $r('sys.media.ohos_app_icon'), 259 primaryText: '双行列表', 260 secondaryText: '辅助文字', 261 description: '描述内容文字' 262 }), 263 operateItem: ({ 264 icon: { 265 value: $r('sys.media.ohos_app_icon'), 266 action: () => { 267 this.getUIContext().getPromptAction().showToast({ 268 message: 'icon' 269 }); 270 }, 271 accessibilityText: '这是一个icon', // 该icon屏幕朗读播报文本为‘这是一个icon’ 272 accessibilityDescription: '单指双击即可弹出', // 该icon屏幕朗读播报描述为'单指双击即可弹出' 273 accessibilityLevel: 'yes' // 该项可被无障碍屏幕朗读聚焦 274 } 275 }) 276 }) 277 } 278 } 279 } 280 } 281} 282``` 283 284 285### 示例3（设置Symbol类型图标） 286 287从API version 18开始，该示例通过设置ContentItem、OperateItem、OperateIcon的属性symbolStyle，展示了自定义Symbol类型图标。 288 289```ts 290import { IconType, ComposeListItem, SymbolGlyphModifier } from '@kit.ArkUI'; 291@Entry 292@Component 293struct ComposeListItemExample { 294 build() { 295 Column() { 296 List() { 297 ListItem() { 298 ComposeListItem({ 299 contentItem: ({ 300 iconStyle: IconType.NORMAL_ICON, 301 icon: $r('sys.symbol.house'), 302 primaryText: '双行列表', 303 secondaryText: '辅助文字', 304 description: '描述内容文字' 305 }), 306 operateItem: ({ 307 image: $r('sys.symbol.car'), 308 }) 309 }) 310 } 311 312 ListItem() { 313 ComposeListItem({ 314 contentItem: ({ 315 iconStyle: IconType.NORMAL_ICON, 316 icon: $r('sys.symbol.house'), 317 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.bell')).fontColor([Color.Red]), 318 primaryText: '双行列表', 319 secondaryText: '辅助文字', 320 description: '描述内容文字' 321 }), 322 operateItem: ({ 323 image: $r('sys.symbol.car'), 324 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.heart')).fontColor([Color.Pink]), 325 }) 326 }) 327 } 328 329 ListItem() { 330 ComposeListItem({ 331 contentItem: ({ 332 iconStyle: IconType.NORMAL_ICON, 333 icon: $r('sys.symbol.house'), 334 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.bell')).fontColor([Color.Blue]), 335 primaryText: '双行列表', 336 secondaryText: '辅助文字', 337 description: '描述内容文字' 338 }), 339 operateItem: ({ 340 icon: { 341 value: $r('sys.symbol.car'), 342 symbolStyle: new SymbolGlyphModifier($r('sys.symbol.heart')).fontColor([Color.Orange]), 343 action: () => { 344 this.getUIContext().getPromptAction().showToast({ 345 message: 'icon' 346 }); 347 } 348 } 349 }) 350 }) 351 } 352 } 353 } 354 } 355} 356``` 357 358
