一、引言

在鸿蒙应用开发中，List 组件是构建长列表场景的核心组件。无论是新闻列表、设置页面还是聊天记录，都离不开它。本文将通过一个模仿新闻列表的实战案例，带你快速掌握 List 组件的核心用法。

二、效果预览与整体结构

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

整体布局结构如下：

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

三、核心代码实现

3.1 数据模型

首先，我们需要定义一个新闻数据模型，用于存储新闻标题、作者和发布时间。

// NewsItem.ets
export interface NewsItem {
  title: string;
  author: string;
  publishTime: string;
}

3.2 主页面布局

接下来，我们编写主页面，包含 TextInput 和 List 组件。

// 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。它包含新闻标题、作者和发布时间。

// 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，编译器会报错。

// ❌ 错误写法
List() {
  Column() { // 报错：List 的子元素只能是 ListItem 或 ListItemGroup
    // ...
  }
}

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

4.2 文本溢出处理

当新闻标题过长时，我们使用 maxLines 和 textOverflow 属性来控制显示行数和溢出后的省略号效果。

Text(this.newsItem.title)
  .maxLines(2) // 最大显示两行
  .textOverflow({ overflow: TextOverflow.Ellipsis }) // 超出显示省略号

4.3 Span 组件的妙用

在显示作者和发布时间时，我们使用了 Span 组件包裹在 Text 组件内部。这样做的好处是：

• 样式统一：Span 可以继承父级 Text 组件的样式（如字体大小、颜色）。
• 代码简洁：如果写成两个独立的 Text 组件，需要重复设置相同的样式属性。

// ✅ 推荐写法：使用 Span 组件
Text() {
  Span(this.newsItem.author)
  Span(' | ')
  Span(this.newsItem.publishTime)
}

// ❌ 不推荐写法：多个 Text 组件，代码冗余
Text(this.newsItem.author)
Text(' | ')
Text(this.newsItem.publishTime)

五、总结

通过本文的实战案例，我们学习了如何在鸿蒙应用中使用 List 组件构建一个新闻列表。关键点总结如下：

1. List 的子元素必须是 ListItem 或 ListItemGroup。
2. 使用 ForEach 遍历数据数组，动态渲染列表项。
3. 利用 maxLines 和 textOverflow 处理文本溢出。
4. 使用 Span 组件简化相同样式的文本布局。

掌握了这些核心用法，你就可以轻松应对各种列表场景的开发需求了。