【ArkUI 练中学】第1课：从零开始

本节目标

· 完成 DevEco Studio 的下载、安装与首次配置

· 掌握 HarmonyOS SDK 与 JDK 环境的基本配置方法

· 独立创建第一个 ArkTS 工程，并理解 Stage 模型工程目录结构

· 理解声明式 UI 的核心思想：描述结果、状态驱动视图更新

· 掌握 @Entry、@Component、@State 三个核心装饰器的作用

· 学会使用基础组件 Text、Button 和容器组件 Column、Row

· 能通过链式调用设置组件属性与事件

· 能运行或预览 Hello World 页面，并通过习题巩固本节知识

一、开发环境搭建

1.1 系统要求

在安装 DevEco Studio 之前，请确认你的电脑满足以下最低配置：

· 操作系统：Windows 10 64位 / macOS 10.15及以上

· 内存：建议 16GB 及以上（8GB 可运行但可能卡顿）

· 存储空间：至少 20GB 可用空间（含 SDK 和模拟器）

· JDK：需安装 OpenJDK 11 或 Oracle JDK 11（DevEco Studio 3.0+ 版本要求）

1.2 下载与安装 DevEco Studio

访问华为开发者联盟官网，进入"开发工具 → DevEco Studio"下载页面，选择对应操作系统的版本。建议优先选择稳定版（Stable Channel）。

Windows 安装步骤：

双击运行 .exe 安装程序
选择安装路径，避免使用中文目录
勾选"Add to PATH"选项以自动配置环境变量
完成安装后启动 DevEco Studio

macOS 安装步骤：

双击 .dmg 文件打开磁盘镜像
将 DevEco Studio 拖拽至"Applications"文件夹
首次启动时需在系统偏好设置中授权安全权限

1.3 首次启动配置

首次启动 DevEco Studio 时，需要进行以下配置：

导入设置：可选择从 Android Studio 导入配置或使用默认设置
SDK 配置：打开 File → Settings → Appearance & Behavior → System Settings → HarmonyOS SDK，配置 SDK 存储路径（建议与 IDE 安装路径分离），并安装必要组件（API Version、编译工具链等）
推荐插件：ArkTS 语言支持、CodeGlance（代码缩略图）、Rainbow Brackets（括号高亮）

常见问题：如果安装后无法打开，请检查安装路径是否包含中文或空格，并尝试以管理员权限运行。SDK 下载卡住时，可检查网络或切换华为镜像源。

二、创建第一个 ArkTS 项目

2.1 创建工程

首次打开 DevEco Studio 时，点击 Create Project 创建工程。如果已经打开了某个工程，请在菜单栏选择 File → New → Create Project 来创建新工程。

在模板选择界面，选择 Application 应用开发，模板选择 Empty Ability，点击 Next 进行下一步配置。在配置界面中，Compatible SDK 表示兼容的最低 API Version，其他参数保持默认即可。点击 Finish，工具会自动生成示例代码和相关资源，等待工程创建完成。

2.2 工程目录结构（Stage 模型）

创建完成后，左侧 Project 窗口会显示完整的目录结构。核心目录说明如下：

· AppScope > app.json5：应用的全局配置信息

· entry：HarmonyOS 工程模块，编译构建生成一个 HAP 包

· src > main > ets：用于存放 ArkTS 源码

· entryability：应用/服务的入口

· pages：应用/服务包含的页面

· src > main > resources：资源文件（图形、多媒体、字符串等）

· src > main > module.json5：模块配置文件

· build-profile.json5：模块级编译信息配置

· oh-package.json5：描述包名、版本和依赖项等信息

· build-profile.json5（工程级）：工程级配置信息，包括签名、产品配置等

· hvigorfile.ts：编译构建任务脚本

2.3 运行项目

工程创建完成后，打开 entry → src → main → ets → pages → Index.ets，点击右侧预览器即可查看 Hello World 页面效果。也可以在菜单栏选择 Run → Run 'entry' 将应用部署到模拟器或真机上运行。

三、核心知识点讲解

3.1 声明式 UI 的基本概念

应用界面由一个个页面组成，HarmonyOS 应用程序以 ArkUI 框架作为 UI 界面开发的基础，而 ArkTS 则是对 UI 开发提供了声明式语法的拓展。通过声明式 UI 构建页面，其实是组合组件的过程------通过组合基础组件形成自定义组件，进而组成页面，来描述应用界面应该呈现的结果。

声明式 UI 的思想主要体现在两个方面：

· 描述 UI 的呈现结果，而不关心过程：开发者只需描述页面在某个状态下应该长什么样，框架负责把状态变化同步到界面上。

· 状态驱动视图更新：视图是 UI 描述的结果，状态则是驱动视图动态变化的数据源。状态变量变化会触发 UI 刷新。

3.2 ArkTS 的基本组成

一个最简单的 ArkUI 页面如下：

typescript 复制代码

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('Hello HarmonyOS')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
      Button('开始')
        .margin({ top: 16 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

几个关键组成部分：

装饰器：用于装饰类、结构、方法以及变量，赋予其特殊的含义。@Entry 表示该自定义组件为页面入口组件，@Component 表示自定义组件，@State 表示组件中的状态变量。

UI 描述：以声明式的方式描述 UI 的结构，写在 build() 方法中。

自定义组件：可复用的 UI 单元，可组合其他组件。通过 struct 声明组件名，并用 @Component 装饰。

系统组件：ArkUI 框架默认内置的基础和容器组件，可以直接调用。基础组件负责展示或交互（如 Text、Image、Button），容器组件负责组织子组件（如 Column、Row、Stack）。

属性方法：组件通过链式调用配置多项属性，如 .fontSize()、.width()、.backgroundColor() 等。

事件方法：组件通过链式调用设置事件的响应逻辑，如 .onClick()。

3.3 状态管理与数据驱动

@State 装饰的变量是组件内部的状态数据，当状态变化时，框架会自动更新使用了该状态的 UI 部分。例如：

typescript 复制代码

@Entry
@Component
struct Hello {
  @State myText: string = 'World'
  build() {
    Column() {
      Text(`Hello ${this.myText}`)
        .fontSize(50)
      Divider()
      Button('Click me')
        .onClick(() => {
          this.myText = 'ArkUI'
        })
        .height(50)
        .width(100)
        .margin({ top: 20 })
    }
  }
}

点击按钮时，myText 从 "World" 变为 "ArkUI"，文本内容随之更新。

3.4 布局容器

ArkUI 中最基础的两个布局容器是：

· Column：纵向排列子组件

· Row：横向排列子组件

在 Column 和 Row 内部，通过花括号语法放置子组件的 UI 描述，再通过链式属性设置对齐方式。例如 justifyContent(FlexAlign.Center) 设置主轴居中，alignItems(HorizontalAlign.Center) 设置交叉轴居中。

四、多元化习题

习题 1（判断题）

题目：在 ArkTS 中，@Entry 装饰器表示该自定义组件为页面入口组件，页面加载时会首先进行渲染。

答案：正确

解读：@Entry 装饰的自定义组件作为页面的入口，会在页面加载时首先进行渲染。一个页面文件中通常只需要一个入口组件。

习题 2（单选题）

题目：以下哪个装饰器用于声明组件中的状态变量，使变量变化时自动触发 UI 刷新？

A. @Entry

B. @Component

C. @State

D. @Builder

答案：C

解读：@State 表示组件中的状态变量，状态变量变化会触发 UI 刷新。@Entry 标识页面入口组件，@Component 标识自定义组件，@Builder 用于封装可复用的 UI 描述方法。

习题 3（多选题）

题目：关于 ArkTS 声明式 UI 的特点，以下说法正确的有（多选）：

A. 开发者需要逐步指示每个 UI 元素的创建和属性设置过程

B. 开发者只需描述 UI 的最终状态和交互意图

C. 状态变化后，框架自动更新需要刷新的 UI 部分

D. UI 的呈现结果与数据状态之间建立了绑定关系

答案：B、C、D

解读：声明式 UI 遵循"描述即实现"的理念，开发者仅需声明 UI 的最终状态与交互意图，具体实现交由框架处理。状态驱动视图更新是声明式 UI 的核心特征------状态变化后框架会根据新的描述刷新需要变化的部分。选项 A 描述的是传统命令式 UI 的开发方式。

习题 4（代码填空题）

题目：请补全以下代码，使其实现一个简单的计数器：点击按钮时，数字加 1 并更新显示。

typescript 复制代码

@Entry
@Component
struct Counter {
  @State count: number = 0

  build() {
    Column() {
      Text(`当前计数：${this.count}`)
        .fontSize(30)
      Button('点击 +1')
        .onClick(() => {
          // 在此处填写代码
          ______________
        })
        .margin({ top: 20 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

答案：this.count++ 或 this.count += 1 或 this.count = this.count + 1

解读：@State 修饰的 count 是状态变量，在 onClick 回调中修改其值后，框架检测到状态变化，会自动重新渲染 build() 中使用了 this.count 的 Text 组件，从而更新显示的计数。

习题 5（代码改错题）

题目：以下代码存在错误，请指出问题并修正。

typescript 复制代码

@Component
struct MyComponent {
  @State message: string = 'Hello'
  build() {
    Text(this.message)
      .fontSize(30)
  }
}

答案：该组件被 @Component 装饰但没有被 @Entry 装饰。如果这是页面的入口组件，需要添加 @Entry 装饰器：

typescript 复制代码

@Entry
@Component
struct MyComponent {
  @State message: string = 'Hello'
  build() {
    Text(this.message)
      .fontSize(30)
  }
}

解读：@Component 表示这是一个自定义组件，但一个页面需要一个入口组件来标识页面加载时首先渲染的组件。@Entry 和 @Component 装饰的自定义组件作为页面入口。如果 MyComponent 只是作为其他页面的子组件使用，则不需要 @Entry，但当它是独立页面时必须添加。

习题 6（简答题）

题目：简述 Stage 模型中 entry/src/main/ets/pages 目录的作用，以及 module.json5 文件的主要功能。

答案：entry/src/main/ets/pages 目录用于存放应用/服务包含的页面，每个 .ets 文件对应一个页面。module.json5 是模块配置文件，主要包含 HAP 包的配置信息、应用/服务在具体设备上的配置信息以及应用/服务的全局配置信息。

解读：在 Stage 模型中，工程以模块（Module）为单位组织，每个模块编译生成一个 HAP 包。pages 目录是页面源码的存放位置，而 module.json5 则是该模块的核心配置入口。

五、本节知识点总结

开发环境

DevEco Studio 是华为官方 IDE，需配置 JDK 11、HarmonyOS SDK。

项目创建

选择 Empty Ability 模板，Compatible SDK 决定最低 API 版本。

工程结构

AppScope 存全局配置，entry 模块含 ets 源码、resources 资源和 module.json5。

声明式 UI

描述结果而非过程，状态驱动视图更新。

核心装饰器

@Entry 表示页面入口，@Component 表示自定义组件，@State 表示状态变量。

组件体系

基础组件如 Text、Button、Image；容器组件如 Column、Row、Stack。

属性与事件

通过链式调用配置属性，如 .fontSize()；通过链式调用绑定事件，如 .onClick()。

状态管理

@State 变量变化后，会自动触发使用了该状态的 UI 刷新。

下节预告

第2课将深入讲解 ArkTS 基础语法，包括变量声明、数据类型、函数定义以及条件渲染与循环渲染的使用方法。