这是一个使用鸿蒙技术开发的本地原生记账应用，非常适合大家用来练手。相关源码已上传至 Github，点击此处查看项目。欢迎大家交流、指正，也欢迎提交 PR。
一、引言
在鸿蒙应用开发中，List 组件是构建长列表场景的核心组件。无论是新闻列表、设置页面还是聊天记录，都离不开它。本文将通过一个模仿新闻列表的实战案例，带你快速掌握 List 组件的核心用法。
二、效果预览与整体结构
我们先来看一下最终要实现的效果：页面顶部是一个搜索框（TextInput），下方是一个新闻列表（List）。列表中的每一个条目都是一条新闻，包含新闻标题、作者和发布时间。
整体布局结构如下：
TextInput：作为搜索框，位于页面顶部。List：作为列表容器，位于搜索框下方。ForEach：遍历新闻数据数组，动态生成列表项。- 自定义子组件：每个列表项都是一个自定义组件，用于展示单条新闻的标题、作者和发布时间。
三、核心代码实现
3.1 数据模型
首先，我们需要定义一个新闻数据模型，用于存储新闻标题、作者和发布时间。
typescript
// NewsItem.ets
export interface NewsItem {
title: string;
author: string;
publishTime: string;
}3.2 主页面布局
接下来，我们编写主页面，包含 TextInput 和 List 组件。
typescript
// Index.ets
import { NewsItem } from './NewsItem';
@Entry
@Component
struct Index {
@State newsList: NewsItem[] = [
{ title: '鸿蒙生态再添新成员，多家头部应用宣布适配', author: '科技日报', publishTime: '2026-06-26 10:00' },
{ title: '华为开发者大会亮点回顾：HarmonyOS NEXT 正式发布', author: 'IT之家', publishTime: '2026-06-25 15:30' },
{ title: '深入理解 ArkTS 语法：状态管理与数据驱动 UI 更新', author: '鸿蒙开发者社区', publishTime: '2026-06-24 09:00' },
{ title: '从零开始搭建鸿蒙应用：开发环境配置与第一个 Hello World', author: 'CSDN 博主', publishTime: '2026-06-23 14:20' },
{ title: '鸿蒙原生应用上架流程详解：从签名到审核全攻略', author: '华为开发者联盟', publishTime: '2026-06-22 11:45' },
{ title: 'ArkUI 动画实战：打造流畅的页面转场与交互动效', author: '鸿蒙技术周刊', publishTime: '2026-06-21 16:00' },
{ title: '鸿蒙分布式技术入门：跨设备数据同步与任务迁移', author: '开发者头条', publishTime: '2026-06-20 08:30' },
{ title: '性能优化实战：鸿蒙应用冷启动速度提升 50% 的秘诀', author: '技术博客', publishTime: '2026-06-19 13:10' },
{ title: '鸿蒙安全机制解析：权限管理、数据加密与隐私保护', author: '安全研究', publishTime: '2026-06-18 09:50' },
{ title: '从 Web 到鸿蒙：前端开发者快速上手 ArkTS 指南', author: '前端之巅', publishTime: '2026-06-17 17:25' },
];
build() {
Column() {
// 搜索框
TextInput({ placeholder: '搜索新闻...' })
.width('100%')
.height(40)
.margin({ bottom: 10 })
// 新闻列表
List() {
ForEach(this.newsList, (item: NewsItem) => {
ListItem() {
NewsCard({ newsItem: item })
}
}, (item: NewsItem) => item.title)
}
.width('100%')
.height('100%')
}
.padding(10)
.width('100%')
.height('100%')
}
}3.3 自定义新闻卡片组件
每个新闻条目都是一个独立的 @Component，我们将其命名为 NewsCard。它包含新闻标题、作者和发布时间。
typescript
// NewsCard.ets
import { NewsItem } from './NewsItem';
@Component
export struct NewsCard {
@Prop newsItem: NewsItem;
build() {
Column() {
// 新闻标题：最多显示两行，超出显示省略号
Text(this.newsItem.title)
.fontSize(16)
.fontWeight(FontWeight.Bold)
.maxLines(2)
.textOverflow({ overflow: TextOverflow.Ellipsis })
.width('100%')
// 作者和发布时间
Row() {
Text() {
Span(this.newsItem.author)
.fontSize(12)
.fontColor(Color.Gray)
Span(' | ')
.fontSize(12)
.fontColor(Color.Gray)
Span(this.newsItem.publishTime)
.fontSize(12)
.fontColor(Color.Gray)
}
.fontSize(12)
.fontColor(Color.Gray)
}
.width('100%')
.margin({ top: 8 })
}
.padding(12)
.width('100%')
.backgroundColor(Color.White)
.borderRadius(8)
.margin({ bottom: 8 })
}
}运行效果：
四、关键知识点解析
4.1 List 组件的子元素限制
List 组件的子元素不能是任意组件 ，它必须是 ListItem 或 ListItemGroup。如果你尝试在 List 中直接放置一个 Column 或 Text，编译器会报错。
typescript
// ❌ 错误写法
List() {
Column() { // 报错：List 的子元素只能是 ListItem 或 ListItemGroup
// ...
}
}
// ✅ 正确写法
List() {
ListItem() {
Column() {
// ...
}
}
}4.2 文本溢出处理
当新闻标题过长时，我们使用 maxLines 和 textOverflow 属性来控制显示行数和溢出后的省略号效果。
typescript
Text(this.newsItem.title)
.maxLines(2) // 最大显示两行
.textOverflow({ overflow: TextOverflow.Ellipsis }) // 超出显示省略号4.3 Span 组件的妙用
在显示作者和发布时间时，我们使用了 Span 组件包裹在 Text 组件内部。这样做的好处是：
- 样式统一 ：
Span可以继承父级Text组件的样式（如字体大小、颜色）。 - 代码简洁 ：如果写成两个独立的
Text组件，需要重复设置相同的样式属性。
typescript
// ✅ 推荐写法：使用 Span 组件
Text() {
Span(this.newsItem.author)
Span(' | ')
Span(this.newsItem.publishTime)
}
// ❌ 不推荐写法：多个 Text 组件，代码冗余
Text(this.newsItem.author)
Text(' | ')
Text(this.newsItem.publishTime)五、总结
通过本文的实战案例，我们学习了如何在鸿蒙应用中使用 List 组件构建一个新闻列表。关键点总结如下：
List的子元素必须是ListItem或ListItemGroup。- 使用
ForEach遍历数据数组，动态渲染列表项。 - 利用
maxLines和textOverflow处理文本溢出。 - 使用
Span组件简化相同样式的文本布局。
掌握了这些核心用法，你就可以轻松应对各种列表场景的开发需求了。