一、

在鸿蒙应用开发中，List 组件是建立长列表场景的主要组件。无论是新闻列表、设置页面还是聊天记录，都离不开它。

二、效果预览与整体结构

我们先来看一下最终要实现的效果：页面顶部是一个搜索框，下方是一个新闻列表。列表中的每一条新闻包含标题、作者和发布时间。

整体布局结构如下：

• TextInput: 搜索框，位于页面顶部。
• List: 列表容器，位于搜索框下方。
• ForEach: 遍历新闻数据数组，动态生成列表项。
• 自定义子组件: 每个列表项都是自定义组件，用于展示单条新闻的标题、作者和发布时间。不过，

三、主要代码实现

1️⃣ 数据模型

需要定义一个新闻数据模型。用于存储标题、作者和发布时间。其实，在实际项目中，经常出现字段类型不一致导致编译报错的问题。所以建议统一使用字符串类型并在后端或业务层做格式化。

// NewsItem.etx
export interface NewsItem {
title的观点是，string;怎么说呢，author: string;publishTime: string;}

2️⃣ 主页面布局

Main 页面包含 TextInput 与 List。怎么说呢，下面的代码演示了完整实现。并标注了常见问题点：

// Index.ets
import { NewsItem } from './NewsItem';@Entry
@Component
struct Index {
@State newsList: NewsItem =;build {
Column {
// 搜索框
TextInput
.width
.height
.margin;// 新闻列表
List {
ForEach => {
ListItem {
NewsCard
}
},=> item.title);// key 必须唯一，否则渲染不稳定
}
.width
.height
}
.padding
.width
.height;}
}

3️⃣ 自定义新闻卡片组件

This component encapsulates each news entry and handles text overflow gracefully.

// NewsCard.ets
import { NewsItem } from './NewsItem';@Component
export struct NewsCard {
@Prop newsItem: NewsItem;build {
Column {
// 新闻最多显示两行，超出显示省略号
Text
.fontSize
.fontWeight
.maxLines
.textOverflow
.width;// 作者和发布时间
Row {
Text {
Span.fontSize.fontColor;
Span.fontSize.fontColor;Span.fontSize.fontColor;}
}
.margin，按理说，}
.padding
.backgroundColor
.borderRadius
.margin;}
}

四、关键知识点解析 & 使用者痛点方法

🔧 List 子元素限制问题

: 很多初学者把普通 //Text 等直接放进 List,导致编译报错“子元素只能是 ListItem 或 ListItemGroup”。这往往让人误以为 List 非常严格。: 将任何可视化内容包装进 ,再在其中使用 Column/Row 等布局即可。说到例如，

// ❌ 错误写法
// List{ Column{...}}

// ✅ 正确写法 // List{ // ListItem{ // Column{...} // } //}

🔍 文本溢出处理

: 当标题过长时会导致卡片高度不一致甚至页面抖动。很多人忽略了 maxLines/textOverflow 的组合配置。: 在 Title 上设置最大行数 + 溢出省略号。而且统一字体大小，保持基本一致。例如这方面，

Text
.maxLines
.textOverflow
...

🎨 Span 与 Text 的组合

: 开发时经常需要在同一行显示多段不同内容。却因为每段都写成独立 Text 而导致样式重复且难以维护。: 在同一父级 Text 内使用多个 Span。可继承父级样式，也能减少冗余。至于例如，

• ✅ 推荐写法: .Span…Span，Span
• ❌ 不推荐: .Text…Text，Text
.
This line is hidden but keeps formatting.
.

📦 性能调整小贴士

• ✅ 虚拟滚动支持: 若列表项数量超过几百条，请开启虚拟滚动功能；否则会导致内存使用飙升，
• ✅ 异步加载数据: 将网络请求拆分为分页或懒加载，可明显提高首次渲染速度。
• ❌ 常见错误: 把所有数据一次性拉到前端渲染，会造成卡顿甚至崩溃。

---

• 请根据实际业务需求调节阈值，如分页大小或缓存策略。

五、 & 后续建议

- 列表子元素必须是 . - 使用 ForEach 动态渲染并保证 key 唯一性。- 利用 maxLines/textOverflow 控制文本溢出，保持卡片基本一致。- 用 Span 简化同级文本样式维护成本。按理说，这些技巧能帮助你避免最常见的错误与性能瓶颈。让你的新闻列表既美观又流畅。