开头
这一篇只讲一个主角：Rating。
做一个课程评分控件，点击星星后显示评分结果。 对新手来说，学习控件最有效的方法不是把官方属性一次背完，而是先把一个完整页面跑起来，然后围绕这个页面改尺寸、改状态、改事件。下面的代码就是配套截图 App 中已经编译通过的完整页面。
本篇目标
- 看懂 Rating 的基础用法。
- 能复制完整页面到 ArkTS 工程中运行。
- 知道关键属性和事件分别控制什么。
- 能基于同一个组件改出几个小样例。
对应 App 页面
配套 App 中，本篇对应页面文件是：
entry/src/main/ets/pages/RatingScorePage.ets运行 App 后，从首页点击 Rating 入口即可进入本页截图。
完整页面代码
import{router}from'@kit.ArkUI';@Entry@Componentstruct RatingScorePage{@Statescore: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?'很满意':'还可以继续改进')新手常见问题
- 只复制了组件，没有复制 @State。如果组件依赖状态，页面会报错或无法交互。
- 只改了显示文本，没有改事件里的状态变量，导致看起来“点了没反应”。
- 截图页没有固定宽高或留白，模拟器尺寸一变，画面就挤在一起。
本篇小结
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五、创建项目过程
- 打开 DevEco Studio。
- 点击 Create Project。
- 选择 Application。
- 模板选择 Empty Ability。
- 开发语言选择 ArkTS。
- 模型选择 Stage。
- 设置项目名称，例如
ArkTSControlsDemo。 - 选择保存路径，建议路径只包含英文、数字、下划线或连字符。
- 选择 API 24+ 对应 SDK。
- 点击 Finish，等待工程创建完成。
- 打开
entry/src/main/ets/pages/Index.ets。 - 运行默认工程，确认模拟器或真机能打开。
- 再逐个添加本文中的页面代码并截图。
六、本次编译安装遇到的问题与解决办法
1. 中文路径导致 Hvigor 拒绝构建
问题现象：
Invalid project path. Current path does not match: D:\私人资料\CSDN\HarmonyOS_ArkTS_API24_ControlsScreenshotApp原因：Hvigor 对工程路径有限制，路径只能包含英文字母、数字、连字符、下划线、英文句点、英文括号、空格或@。
处理办法：把项目复制到 ASCII 路径后构建：
D:\\HarmonyOS_ArkTS_API24_ControlsScreenshotApp2.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-daemon5. 构建成功但有弃用警告
构建时出现过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 aastart-a EntryAbility-b com.csdn.arkts.controls.screenshot验证结果：
- HAP 构建成功。
- 模拟器目标：
127.0.0.1:5555。 - 安装结果：
install bundle successfully。 - 启动结果：
start ability successfully。
