当前位置：首页 > news >正文

HarmonyOS ArkTS声明式UI实战：可刷新排行榜页面开发全解析

news 2026/6/2 23:55:53

1. 项目概述与核心价值

最近在捣鼓HarmonyOS应用开发，想找个能综合练习声明式UI和状态管理的实战案例，排行榜页面是个绝佳的选择。它麻雀虽小五脏俱全，几乎涵盖了日常开发中80%的UI组件交互场景：列表渲染、数据绑定、组件通信、状态管理，甚至还能捎带上生命周期函数。很多新手朋友学完基础语法后，面对一个完整的页面常常不知从何下手，感觉知识点是散的。这个“可刷新的排行榜”项目，就是帮你把这些散落的珍珠串成项链。

这个页面最终要实现的效果是：一个顶部带刷新按钮的标题栏，一个展示排名的列表，点击列表项能切换样式，点击系统返回键还有二次确认的交互。听起来简单，但里面用到的@State、@Prop、Link、@Builder以及ForEach循环渲染，正是构建复杂HarmonyOS应用的基石。我会带你从零开始，不仅复现功能，更重点拆解每个技术选择背后的“为什么”，比如为什么这里用@Link而不是@Prop，@Builder到底解决了什么痛点。无论你是刚接触ArkTS的新手，还是想深化对HarmonyOS UI框架理解的中级开发者，这个案例都能让你获得即学即用的、能直接搬到你自己项目里的代码经验和设计思路。

2. 环境准备与工程创建

2.1 开发环境配置详解

工欲善其事，必先利其器。首先确保你的开发环境是匹配的。根据官方推荐，我们使用DevEco Studio 3.1 Release版本，SDK选择API 9。为什么是API 9？因为它提供了稳定的声明式开发范式支持，并且兼容性广。如果你安装了更高版本，通常也向下兼容，但为了避免一些潜在的、未被发现的兼容性问题，在学习和复现特定案例时，严格遵循推荐的版本是最稳妥的做法。

注意：安装DevEco Studio时，务必勾选ArkTS相关的工具链。有时候默认安装可能不全，导致后续编译报错。安装完成后，打开IDE，在Settings（或Preferences） >SDK Manager中，确认OpenHarmony SDK和Toolchains都已正确安装。

硬件方面，我们以润和RK3568开发板为例，系统为OpenHarmony 3.2 Release。选择RK3568是因为它在社区和教学场景中非常普及，资料丰富，烧录和调试流程成熟。当然，如果你手头是其他符合标准系统要求的开发板（如Hi3516DV300等），整体代码逻辑是完全通用的，仅在设备连接和签名配置环节略有差异。

2.2 工程创建与结构初始化

环境就绪后，我们开始创建工程。打开DevEco Studio，选择Create Project。在模板选择页面，我们找到Empty Ability模板。这里有个关键点：为什么不选Empty Ability (ArkTS)之外的模板？因为其他模板（如JS或eTS旧范式）的语法和项目结构与我们即将使用的声明式ArkTS不同，Empty Ability模板为我们提供了一个最纯净的、基于声明式UI的起点，避免了无关代码的干扰。

创建工程时，Project Name可以命名为RankListDemo，Bundle Name按自己习惯定义即可。Save Location注意不要放在中文或过深路径下，以防一些工具链处理时出现意外错误。点击Finish后，DevEco Studio会自动构建项目。

项目创建完成后，我们花几分钟看一下自动生成的核心目录结构，这对后续代码组织至关重要：

entry/src/main/ets/ ├── entryability │ └── EntryAbility.ts // 应用入口，管理应用生命周期 ├── pages │ └── Index.ets // 默认生成的首页，我们将改造它 └── resources // 存放字符串、颜色、图片等资源

我们的主要工作将在pages目录下进行。但为了更好的代码组织，我们会参照案例，创建更清晰的结构。在ets目录下，右键新建目录：common（公共常量）、model（数据模型）、view（自定义组件）、viewmodel（视图模型）。这是一种常见的、利于维护的架构模式，将UI、数据和逻辑分离。

3. 核心概念与设计思路拆解

在动手写代码前，我们必须把几个核心装饰器和工作原理吃透。很多开发者踩坑，不是因为代码写不出来，而是因为用错了状态管理方式，导致数据流混乱，页面更新不符合预期。

3.1 状态管理装饰器：@State, @Prop, @Link 的本质区别

这是HarmonyOS声明式开发中最关键的一环。你可以把它们理解为组件之间数据流动的“管道协议”。

@State：组件内部的状态源。它装饰的变量是组件内部的状态数据，可以初始化。当这个变量的值发生变化时，它会驱动当前组件的build()方法重新执行，从而更新UI。它是数据变化的“发源地”。在本案例中，页面是否刷新数据（isSwitchDataSource）这个最根本的状态，就应该用@State来管理。

@Prop：从父组件来的单向数据流。@Prop装饰的变量必须从父组件初始化（通常通过参数传入），它接收来自父组件（通常是@State或@Link）的数据。子组件可以修改@Prop变量的值，但这个修改仅限于子组件内部，不会反向通知父组件。这就像父亲给了儿子一本书，儿子可以在书上做笔记（修改），但父亲手里的书不会自动出现这些笔记。案例中，列表项（ListItemComponent）是否切换数据源（isSwitchDataSource）这个状态，是从父页面传下来的，且列表项内部的修改不需要通知父页面，这就非常适合用@Prop。

@Link：与父组件的双向绑定。@Link装饰的变量同样从父组件初始化，但它与父组件对应的@State变量建立了双向连接。任何一方修改这个数据，另一方都会同步更新。这就像父子共用一份云端文档，任何一方的编辑都会实时同步给对方。案例中，标题栏组件（TitleComponent）里的刷新状态（isRefreshData）需要与页面的刷新状态同步，点击标题栏的刷新按钮，页面列表要立刻感知并刷新，这就必须使用@Link。

实操心得：如何快速决定用哪个？问自己两个问题：1. 这个状态是当前组件“私有”的还是需要从外部传入？2. 子组件对状态的修改是否需要通知父组件？私有且自用 ->@State；从外来，子改不需通知父 ->@Prop；从外来，子改需同步父 ->@Link。

3.2 @Builder：可复用的UI描述块

@Builder装饰的方法不是一个执行逻辑的函数，而是一个UI描述的定义。它允许你将一段UI结构封装起来，像函数一样在build()方法或其他@Builder方法中调用。它的核心价值在于：

代码复用与整洁：避免在build()方法中堆砌巨量的UI代码，尤其是当某段结构（如列表项、卡片）被多次使用时。
逻辑与UI分离：可以将一些带有简单逻辑（如条件判断）的UI片段抽离出来，让主build()方法更清晰。在本案例中，整个排行榜列表区域（RankList）被抽离成一个@Builder方法，这样主页面的build()结构就变得非常简洁：标题、表头、列表，一目了然。

3.3 渲染控制语法：ForEach 与条件渲染

动态列表是移动端应用的标配。ArkTS提供了ForEach方法来遍历数组并生成对应的组件集合。

ForEach( arr: Array<any>, // 数据源数组 itemGenerator: (item: any, index?: number) => void, // 生成每个项目的UI keyGenerator?: (item: any, index?: number) => string // 为每个项目生成唯一键 )

关键点在于keyGenerator。这个可选的参数极其重要。框架通过这个“键”来识别数组中的每一项。当数组发生变化（增、删、改、排序）时，高效的key能帮助框架精准地知道哪些组件需要更新、移动或销毁，而不是粗暴地重新渲染整个列表，这能极大提升长列表的性能。最佳实践是使用数据项中真正唯一且稳定的标识符（如item.id），而不是数组索引index，因为索引在数组变动时并不稳定。

条件渲染（if/else）则用于根据状态动态显示不同的UI分支，在本案例中用于控制显示圆形排名数字还是普通数字。

4. 数据模型与视图模型构建

4.1 定义实体类 (RankData.ets)

数据是应用的血液。我们先在viewmodel目录下创建RankData.ets，定义一个表示排行榜单项数据的实体类。

// RankData.ets export class RankData { name: string; // 名称 vote: string; // 票数或分数 constructor(name: string, vote: string) { this.name = name; this.vote = vote; } }

这里使用class而不是interface，是因为我们后续可能需要实例化并包含一些方法。字段类型定义为string是为了展示方便，vote在实际项目中可能是number类型用于计算。

4.2 创建视图模型 (RankViewModel.ets)

视图模型（ViewModel）负责准备和管理UI所需的数据和状态，它将业务逻辑从UI组件中剥离出来。在viewmodel目录下创建RankViewModel.ets。

// RankViewModel.ets import { RankData } from './RankData'; export class RankViewModel { // 数据源一 private dataSource1: Array<RankData> = [ new RankData('项目A', '12560'), new RankData('项目B', '11023'), new RankData('项目C', '9820'), new RankData('项目D', '8754'), new RankData('项目E', '7601'), ]; // 数据源二 private dataSource2: Array<RankData> = [ new RankData('任务一', '98%'), new RankData('任务二', '87%'), new RankData('任务三', '76%'), new RankData('任务四', '65%'), new RankData('任务五', '54%'), ]; // 获取数据源（根据状态决定返回哪一个） getRankList(isSwitch: boolean): Array<RankData> { return isSwitch ? this.dataSource1 : this.dataSource2; } }

为什么要把数据源放在ViewModel里，而不是直接写在页面组件里？这遵循了关注点分离原则。页面组件（RankPage）只应该关心如何渲染UI和响应用户交互，至于数据从哪里来（本地模拟、网络请求）、如何加工，应该由ViewModel负责。这样，当未来需要将模拟数据替换为网络接口时，你只需要修改ViewModel，页面组件几乎不用动，大大提升了代码的可维护性和可测试性。

5. 自定义组件封装与实践

5.1 标题组件 (TitleComponent.ets) 与 @Link 实战

在view目录下创建TitleComponent.ets。这个组件包含一个刷新按钮，点击后需要通知父页面刷新列表。

// TitleComponent.ets @Component export struct TitleComponent { @Link isRefreshData: boolean; // 双向绑定父页面的刷新状态 @State title: Resource = $r('app.string.title_default'); // 组件内部标题状态 build() { Row() { // 左侧标题 Text(this.title) .fontSize(20) .fontWeight(FontWeight.Bold) .layoutWeight(1) // 使用权重布局占满剩余空间 // 右侧刷新按钮区域 Row() { Image($r('app.media.ic_refresh')) // 刷新图标，需提前放入resources目录 .height(24) .width(24) .onClick(() => { // 点击按钮，切换刷新状态。这个变化会通过@Link同步到父组件 this.isRefreshData = !this.isRefreshData; // 可以在这里添加按钮点击动画效果，例如旋转 }) } .height('100%') .justifyContent(FlexAlign.End) // 内容右对齐 } .width('100%') .height(56) .padding({ left: 12, right: 12 }) .backgroundColor($r('app.color.title_bg')) } }

关键解析：

@Link isRefreshData: 这个变量通过@Link与父页面中的某个@State变量绑定。当子组件内修改this.isRefreshData时，父页面中对应的状态变量也会立刻改变，从而触发父页面重新渲染。
@State title: 这个标题文字如果只是静态展示，其实可以用常规变量。这里用@State是为了演示：即使组件内部有@State，也不影响它通过@Link与父组件通信。在实际项目中，如果标题是固定的，完全可以去掉@State，直接用private title: Resource。
layoutWeight(1): 这是弹性布局（Flex）中的权重属性。它让左侧的Text组件占据Row中除右侧刷新按钮区域外的所有剩余空间，是实现左右布局的常用技巧。

5.2 列表头部组件 (ListHeaderComponent.ets)

这个组件比较简单，用于显示列表的表头（如“排名”、“名称”、“票数”）。它不接受动态状态，只依赖传入的样式参数。

// ListHeaderComponent.ets @Component export struct ListHeaderComponent { // 通过构造函数传入的参数，属于常规变量，变化不会触发UI更新 private paddingValue: Padding | Length = 0; private widthValue: Length = 0; // 构造函数，用于接收父组件传递的参数 constructor(padding: Padding | Length, width: Length) { this.paddingValue = padding; this.widthValue = width; } build() { Row() { Text($r('app.string.rank')) .fontSize(14) .width('15%') .fontColor($r('app.color.font_secondary')) Text($r('app.string.name')) .fontSize(14) .width('60%') .fontColor($r('app.color.font_secondary')) Text($r('app.string.votes')) .fontSize(14) .width('25%') .fontColor($r('app.color.font_secondary')) } .width(this.widthValue) .padding(this.paddingValue) .backgroundColor($r('app.color.list_header_bg')) } }

注意：这个组件没有使用任何状态管理装饰器（@State、@Prop、@Link）。它的所有属性都在创建时通过构造函数一次性设置，之后不再改变。这种组件称为无状态组件，性能开销最小。在设计中，应尽可能将组件设计为无状态的。

5.3 列表项组件 (ListItemComponent.ets) 与 @Prop 实战

这是最复杂的子组件，它演示了@Prop的单向绑定和组件内部@State的管理。

// ListItemComponent.ets @Component export struct ListItemComponent { // 从父组件传入的索引和数据显示 private index?: number; private name?: string; @Prop vote: string = ''; // 票数，单向绑定 @Prop isSwitchDataSource: boolean = false; // 是否切换数据源标志，单向绑定 // 组件内部状态，控制文字颜色是否变化 @State isChange: boolean = false; build() { Row() { // 排名列：根据索引决定显示圆形还是普通数字 Column() { if (this.index !== undefined && this.index <= 3) { // 前三名显示为圆形背景 Text(this.index.toString()) .textAlign(TextAlign.Center) .fontSize(16) .fontColor(Color.White) .backgroundColor($r('app.color.top3_bg')) .borderRadius(20) .width(40) .height(40) } else { // 其他名次普通显示 Text(this.index?.toString() ?? '') .fontSize(14) .textAlign(TextAlign.Center) .width(40) } } .width('15%') // 名称列 Text(this.name ?? '') .fontSize(16) .fontWeight(this.isChange ? FontWeight.Bold : FontWeight.Normal) .fontColor(this.isChange ? $r('app.color.primary') : Color.Black) .width('60%') // 票数列 Text(this.vote) .fontSize(14) .fontColor(this.isChange ? $r('app.color.primary') : Color.Gray) .width('25%') .textAlign(TextAlign.End) } .width('100%') .height(60) .padding({ left: 12, right: 12 }) .backgroundColor(Color.White) .onClick(() => { // 点击事件 // 1. 修改内部状态，触发自身UI更新（文字颜色/加粗） this.isChange = !this.isChange; // 2. 修改@Prop变量。注意：这个修改不会通知父组件！ this.isSwitchDataSource = !this.isSwitchDataSource; }) } }

深度解析与避坑指南：

@Prop的“单向性”实验：注意onClick事件中，我们同时修改了this.isChange（@State）和this.isSwitchDataSource（@Prop）。修改@State会立刻让当前组件重新渲染，所以你点击列表项，它的颜色会变。但是，修改@Prop变量isSwitchDataSource，这个变化不会传回给父组件（RankPage）。因此，父组件中用于控制数据源切换的那个状态isSwitchDataSource（我们稍后会在主页定义）并不会改变。这就直观验证了@Prop的单向数据流特性。
条件渲染的运用：我们使用if/else根据排名索引（index）来决定是渲染一个带圆形背景的文本还是普通文本。这种根据状态动态构建UI的能力是声明式UI的核心。
样式与逻辑分离建议：实际项目中，像40、'15%'、$r('app.color.primary')这样的魔法数字和颜色值，应该抽取到common/constants目录下的常量文件中统一管理，例如Style.ets或Color.ets。这极大方便了后期主题切换和整体样式调整。

6. 主页面集成与核心逻辑实现

6.1 主页面结构 (RankPage.ets) 与 @Builder 使用

现在，我们把所有零件组装起来。修改pages目录下的Index.ets，或新建RankPage.ets作为主页面。

// RankPage.ets import { TitleComponent } from '../view/TitleComponent'; import { ListHeaderComponent } from '../view/ListHeaderComponent'; import { ListItemComponent } from '../view/ListItemComponent'; import { RankViewModel } from '../viewmodel/RankViewModel'; import { RankData } from '../viewmodel/RankData'; import prompt from '@ohos.promptAction'; @Entry @Component struct RankPage { // 控制数据源切换的核心状态 @State isSwitchDataSource: boolean = false; // 视图模型实例，提供数据 private rankViewModel: RankViewModel = new RankViewModel(); // 用于处理返回键的生命周期变量 private clickBackTimeRecord: number = 0; private readonly BACK_PRESS_INTERVAL: number = 2000; // 2秒内再次点击退出 // 获取当前应显示的数据列表 private getCurrentData(): Array<RankData> { return this.rankViewModel.getRankList(this.isSwitchDataSource); } build() { Column() { // 1. 标题栏组件：传递@State变量建立@Link绑定 TitleComponent({ isRefreshData: $isSwitchDataSource }) // 2. 列表头部 ListHeaderComponent({ paddingValue: { left: 16, right: 16 }, widthValue: '100%' }) .margin({ top: 10, bottom: 10 }) // 3. 列表区域：使用@Builder方法构建，使结构更清晰 this.RankList() } .width('100%') .height('100%') .backgroundColor($r('app.color.page_bg')) } // @Builder 修饰的方法，用于描述列表UI @Builder RankList() { Column() { List() { // 使用ForEach循环渲染数据 ForEach( this.getCurrentData(), // 数据源数组 (item: RankData, index?: number) => { ListItem() { // 创建每一个列表项组件 ListItemComponent({ index: (index ?? 0) + 1, // 排名从1开始 name: item.name, vote: item.vote, isSwitchDataSource: this.isSwitchDataSource // 传递@Prop }) } }, (item: RankData) => item.name // 关键！使用name作为唯一键，实际项目应用id ) } .width('100%') .height('100%') .divider({ strokeWidth: 1, color: $r('app.color.divider') }) } .padding({ left: 16, right: 16 }) .width('100%') .alignItems(HorizontalAlign.Start) } }

代码精讲：

$操作符：在向子组件传递@State变量时，使用$符号（如$isSwitchDataSource）创建对状态变量的引用。对于TitleComponent，它需要@Link绑定，所以传$isSwitchDataSource。对于ListItemComponent，它只需要@Prop单向接收，所以直接传this.isSwitchDataSource的值。
@Builder RankList()：将整个列表的构建逻辑抽离出来。这样做之后，主build()方法变得非常清爽，易于阅读和维护。@Builder方法里可以访问组件内的状态（如this.isSwitchDataSource）。
ForEach的键生成器：这里简单使用了item.name作为键。但在真实项目中，这是一个隐患！如果列表数据中存在同名项，会导致键冲突，可能引发渲染错误。最佳实践是确保数据模型中有唯一标识符（如id），并使用item.id作为键。
数据获取：通过getCurrentData()方法从ViewModel获取数据。将isSwitchDataSource状态传递给ViewModel，由ViewModel决定返回哪一套数据，实现了状态与数据源的解耦。

6.2 自定义组件生命周期：onBackPress 实践

HarmonyOS的自定义组件有一系列生命周期回调，onBackPress是其中比较常用的一个，它在用户点击系统返回键时触发。

// 在RankPage结构体内，与build()方法同级 @Entry @Component struct RankPage { // ... 其他状态和属性 // 系统返回键点击事件回调 onBackPress(): boolean { const currentTime = new Date().getTime(); // 判断是否在2秒内第二次点击 if (currentTime - this.clickBackTimeRecord <= this.BACK_PRESS_INTERVAL) { // 2秒内再次点击，返回false，系统处理退出 prompt.showToast({ message: '再见！', duration: 1000 }); return false; } else { // 第一次点击，或距离上次点击超过2秒 prompt.showToast({ message: '再按一次退出应用', duration: 2000 }); // 记录本次点击时间 this.clickBackTimeRecord = currentTime; // 返回true，表示自己消费了这次返回事件，阻止系统默认退出行为 return true; } } }

生命周期函数要点：

onBackPress、onPageShow、onPageHide这些生命周期函数，仅对用@Entry装饰的、作为页面入口的组件生效。普通组件没有这些回调。
onBackPress需要返回一个boolean值。返回true表示组件自己已经处理了返回逻辑，系统不再执行默认的返回动作（如关闭页面）。返回false则表示交由系统处理。
这里实现的是一个常见的“再按一次退出”功能。通过记录上次点击时间，判断是否为连续快速点击，从而提升用户体验，防止误触退出。

7. 资源定义与常量管理

一个规范的项目离不开良好的资源管理。在resources目录下的对应文件中进行定义。

字符串资源 (src/main/resources/base/element/string.json):

{ "string": [ { "name": "app_name", "value": "排行榜Demo" }, { "name": "title_default", "value": "排行榜" }, { "name": "rank", "value": "排名" }, { "name": "name", "value": "名称" }, { "name": "votes", "value": "票数" }, { "name": "prompt_text", "value": "再按一次退出应用" } ] }

颜色资源 (src/main/resources/base/element/color.json):

{ "color": [ { "name": "page_bg", "value": "#F5F5F5" }, { "name": "title_bg", "value": "#FFFFFF" }, { "name": "primary", "value": "#007DFF" }, { "name": "list_header_bg", "value": "#F0F0F0" }, { "name": "font_secondary", "value": "#666666" }, { "name": "top3_bg", "value": "#FF6A00" }, { "name": "divider", "value": "#E0E0E0" } ] }

媒体资源：将刷新按钮的图标（如ic_refresh.png）放入src/main/resources/base/media/目录。

常量文件 (common/constants/Style.ets): 在ets/common/constants/下创建Style.ets，统一管理尺寸、边距等。

// Style.ets export class Style { // 尺寸 static readonly TITLE_BAR_HEIGHT: Length = 56; static readonly LIST_ITEM_HEIGHT: Length = 60; static readonly LIST_HEADER_HEIGHT: Length = 40; static readonly ICON_SIZE: Length = 24; // 边距 static readonly PAGE_PADDING: Length = 16; static readonly ITEM_PADDING_HORIZONTAL: Length = 12; // 颜色（也可直接引用资源，这里提供另一种管理思路） static readonly COLOR_PRIMARY: string = '#007DFF'; static readonly COLOR_BACKGROUND: string = '#F5F5F5'; }

然后在组件中引入并使用：import { Style } from '../common/constants/Style';，并使用Style.TITLE_BAR_HEIGHT。这种方式比硬编码要优雅得多，后期修改样式只需改动这一个文件。

8. 真机调试与常见问题排查

8.1 连接设备与运行

确保RK3568开发板已烧录正确的OpenHarmony镜像，并通过USB连接电脑。
在DevEco Studio中，打开File > Project Structure > Project > Signing Configs，配置正确的签名证书（对于真机调试，通常需要使用debug证书）。
在顶部工具栏的设备选择器中，选择你的RK3568设备。
点击绿色的运行按钮（或使用快捷键Shift+F10）。DevEco Studio会自动编译、打包、安装并运行应用到开发板上。

8.2 常见问题与解决方案实录

在实际开发中，你几乎一定会遇到下面这些问题。这里是我踩过坑后总结的排查思路：

问题一：页面空白，控制台无报错，或报错“组件未正确构建”。

可能原因1：@Entry装饰器缺失或位置错误。@Entry必须且只能装饰一个作为应用入口的组件。检查你的主页面struct是否被@Entry正确装饰。
可能原因2：build()方法返回值错误或结构异常。build()方法必须返回一个合法的UI组件（如Column、Row、Stack等）。检查build()方法内所有括号是否配对，最后一行是否是组件。
排查技巧：尝试先构建一个极简页面，比如只返回一个Text('Hello')的Column，确认基础环境无误后，再逐步添加复杂组件。

问题二：点击标题栏刷新按钮，列表数据无变化。

可能原因1：@Link绑定失败。检查TitleComponent中isRefreshData变量是否用@Link装饰，并且在父页面RankPage中传递时是否使用了$符号（$isSwitchDataSource）。
可能原因2：数据源未响应状态变化。检查RankPage中，ForEach的数据源是否依赖于那个被@Link绑定的状态变量（isSwitchDataSource）。确保getCurrentData()方法或直接用于ForEach的数组，能根据isSwitchDataSource的值返回不同的数据。
排查技巧：在TitleComponent的onClick事件和RankPage的build()方法开始处，使用console.log打印状态变量的值，观察点击前后状态是否同步变化，以及build()方法是否被调用。

问题三：列表滚动卡顿，或数据更新时闪烁。

可能原因：ForEach的keyGenerator未设置或设置不当。这是性能问题的首要怀疑对象。如果未提供键或使用数组索引作为键，当数组变化时，框架无法高效复用组件，可能导致全部重新渲染。
解决方案：确保你的RankData实体类有一个唯一且稳定的字段（如id），并在ForEach中将其作为键：(item: RankData) => item.id。
排查技巧：对于复杂列表项，可以给组件添加一个aboutToAppear生命周期回调，在里面打印日志，观察哪些项被重新创建了。

问题四：@Prop变量在子组件内修改，但父组件看不到变化。

这是预期行为，不是问题。@Prop的设计就是单向数据流。如果你需要子组件的修改通知父组件，应该使用@Link。请重新审视你的组件通信设计。

问题五：真机调试时，提示“安装失败”或“签名错误”。

可能原因1：签名配置错误。确认在Signing Configs中为debug类型配置了正确的证书文件（.p12）和Profile文件（.p7b）。通常DevEco Studio在创建项目时会自动生成调试证书，确保其未被删除或损坏。
可能原因2：设备上已存在相同包名但签名不同的应用。卸载设备上已有的同名应用，再重新安装。
可能原因3：网络权限等敏感权限未声明。如果应用需要网络等功能，需在module.json5文件的requestPermissions字段中声明。

问题六：资源$r('app.string.xxx')引用报错或显示为空。

可能原因1：资源ID拼写错误或不存在。仔细检查string.json中name字段的值是否与代码中引用的完全一致，注意大小写。
可能原因2：资源文件未正确同步或编译。尝试点击Build > Clean Project，然后Build > Rebuild Project，清理并重新构建项目。
排查技巧：对于图片资源，还要检查其是否放在正确的目录（base/media）下，以及格式是否受支持。

9. 项目总结与扩展思考

走完整个排行榜页面的开发流程，你会发现一个看似简单的功能，背后串联起了HarmonyOS声明式开发的精髓：用@State、@Prop、@Link构建清晰的数据流，用@Builder和组件化拆分复杂UI，用ForEach高效处理列表，再用生命周期函数处理边界交互。

这个项目完全可以作为你下一个实际应用的起点。你可以尝试以下扩展练习，把知识真正变成自己的能力：

接入真实数据：将RankViewModel中的模拟数据，替换为从网络API获取。学习使用@ohos.net.http模块发起请求，并在请求返回后，通过@State更新数据源，观察列表如何自动刷新。
增加交互复杂度：为列表项添加“点赞”或“投票”按钮，点击后票数增加。思考这个“票数”状态应该放在哪里（Item内部@State？还是提升到父页面的@State数组里？），不同的选择对数据流和性能有什么影响。
实现下拉刷新：利用<Refresh>组件或List的onScroll事件，实现经典的下拉刷新列表功能，这比点击标题栏刷新更符合移动端习惯。
优化性能：如果列表数据量很大（比如1000条），尝试实现列表项回收、图片懒加载等优化策略，感受ArkUI引擎的优化能力。