从零到一：用 ArkTS 声明式 UI 开发你的第一个鸿蒙应用

写在前面

ArkTS 是 HarmonyOS 应用开发的核心语言，它在 TypeScript 的基础上扩展了声明式 UI 和状态管理等能力。对习惯了 Web 前端开发的工程师来说，ArkTS 的上手曲线非常平缓——你几乎可以把自己熟悉的组件、props、状态管理直觉直接迁移过来。本文以一个可运行的"待办清单"小应用为例，完整走一遍开发流程：环境搭建、页面搭建、状态驱动 UI、列表渲染与点击交互，并附上我在鸿蒙开发实践中心做每日案例浏览时踩过的几个坑。

一、环境准备

开发鸿蒙应用需要 DevEco Studio。到华为开发者官网下载对应操作系统的安装包，首次启动时会引导你安装 SDK 与工具链。这里提醒两点：

1. Node 版本：DevEco Studio 内置了自己的工具链，不需要额外全局安装 Node，建议不要让本机的高版本 Node 干扰其内部构建；
2. 模拟器：如果没有真机，可以在 Device Manager 里创建本地模拟器，登录开发者账号后即可使用，日常调 UI 完全够用。

创建项目时选择"Application → Empty Ability"，语言选 ArkTS，模板会生成 entry 模块，这就是应用的主模块。

二、理解 @Entry 与 @Component

新建的 Index.ets 大致长这样：

@Entry
@Component
struct Index {
  @State message: string = 'Hello World'

  build() {
    Column() {
      Text(this.message)
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

几个关键点：

• @Entry 标记页面入口，一个页面只能有一个；
• @Component 把 struct 变成自定义组件，UI 必须写在 build() 里；
• @State 是状态变量：当它变化时，引用它的 UI 会自动刷新，这就是声明式 UI 的核心心智模型。你不需要手动操作 DOM，改数据就够了。

如果把 Text(this.message) 换成点击修改 this.message，界面会立即跟着变：

Text(this.message)
  .fontSize(30)
  .onClick(() => {
    this.message = '你好，ArkTS'
  })

三、动手：50 行实现一个待办清单

下面是完整的待办清单页面，包含输入框、添加按钮、列表渲染、完成切换和删除：

@Entry
@Component
struct TodoList {
  @State items: Array<TodoItem> = [
    { text: '浏览鸿蒙开发案例', done: true },
    { text: '学习 ArkTS 状态管理', done: false }
  ]
  @State inputText: string = ''

  build() {
    Column({ space: 12 }) {
      Text('我的待办')
        .fontSize(26)
        .fontWeight(FontWeight.Bold)

      Row({ space: 8 }) {
        TextInput({ placeholder: '添加一条待办' })
          .onChange((v) => this.inputText = v)
          .layoutWeight(1)
        Button('添加')
          .onClick(() => {
            if (this.inputText.trim() === '') return
            this.items.push({ text: this.inputText, done: false })
            this.inputText = ''
          })
      }
      .width('100%')

      List({ space: 8 }) {
        ForEach(this.items, (item: TodoItem, idx: number) => {
          ListItem() {
            Row({ space: 8 }) {
              Checkbox()
                .select(item.done)
                .onChange(() => {
                  this.items[idx] = {
                    text: item.text,
                    done: !item.done
                  }
                })
              Text(item.text)
                .decoration({
                  type: item.done ? TextDecorationType.LineThrough : TextDecorationType.None
                })
                .layoutWeight(1)
              Image($r('sys.media.ohos_ic_public_delete'))
                .width(20).height(20)
                .onClick(() => {
                  this.items.splice(idx, 1)
                })
            }
            .width('100%')
          }
        }, (item: TodoItem) => item.text)
      }
      .layoutWeight(1)
      .width('100%')
    }
    .padding(16)
    .width('100%')
    .height('100%')
  }
}

interface TodoItem {
  text: string
  done: boolean
}

逐段拆解：

1. 数据结构：用 interface TodoItem 定义待办项，字段越简单越好，方便 ForEach 做键值管理。

2. 双输入状态：inputText 绑定输入框，items 绑定列表，两者都是 @State。注意 push 和 splice 这类数组原位操作在 ArkTS 中同样能触发刷新，因为 @State 对数组做了代理监听。

3. ForEach 的键值生成器：第三个参数返回唯一键。如果用 idx 当键，删除中间项时可能出现状态错位——这是我从"数独小游戏"案例页学习时印象最深的一个坑，案例评论区里不少人踩过。

4. 布局权重：layoutWeight(1) 类似前端的 flex:1，让输入框和文本在行内自适应伸展，避免写死宽度。

四、状态管理进阶：什么时候不用 @State

@State 只在组件内部生效。一旦开始拆组件，就会遇到父子传递：

• @Prop：父传子，单向同步，子组件内可改但不回传；
• @Link：双向同步，适合"子弹窗改父状态"；
• @Provide/@Consume：跨层级注入，类似 Context。

一个实用的判断标准：谁持有状态，谁用 @State；别人只是消费或回写，用 @Prop / @Link。上面的待办清单只有 50 行，拆成 TodoItem 子组件时，勾选回调改用 @Link 就能继续工作。

五、真机调试与发布

在 DevEco Studio 里用数据线连接真机，打开开发者模式和 USB 调试，点击 Run 即可安装运行。日志在 Log 窗口按 app 过滤，配合 hilog 标签能快速定位崩溃。

如果要发布上架 AppGallery，需要先在 AGC（AppGallery Connect）创建应用、填写证书与 Profile，然后 Build → Build Hap(s)/App(s) 生成签名包上传。个人练手项目建议先跑通"本地模拟器 → 真机"这条链路，发布流程等作品成型后再走。

六、写在最后

从"Hello World"到能交互的待办清单，核心只需要理解三件事：struct + build 的组件模型、@State 的状态驱动刷新、ForEEach 的列表渲染。HarmonyOS 的声明式 UI 与现代前端框架一脉相承，前端背景的同学可以把它当成"换了一套组件名的老朋友"。

接下来的练手方向建议：

1. 加上 @ohos.data.preferences 做本地持久化，重启不丢数据；
2. 接入 @ohos.notification，为到期待办发本地通知；
3. 把鸿蒙开发实践中心的数独、贪吃蛇等案例源码拉下来读一遍，比看文档更直观。

如果你也在做鸿蒙应用，欢迎在评论区交流你的踩坑经验。