环境搭建与 ArkTS 基础

什么是 HarmonyOS NEXT

HarmonyOS NEXT（鸿蒙 NEXT）是华为于 2024 年推出的全新版本鸿蒙操作系统，它与以往最大的区别在于：彻底移除了 Android 兼容层，成为完全自主、纯鸿蒙内核的操作系统。这意味着在 HarmonyOS NEXT 上运行的应用，必须是原生鸿蒙应用，不再兼容 Android APK。

这一变化对开发者来说是重大机遇：整个华为、荣耀手机生态需要重建原生应用，市场需求巨大。与此同时，HarmonyOS NEXT 提供了统一的开发框架 ArkUI，以及专属语言 ArkTS，让开发体验比以往任何版本都更加一致和高效。

HarmonyOS NEXT 的核心设计哲学是万物互联——手机、平板、手表、电视、汽车……所有华为生态设备共享同一套 UI 框架和分布式能力。开发者一次开发，可以覆盖整个华为超级终端生态。

核心名词解释

HarmonyOS NEXT vs 前代 vs 竞品

理解 HarmonyOS NEXT 在整个移动生态中的定位，有助于做出合理的技术选型：

安装 DevEco Studio

DevEco Studio 是开发 HarmonyOS NEXT 应用的唯一官方 IDE。以下是安装步骤：

1. 访问华为开发者官网 developer.harmonyos.com，下载最新版 DevEco Studio（Windows 或 macOS 版本）
2. 安装时选择"HarmonyOS NEXT"SDK，会自动下载 ArkTS 工具链、模拟器镜像
3. 首次启动配置 SDK 路径，建议 SDK 安装在非系统盘路径（Windows）或用户目录（macOS）
4. 在 SDK Manager 中确保安装：HarmonyOS SDK（API 12+）、工具包（Command Line Tools）
5. 可选：安装模拟器镜像（约 4GB），或连接真机通过 USB 调试

创建第一个项目

1. 打开 DevEco Studio，选择 "Create Project"
2. 选择模板：Application → Empty Ability（Stage 模型，ArkTS）
3. 填写项目名、包名（格式：com.example.myapp），选择 API 版本（选 API 12 或最新）
4. 点击 Finish，等待 Gradle 同步和依赖下载（首次约 5~10 分钟）
5. 连接设备或启动模拟器，点击运行按钮（▶）

项目结构详解

# HarmonyOS NEXT Stage 模型项目结构
MyApp/
├── AppScope/                    # 应用级配置
│   ├── app.json5                # 应用全局配置（包名、版本、图标）
│   └── resources/              # 应用级资源（启动图标等）
│
├── entry/                       # 入口 HAP 模块
│   ├── src/main/
│   │   ├── ets/                 # ArkTS 源码目录
│   │   │   ├── entryability/
│   │   │   │   └── EntryAbility.ets   # UIAbility 入口
│   │   │   └── pages/
│   │   │       └── Index.ets    # 首页组件
│   │   ├── resources/           # 模块资源（字符串、颜色、图片）
│   │   │   ├── base/
│   │   │   │   ├── element/     # string.json、color.json
│   │   │   │   └── media/       # 图片资源
│   │   │   └── rawfile/         # 原始文件（不压缩）
│   │   └── module.json5         # 模块配置（路由、权限声明）
│   └── build-profile.json5      # 构建配置
│
├── hvigor/                      # 构建工具（类似 Gradle）
├── build-profile.json5          # 项目构建配置
└── hvigorfile.ts                # 构建脚本

ArkTS 语言基础

ArkTS 是鸿蒙生态的核心语言。理解它与 TypeScript 的关系非常重要：ArkTS 是 TypeScript 的超集，但同时也是受限子集。"超集"是指它新增了声明式 UI 语法；"受限子集"是指它禁止了一些 TypeScript 的动态特性，以保证性能和安全。

基本类型与变量

// ArkTS 完全支持 TypeScript 的类型系统
let name: string = '鸿蒙开发者'
let age: number = 25
let isActive: boolean = true
const PI: number = 3.14159

// 数组类型
let scores: number[] = [90, 85, 92]
let names: Array<string> = ['Alice', 'Bob']

// 联合类型
let id: string | number = 'abc123'
id = 42  // 合法

// 可选链与空值合并
let user: { name?: string } = {}
const displayName = user.name ?? '匿名用户'

// ArkTS 限制：禁止 any 类型（推荐 unknown 代替）
// let x: any = ...  ← 在严格模式下不推荐
let data: unknown = fetchData()
if (typeof data === 'string') {
  console.log(data.toUpperCase())  // 类型缩小后安全访问
}

接口与类

// 接口定义数据结构
interface User {
  id: number
  name: string
  email?: string    // 可选属性
  readonly role: string  // 只读属性
}

// 类实现接口
class Developer implements User {
  id: number
  name: string
  readonly role: string = 'developer'
  private skills: string[] = []

  constructor(id: number, name: string) {
    this.id = id
    this.name = name
  }

  addSkill(skill: string): void {
    this.skills.push(skill)
  }

  getSkills(): string[] {
    return [...this.skills]  // 返回副本，避免外部修改
  }
}

// 泛型函数
function createList<T>(items: T[]): T[] {
  return [...items]
}

const devList = createList<Developer>([
  new Developer(1, '张三'),
  new Developer(2, '李四')
])

异步编程

HarmonyOS 大量 API 是异步的，ArkTS 提供了完整的 Promise 和 async/await 支持：

// async/await 是处理异步的推荐方式
async function loadUserData(userId: number): Promise<User> {
  try {
    // 模拟网络请求
    const response = await httpRequest(`/api/users/${userId}`)
    const data: User = JSON.parse(response.result as string)
    return data
  } catch (err) {
    console.error('加载失败:', err)
    throw err
  }
}

// Promise 链式调用（等价于上面的 async/await）
loadUserData(1)
  .then(user => console.log(user.name))
  .catch(err => console.error(err))

// 并行请求
const [user, posts] = await Promise.all([
  loadUserData(1),
  loadPosts(1)
])

ArkTS 独有限制（与 TypeScript 的区别）

第一个完整 ArkTS 组件

下面这个例子展示了 ArkTS + ArkUI 声明式 UI 的完整写法，包含状态管理和事件处理：

// Index.ets — 第一个 HarmonyOS NEXT 应用

// @Entry 标记这是页面的入口组件（一个页面只能有一个）
@Entry
// @Component 标记这是一个 ArkUI 组件
@Component
struct Index {
  // @State 声明响应式状态变量
  // 当 count 变化时，引用它的 UI 自动重绘
  @State count: number = 0
  @State greeting: string = '你好，鸿蒙！'

  // build() 方法描述 UI 结构，由框架自动调用
  build() {
    // Column 是垂直布局容器，子组件从上到下排列
    Column({ space: 20 }) {

      // Text 组件显示文字，通过链式调用设置属性
      Text(this.greeting)
        .fontSize(28)
        .fontWeight(FontWeight.Bold)
        .fontColor('#CF0A2C')

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

      // Button 组件，onClick 事件处理函数
      Button('点击我 +1')
        .width(200)
        .height(48)
        .backgroundColor('#CF0A2C')
        .borderRadius(10)
        .onClick(() => {
          this.count++
          // 修改 @State 变量，框架自动触发 UI 更新
        })

      // if 条件渲染
      if (this.count >= 5) {
        Text('🎉 点击达到 5 次！')
          .fontSize(16)
          .fontColor('#56d364')
      }

    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#0d1117')
  }
}

EntryAbility 生命周期

在 Stage 模型中，UIAbility 是应用的核心容器。理解其生命周期对于处理应用状态切换（如从后台恢复）至关重要：

// EntryAbility.ets
import UIAbility from '@ohos.app.ability.UIAbility'
import type { AbilityConstant, Want, window } from '@kit.AbilityKit'

export default class EntryAbility extends UIAbility {

  // 应用首次创建时调用（冷启动）
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    console.log('Ability onCreate')
    // 适合：初始化全局数据、配置日志系统
  }

  // 窗口创建后调用，在此加载页面
  async onWindowStageCreate(windowStage: window.WindowStage) {
    // loadContentByName 加载路由命名页面
    await windowStage.loadContent('pages/Index')
    console.log('页面加载完成')
  }

  // 应用切到前台（从后台恢复或首次可见）
  onForeground() {
    console.log('Ability onForeground')
    // 适合：恢复定时器、重新订阅数据
  }

  // 应用切到后台（用户按 Home 键或切换应用）
  onBackground() {
    console.log('Ability onBackground')
    // 适合：暂停定时器、保存临时状态
  }

  // 应用销毁时调用
  onDestroy() {
    console.log('Ability onDestroy')
    // 适合：释放资源、取消订阅
  }
}

module.json5 配置文件

每个 HAP 模块的核心配置文件，类似 Android 的 AndroidManifest.xml：

{
  "module": {
    "name": "entry",
    "type": "entry",           // 入口模块
    "description": "应用主模块",
    "mainElement": "EntryAbility",

    "deviceTypes": [           // 支持的设备类型
      "phone",
      "tablet"
    ],

    "abilities": [{            // Ability 声明
      "name": "EntryAbility",
      "srcEntry": "./ets/entryability/EntryAbility.ets",
      "description": "主界面",
      "icon": "$media:icon",
      "label": "$string:EntryAbility_label",
      "startWindowIcon": "$media:startIcon",
      "startWindowBackground": "$color:start_window_background",
      "exported": true,
      "skills": [{             // 响应的 Intent
        "entities": ["entity.system.home"],
        "actions": ["action.system.home"]
      }]
    }],

    "requestPermissions": [   // 权限声明
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}