HarmonyOS ArkTS 的新手练手样例：从 Text 和 Button 开始，做一个会变化的计数页面

开头

刚学 ArkTS 时，最容易迷糊的不是语法，而是"不知道页面为什么会自己刷新"。这一篇先用 Text、Button、Column、Row 做一个点击计数器：点一下按钮，页面上的数字自动变化。

你只要先记住一句话：在 ArkTS 声明式 UI 里，页面是由状态驱动的。状态变了，和它绑定的界面也会跟着变。

本篇目标

会用 Text 显示文字。
会用 Button 响应点击。
会用 Column 和 Row 排版。
理解 @State 的最基本作用。

示例代码

把下面代码放到页面文件中，例如 entry/src/main/ets/pages/Index.ets。

ts 复制代码

@Entry
@Component
struct Index {
  @State count: number = 0;

  build() {
    Column({ space: 20 }) {
      Text('ArkTS 控件入门')
        .fontSize(28)
        .fontWeight(FontWeight.Bold)

      Text(`当前点击次数：${this.count}`)
        .fontSize(20)
        .fontColor('#333333')

      Row({ space: 12 }) {
        Button('加 1')
          .onClick(() => {
            this.count += 1;
          })

        Button('清零')
          .onClick(() => {
            this.count = 0;
          })
      }
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
    .padding(24)
  }
}

小白看懂代码

@Entry 表示这是入口页面，应用启动后可以先看到它。

@Component 表示这是一个组件。ArkTS 页面本质上也是组件。

@State count: number = 0 是页面状态。count 变了，页面里用到 count 的地方会重新显示。

build() 是界面结构。你可以把它理解成"这个页面长什么样"。

Column 是纵向排列，Row 是横向排列。这里标题、次数、按钮区从上到下排，两个按钮在同一行。

Button('加 1') 创建按钮，.onClick() 绑定点击事件。点击后修改 this.count，页面上的数字就更新了。

新手常见错误

第一种错误：只定义普通变量，不加 @State。

ts 复制代码

count: number = 0;

这样点击后变量可能变了，但界面不一定按你预期刷新。需要页面响应变化的数据，应优先用 @State。

第二种错误：忘记写 this。

ts 复制代码

count += 1;

在组件内部访问成员变量，要写成：

ts 复制代码

this.count += 1;

第三种错误：把所有控件都堆在一起，不设置宽高和对齐。

新手练习时至少给最外层容器设置：

ts 复制代码

.width('100%')
.height('100%')

这样页面布局会更稳定。

可以怎么改

你可以把"加 1"改成"加 2"，也可以加一个"减 1"按钮。

ts 复制代码

Button('减 1')
  .onClick(() => {
    this.count -= 1;
  })

再进一步，可以根据点击次数显示不同提示：

ts 复制代码

Text(this.count >= 10 ? '已经点了很多次' : '继续试试')

本篇小结

Text 负责显示，Button 负责触发动作，@State 负责让数据和界面联动。只要你理解了这个小计数器，后面做输入框、列表、开关页面，本质也是同一套思路：用户操作改变状态，状态驱动界面变化。

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

一、项目设置

本篇配套一个独立 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 使用如下配置：

json5 复制代码

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

如果本机 DevEco Studio SDK Manager 中安装的版本不同，请按本机实际 API 24+ SDK 调整 compatibleSdkVersion 和 targetSdkVersion。

三、项目目录说明

核心目录如下：

text 复制代码

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

页面文件都在：

text 复制代码

entry/src/main/ets/pages/

路由注册文件在：

text 复制代码

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 拒绝构建

问题现象：

text 复制代码

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

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

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

text 复制代码

D:\\HarmonyOS_ArkTS_API24_ControlsScreenshotApp

2. `DEVECO_SDK_HOME` 环境变量无效

问题现象：

text 复制代码

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

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

powershell 复制代码

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

3. `hvigor-config.json5` 缺少 `dependencies`

问题现象：

text 复制代码

Schema validate failed ... missingProperty: 'dependencies'

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

json5 复制代码

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

4. 打包阶段找不到 Java

问题现象：

text 复制代码

spawn java ENOENT

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

powershell 复制代码

$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 推荐方式替换。

七、本次安装启动记录

构建命令：

powershell 复制代码

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

安装命令：

powershell 复制代码

hdc install entry-default-unsigned.hap

启动命令：

powershell 复制代码

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 ArkTS 的新手练手样例：从 Text 和 Button 开始，做一个会变化的计数页面

开头

本篇目标

示例代码

小白看懂代码

新手常见错误

可以怎么改

本篇小结

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

一、项目设置

二、SDK 版本

三、项目目录说明

五、创建项目过程

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

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

2. DEVECO_SDK_HOME 环境变量无效

3. hvigor-config.json5 缺少 dependencies

4. 打包阶段找不到 Java

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

七、本次安装启动记录

2. `DEVECO_SDK_HOME` 环境变量无效

3. `hvigor-config.json5` 缺少 `dependencies`