开头

这一篇只讲一个主角：Rating。

做一个课程评分控件，点击星星后显示评分结果。 对新手来说，学习控件最有效的方法不是把官方属性一次背完，而是先把一个完整页面跑起来，然后围绕这个页面改尺寸、改状态、改事件。下面的代码就是配套截图 App 中已经编译通过的完整页面。

本篇目标

  • 看懂 Rating 的基础用法。
  • 能复制完整页面到 ArkTS 工程中运行。
  • 知道关键属性和事件分别控制什么。
  • 能基于同一个组件改出几个小样例。

在这里插入图片描述

对应 App 页面

配套 App 中，本篇对应页面文件是：

entry/src/main/ets/pages/RatingScorePage.ets

运行 App 后，从首页点击 Rating 入口即可进入本页截图。

完整页面代码

import { router } from '@kit.ArkUI';

@Entry
@Component
struct RatingScorePage {
  @State score: number = 4;

  build() {
    Column({ space: 18 }) {
      Row() {
        Button('<')
          .width(44)
          .height(36)
          .onClick(() => {
            router.back();
          })
        Text('Rating')
          .fontSize(22)
          .fontWeight(FontWeight.Bold)
          .layoutWeight(1)
          .textAlign(TextAlign.Center)
        Blank()
          .width(44)
      }
      .width('100%')

      Column({ space: 18 }) {
        Text('课程评分')
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .fontColor('#126A5E')

        Rating({ rating: this.score, indicator: false })
          .stars(5)
          .stepSize(1)
          .onChange((value: number) => {
            this.score = value;
          })

        Text(`你给了 ${this.score} 星`)
          .fontSize(18)
          .fontColor('#1F2933')
      }
      .width('100%')
      .padding(28)
      .borderRadius(8)
      .backgroundColor('#FFFFFF')
      .alignItems(HorizontalAlign.Center)
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .backgroundColor('#F7F2E8')
  }
}

核心属性和事件讲解

属性/事件 作用 本篇用法
rating 当前评分 绑定 this.score
indicator 是否只读 false 表示允许点击评分
.stars(5) 星星总数 常见 5 星评分
.stepSize(1) 每次变化步长 每次增减 1 星
.onChange() 评分变化事件 保存新评分

代码结构拆开看

1. 顶部返回栏

每个截图页都保留一个简单顶部栏：左边是返回按钮，中间是当前组件名称，右边用 Blank() 占位。这样做的好处是所有截图页面结构一致，后期整理文章配图时不会乱。

Row() {
  Button('<')
  Text('Rating')
  Blank()
}

2. 主体卡片

主体区域才是本篇组件的练习区。截图 Demo 里统一使用浅色背景和白色卡片，是为了让控件更清楚地被看到。真实项目里你可以把这些颜色替换成自己的设计规范。

3. 状态和事件

如果页面里有 @State，它就是驱动界面变化的数据。事件里修改状态，界面就会跟着刷新。这个规则在 Search、TextArea、Progress、Rating、Radio、Select、LoadingProgress 这些页面里都能看到。

再做几个小样例

样例 1：只读评分

Rating({ rating: 4, indicator: true })
  .stars(5)

样例 2：半星评分

Rating({ rating: this.score, indicator: false })
  .stepSize(0.5)

样例 3：评分文案

Text(this.score >= 4 ? '很满意' : '还可以继续改进')

新手常见问题

  1. 只复制了组件，没有复制 @State。如果组件依赖状态，页面会报错或无法交互。
  2. 只改了显示文本，没有改事件里的状态变量，导致看起来“点了没反应”。
  3. 截图页没有固定宽高或留白，模拟器尺寸一变，画面就挤在一起。

本篇小结

Rating 的学习重点是先把“能运行的完整页面”看懂，再去拆属性和事件。你可以直接使用本篇完整代码截图，也可以从“再做几个小样例”里挑一个继续改。

附录：项目设置与构建问题记录

一、项目设置

本篇配套一个独立 ArkTS 示例 App，用于运行页面和截图：
在这里插入图片描述

建议用 DevEco Studio 打开项目后运行 entry 模块。项目定位是截图练习 Demo，不依赖后端服务，也不需要额外权限。

建议新建或检查工程时保持以下设置：

  • Project type：Application。
  • Template：Empty Ability。
  • Language：ArkTS。
  • Model：Stage。
  • Device：Phone，可按需要兼容 Tablet、2in1。
  • Runtime OS：HarmonyOS。
    在这里插入图片描述
    在这里插入图片描述

二、SDK 版本

本文主题面向 HarmonyOS ArkTS API 24+。本次示例工程根目录 build-profile.json5 使用如下配置：

{
  "compatibleSdkVersion": "6.1.1(24)",
  "targetSdkVersion": "6.1.1(24)",
  "runtimeOS": "HarmonyOS"
}

如果本机 DevEco Studio SDK Manager 中安装的版本不同，请按本机实际 API 24+ SDK 调整 compatibleSdkVersion 和 targetSdkVersion。
在这里插入图片描述

三、项目目录说明

在这里插入图片描述

核心目录如下：

HarmonyOS_ArkTS_API24_ControlsScreenshotApp/
├── AppScope/
│   ├── app.json5
│   └── resources/
├── entry/
│   ├── src/main/ets/entryability/EntryAbility.ets
│   ├── src/main/ets/pages/
│   ├── src/main/resources/base/profile/main_pages.json
│   ├── build-profile.json5
│   └── oh-package.json5
├── build-profile.json5
├── hvigorfile.ts
└── oh-package.json5

页面文件都在：

entry/src/main/ets/pages/

路由注册文件在：

entry/src/main/resources/base/profile/main_pages.json

五、创建项目过程

  1. 打开 DevEco Studio。
  2. 点击 Create Project。
  3. 选择 Application。
  4. 模板选择 Empty Ability。
  5. 开发语言选择 ArkTS。
  6. 模型选择 Stage。
  7. 设置项目名称，例如 ArkTSControlsDemo。
  8. 选择保存路径，建议路径只包含英文、数字、下划线或连字符。
  9. 选择 API 24+ 对应 SDK。
  10. 点击 Finish，等待工程创建完成。
  11. 打开 entry/src/main/ets/pages/Index.ets。
  12. 运行默认工程，确认模拟器或真机能打开。
  13. 再逐个添加本文中的页面代码并截图。

六、本次编译安装遇到的问题与解决办法

1. 中文路径导致 Hvigor 拒绝构建

问题现象：

Invalid project path. Current path does not match: D:\私人资料\CSDN\HarmonyOS_ArkTS_API24_ControlsScreenshotApp

原因：Hvigor 对工程路径有限制，路径只能包含英文字母、数字、连字符、下划线、英文句点、英文括号、空格或 @。

处理办法：把项目复制到 ASCII 路径后构建：

D:\\HarmonyOS_ArkTS_API24_ControlsScreenshotApp

2. DEVECO_SDK_HOME 环境变量无效

问题现象：

Invalid value of 'DEVECO_SDK_HOME' in the system environment path.

处理办法：在当前命令会话中临时指定 DevEco SDK 根目录：

$env:DEVECO_SDK_HOME='D:\Program Files\Huawei\DevEco Studio Beta\sdk'

3. hvigor-config.json5 缺少 dependencies

问题现象：

Schema validate failed ... missingProperty: 'dependencies'

处理办法：补齐 hvigor/hvigor-config.json5：

{
  "modelVersion": "5.0.0",
  "dependencies": {
  }
}

4. 打包阶段找不到 Java

问题现象：

spawn java ENOENT

处理办法：使用 DevEco Studio 自带 JBR，并停止旧的 Hvigor daemon 后重新构建：

$env:JAVA_HOME='D:\Program Files\Huawei\DevEco Studio Beta\jbr'
$env:Path="D:\Program Files\Huawei\DevEco Studio Beta\jbr\bin;$env:Path"
hvigorw --stop-daemon

5. 构建成功但有弃用警告

构建时出现过 router.pushUrl、router.back、AlertDialog.show 的弃用警告，但不影响本次截图 Demo 编译和安装。正式项目建议后续按当前 API 推荐方式替换。

七、本次安装启动记录

构建命令：

hvigorw --mode module -p module=entry@default -p product=default assembleHap

安装命令：

hdc install entry-default-unsigned.hap

启动命令：

hdc shell aa start -a EntryAbility -b com.csdn.arkts.controls.screenshot

验证结果：

  • HAP 构建成功。
  • 模拟器目标：127.0.0.1:5555。
  • 安装结果：install bundle successfully。
  • 启动结果：start ability successfully。
# harmonyos # 交互 # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

【开发者实战】HarmonyOS AI开发提效完全指南：从DevEco Code到CLI，一套工具链搞定端侧AI应用

端侧 AI 的核心不在于模型有多强，而在于如何稳定地调度任务、管理资源。HarmonyOS 的 Taskpool 和 AOT 编译解决了大部分性能问题，但开发者需要理解它们的限制：Native 对象的跨线程传递、AOT 编译的 profile 匹配、多 Target 的版本一致性。DevEco Code 和 DevEco CLI 把工具链完整了，但真正的工程经验在于知道什么时候该用什么配置，什么时

avatar HarmonyOS开发者社区
cover

从0到1打造燃力Fit：HarmonyOS API 24智慧健身房应用的橙红主题、数据可视化与打卡闭环全解析

avatar HarmonyOS开发者社区
cover

芯笺 Markdown：面向 HarmonyOS PC 的本地优先 Markdown 编辑器

avatar HarmonyOS开发者社区