文章目录
- 一、功能说明
- 二、完整标准代码
- 三、核心API：ListItem卡片样式枚举
- 基础创建语法
- 四、关键用法逐行解析
- 1. 卡片分组容器（ListItemGroup）
- 2. 循环批量设置卡片样式
- 3. 两种展示区域对比
- 4. 列表通用配置
- 五、运行效果
- 总结
一、功能说明
ListItem支持通过style参数配置卡片样式，是鸿蒙系统推荐的列表视觉规范：
- ListItemStyle.CARD：卡片样式，自带圆角、间距、阴影效果，呈现独立卡片形态
- ListItemStyle.NONE：默认无样式，无边距、无圆角，整体平铺展示
- 可与
ListItemGroup(CARD)分组卡片容器结合使用 - 支持同列表内混合样式，满足多样化UI需求
二、完整标准代码
// xxx.ets @Entry @Component struct ListItemExample3 { build() { Column() { List({ space: '4vp', initialIndex: 0 }) { ListItemGroup({ style: ListItemGroupStyle.CARD }) { ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => { ListItem({ style: itemStyle }) { Text('' + index) .width('100%') .textAlign(TextAlign.Center) } }) } ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => { ListItem({ style: itemStyle }) { Text('' + index) .width('100%') .textAlign(TextAlign.Center) } }) } .width('100%') .multiSelectable(true) .backgroundColor(0xDCDCDC) } .width('100%') .padding({ top: 5 }) } }运行效果如图：
三、核心API：ListItem卡片样式枚举
官方提供ListItemStyle枚举，用于控制 ListItem 的显示形态：
| 枚举值 | 说明 | 视觉效果 |
|---|---|---|
| ListItemStyle.CARD | 卡片样式 | 自带内外边距、圆角、背景分隔，呈现独立卡片 |
| ListItemStyle.NONE | 无样式 | 默认平铺效果，无边距、无卡片形态 |
基础创建语法
// 创建卡片样式ListItem ListItem({ style: ListItemStyle.CARD }) { Text("卡片项") } // 创建无样式ListItem ListItem({ style: ListItemStyle.NONE }) { Text("无样式项") }四、关键用法逐行解析
1. 卡片分组容器（ListItemGroup）
代码中使用ListItemGroupStyle.CARD创建卡片分组，让内部 ListItem 以统一卡片组展示：
ListItemGroup({ style: ListItemGroupStyle.CARD }) { // 子项自动继承分组卡片风格 }2. 循环批量设置卡片样式
通过ForEach循环，为不同项设置不同样式，实现混合展示：
// 数组定义每个item的样式：CARD、CARD、NONE [ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE] // 循环创建ListItem并绑定样式 ForEach(..., (itemStyle: number) => { ListItem({ style: itemStyle }) { ... } })3. 两种展示区域对比
示例包含两种展示结构：
- 卡片分组内：ListItem 自带分组圆角 + 自身样式
- 普通列表内：ListItem 独立展示卡片/平铺效果
4. 列表通用配置
List({ space: '4vp' }) // 列表项间距 .multiSelectable(true) // 开启多选能力 .backgroundColor(0xDCDCDC) // 背景色五、运行效果
- 页面顶部：卡片分组列表
- 前两项：带圆角、间距的卡片样式
- 第三项：无样式、平铺、无卡片效果
- 页面下部：普通列表
- 同样展示 CARD / CARD / NONE 混合样式
- 背景为灰色，卡片项为白色，视觉分层清晰
- 符合 HarmonyOS 系统级列表设计规范
总结
ListItem 卡片样式是 HarmonyOS 官方提供的标准化UI能力，核心要点：
- 通过
ListItem({ style: ListItemStyle.CARD })开启卡片样式 - 支持 CARD（卡片）/ NONE（无样式）两种形态
- 可与
ListItemGroup(CARD)实现分组卡片效果 - 支持同列表混合使用，灵活适配界面设计
如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！
