引言

随着HarmonyOS（简称“鸿蒙”）生态的持续扩张，ArkUI作为其核心UI开发框架，以“一次开发、多端部署”的特性深受开发者青睐。声明式开发模式相较于传统的命令式开发，能大幅提升UI构建效率，降低多端适配成本。本文将从环境搭建入手，通过一个实战案例带大家快速掌握ArkUI声明式开发的核心知识点，助力新手快速上手鸿蒙应用开发。

一、开发环境搭建

1.1 工具准备

鸿蒙开发的官方工具为DevEco Studio，建议下载最新稳定版（本文以DevEco Studio 4.0为例）。下载地址：https://developer.harmonyos.com/cn/develop/deveco-studio。

安装过程中需注意：勾选“HarmonyOS SDK”选项，工具会自动下载并配置基础SDK。若安装后未自动配置，可通过“Configure > Settings > Appearance & Behavior > System Settings > HarmonyOS SDK”手动更新。

1.2 项目创建

打开DevEco Studio，点击“Create Project”，选择“Application > Empty Ability”，点击“Next”。填写项目信息：

• Project Name：建议命名为“ArkUIFirstDemo”；
• Bundle Name：需符合包名规范，如“com.example.arkuifirstdemo”；
• Save Location：选择自定义路径；
• Compile SDK：选择最新的SDK版本（如API 10）；
• UI Syntax：选择“ArkTS”（声明式开发首选语言）；
• Device Type：勾选“Phone”和“Tablet”（演示多端适配）。
• 点击“Finish”，工具会自动构建项目结构，等待依赖下载完成即可。

二、ArkUI声明式核心概念

2.1 声明式思想核心

声明式开发的核心是“描述你想要的UI效果，而非如何实现”。相较于命令式开发中需手动控制UI控件的创建、更新、销毁流程，ArkUI通过状态驱动UI，当数据状态发生变化时，框架会自动更新对应的UI视图，开发者无需关注具体的更新逻辑。

2.2 关键组件与布局

ArkUI提供了丰富的内置组件，常用基础组件包括Text（文本）、Button（按钮）、Image（图片）、TextField（输入框）等；布局组件包括Row（横向布局）、Column（纵向布局）、List（列表）、Grid（网格）等，用于控制组件的排列方式。

布局规则：通过“flexDirection”“justifyContent”“alignItems”等属性控制子组件的排列方向、主轴对齐方式、交叉轴对齐方式，类似前端的Flex布局，上手成本较低。

2.3 状态管理基础

状态管理是声明式开发的核心，ArkUI中常用的状态装饰器包括：

• @State：组件内部状态，仅在当前组件及其子组件中生效，状态变化会触发UI更新；
• @Prop：父子组件间单向数据传递，子组件接收父组件的状态，仅可读取不可修改；
• @Link：父子组件间双向数据绑定，子组件可修改父组件传递的状态。

三、实战案例：简易待办清单APP

3.1 需求分析

实现一个简易待办清单，包含以下功能：1. 输入待办事项并添加；2. 展示待办事项列表；3. 点击待办事项标记为已完成（划横线）；4. 删除待办事项。

3.2 代码实现

import router from '@ohos.router';

@Entry
@Component
struct TodoList {
  // 定义待办事项列表状态，每个事项包含id、content、isCompleted
  @State todoList: Array<{ id: number, content: string, isCompleted: boolean }> = [];
  // 定义输入框内容状态
  @State inputValue: string = '';
  // 定义自增id，用于唯一标识待办事项
  private nextId: number = 1;

  build() {
    Column({ space: 16 }) {
      // 标题
      Text('简易待办清单')
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 30 })

      // 输入区域：输入框 + 添加按钮
      Row({ space: 10 }) {
        TextField({ placeholder: '请输入待办事项', text: this.inputValue })
          .width('70%')
          .height(40)
          .border({ width: 1, color: '#cccccc', radius: 4 })
          .padding({ left: 10 })
          // 输入框内容变化时更新inputValue状态
          .onChange((value: string) => {
            this.inputValue = value;
          })

        Button('添加')
          .width('20%')
          .height(40)
          .backgroundColor('#007aff')
          .fontColor('#ffffff')
          .borderRadius(4)
          // 点击添加待办事项
          .onClick(() => {
            if (this.inputValue.trim() !== '') {
              // 添加新事项到列表
              this.todoList.push({
                id: this.nextId++,
                content: this.inputValue.trim(),
                isCompleted: false
              });
              // 清空输入框
              this.inputValue = '';
            }
          })
      }
      .margin({ left: 20, right: 20 })

      // 待办列表
      List({ space: 10 }) {
        ForEach(this.todoList, (item) => {
          ListItem() {
            Row({ space: 10, alignItems: ItemAlign.Center }) {
              // 复选框：标记完成状态
              Checkbox()
                .checked(item.isCompleted)
                .onChange((isChecked: boolean) => {
                  // 找到当前事项并更新状态
                  let index = this.todoList.findIndex(todo => todo.id === item.id);
                  if (index !== -1) {
                    this.todoList[index].isCompleted = isChecked;
                  }
                })

              // 待办内容：已完成则划横线
              Text(item.content)
                .fontSize(18)
                .width('70%')
                .decoration({
                  type: item.isCompleted ? TextDecorationType.LineThrough : TextDecorationType.None,
                  color: item.isCompleted ? '#999999' : '#333333'
                })

              // 删除按钮
              Button('删除')
                .width('15%')
                .height(30)
                .backgroundColor('#ff3b30')
                .fontColor('#ffffff')
                .borderRadius(4)
                .onClick(() => {
                  // 过滤掉当前要删除的事项
                  this.todoList = this.todoList.filter(todo => todo.id !== item.id);
                })
            }
            .padding({ left: 10, right: 10, top: 5, bottom: 5 })
          }
        }, (item) => item.id.toString()) // 为每个列表项指定唯一key
      }
      .width('90%')
      .margin({ top: 10 })
    }
    .width('100%')
    .backgroundColor('#f5f5f5')
  }
}

3.3 代码解析

1. 状态定义：使用@State装饰器定义todoList（待办列表）和inputValue（输入框内容），确保状态变化时UI自动更新。

2. 布局结构：采用Column纵向布局包裹整个页面，内部包含标题、输入区域（Row横向布局）和待办列表（List）。

3. 交互逻辑：

• 添加功能：点击“添加”按钮时，判断输入框内容非空后，向todoList中添加新事项，并清空输入框；
• 完成标记：点击复选框时，通过findIndex找到当前事项，更新其isCompleted状态，Text组件通过decoration属性动态显示划横线效果；
• 删除功能：点击“删除”按钮时，通过filter过滤掉当前事项，实现列表项删除。

3.4 多端适配验证

在DevEco Studio中，点击工具栏的“Previewer”按钮，选择“Phone”（如P50 Pro）和“Tablet”（如MatePad Pro）预览界面。由于使用了百分比宽度和弹性布局，页面会自动适配不同屏幕尺寸，无需额外编写适配代码，体现了ArkUI“一次开发、多端部署”的优势。

四、总结与进阶方向

本文通过环境搭建和实战案例，带大家快速掌握了ArkUI声明式开发的核心知识点，包括组件使用、布局设计和基础状态管理。该案例虽简单，但覆盖了鸿蒙应用开发的常见场景，可在此基础上扩展更多功能，如本地存储（使用Preferences存储待办事项）、下拉刷新、滑动删除等。

进阶学习建议：1. 深入学习状态管理进阶内容，如@Provide/@Consume、AppStorage、LocalStorage；2. 研究自定义组件开发，封装可复用的UI组件；3. 探索多端部署的高级适配技巧，如自适应布局、设备特有功能调用。