开头

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

展示一个任务完成度，并通过按钮模拟进度增加。 对新手来说，学习控件最有效的方法不是把官方属性一次背完，而是先把一个完整页面跑起来，然后围绕这个页面改尺寸、改状态、改事件。下面的代码就是配套截图 App 中已经编译通过的完整页面。

本篇目标

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

对应 App 页面

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

entry/src/main/ets/pages/ProgressTaskPage.ets

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

完整页面代码

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

@Entry
@Component
struct ProgressTaskPage {
  @State progress: number = 45;

  build() {
    Column({ space: 18 }) {
      Row() {
        Button('<')
          .width(44)
          .height(36)
          .onClick(() => {
            router.back();
          })
        Text('Progress')
          .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')
          .width('100%')

        Progress({ value: this.progress, total: 100, type: ProgressType.Linear })
          .width('100%')
          .height(16)

        Text(`当前进度：${this.progress}%`)
          .fontSize(18)
          .fontColor('#1F2933')
          .width('100%')

        Row({ space: 12 }) {
          Button('增加')
            .layoutWeight(1)
            .height(44)
            .onClick(() => {
              this.progress = Math.min(100, this.progress + 10);
            })
          Button('重置')
            .layoutWeight(1)
            .height(44)
            .onClick(() => {
              this.progress = 0;
            })
        }
        .width('100%')
      }
      .width('100%')
      .padding(24)
      .borderRadius(8)
      .backgroundColor('#FFFFFF')
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .backgroundColor('#F7F2E8')
  }
}

核心属性和事件讲解

属性/事件	作用	本篇用法
value	当前进度值	绑定 this.progress
total	总进度值	设置为 100
type	进度条类型	使用 ProgressType.Linear
.width('100%')	占满卡片宽度	适合截图展示
Math.min()	限制最大值	防止进度超过 100

代码结构拆开看

1. 顶部返回栏

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

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

2. 主体卡片

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

3. 状态和事件

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

再做几个小样例

样例 1：圆形进度

Progress({ value: this.progress, total: 100, type: ProgressType.Ring })
  .width(120)
  .height(120)

样例 2：进度完成提示

Text(this.progress >= 100 ? '任务完成' : '任务进行中')

样例 3：每次增加 5

this.progress = Math.min(100, this.progress + 5);

新手常见问题

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

本篇小结

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

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

一、项目设置

本篇配套一个独立 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。