鸿蒙生态与 ArkTS 入门：环境搭建与第一个应用

鸿蒙生态与 ArkTS 入门：环境搭建与第一个应用

HarmonyOS（鸿蒙）是华为面向"万物互联"打造的分布式操作系统，而 ArkTS 是鸿蒙应用开发的首选语言。本文带你从零搭建开发环境、理解工程结构，并写出第一个 ArkUI 应用，建立对鸿蒙开发的整体认知。

---

一、为什么是鸿蒙，为什么是 ArkTS

传统移动操作系统围绕"单设备"设计，而鸿蒙的核心主张是分布式软总线------把手机、平板、手表、智慧屏、车机等设备虚拟成一个"超级终端"，应用可以跨设备调用硬件能力、迁移状态、协同计算。对开发者而言，这意味着一次开发，多端部署（一多）。

ArkTS 是鸿蒙上的应用开发语言，它在 TypeScript 的基础上做了强化与约束：

• 保持 TypeScript 的类型系统，但开启更严格的类型检查（禁用 any、强制类型声明）。
• 强化声明式 UI 能力，用结构化的 UI 描述替代命令式 DOM 操作。
• 通过状态变量（@State 等装饰器）驱动 UI 自动刷新，无需手动操作视图。
• 运行时基于方舟编译器（ArkCompiler）AOT 编译，性能接近原生。

一句话：ArkTS = TypeScript 的严谨子集 + 声明式 UI + 响应式状态管理。

---

二、安装 DevEco Studio

鸿蒙官方 IDE 是 DevEco Studio（基于 IntelliJ 平台），开发 ArkTS 应用必须用它。

安装步骤：

1. 访问华为开发者联盟官网，下载对应操作系统（Windows / macOS）的 DevEco Studio。
2. 安装时勾选 HarmonyOS SDK，并选择 API 版本（建议选当前最新稳定版，如 API 12+）。
3. 首次启动会引导配置 Node.js（建议 18+）、Ohpm（鸿蒙包管理器，类似 npm）。
4. 配置 HarmonyOS SDK Location，确保 SDK、Toolchains、emulator 都勾选安装。

环境校验（macOS 终端）：

# 查看 ohpm 版本，确认包管理器就绪
ohpm -v

# 查看 hdc（鸿蒙设备调试桥）是否可用
hdc version

如果 hdc 命令未找到，需在 DevEco 的 SDK 目录把 toolchains 加入 PATH。

---

三、创建第一个工程

打开 DevEco Studio → New Project → 选择 Empty Ability（ArkTS 模板）→ 配置：

• Project name：HelloHarmony
• Bundle name：com.example.helloharmony（包名，反向域名风格）
• Save location：本地目录
• Compile SDK：选最新 API
• Model：Stage 模型（当前主流，替代老的 FA 模型）

点击 Finish，DevEco 会生成标准 Stage 工程结构。

---

四、理解工程结构

Stage 模型下，关键目录与文件：

HelloHarmony/
├── entry/                      # 主模块（一个 App 可含多个 module）
│   ├── src/main/
│   │   ├── ets/                # ArkTS 源码（ets = extended TypeScript）
│   │   │   ├── entryability/   # 应用入口 Ability
│   │   │   │   └── EntryAbility.ts
│   │   │   ├── pages/          # 页面（ArkUI）
│   │   │   │   └── Index.ets
│   │   │   └── entrybackup/    # 备份恢复（可选）
│   │   ├── resources/          # 资源（图片、字符串、布局限定符）
│   │   └── module.json5        # 模块配置（Ability、权限、入口）
│   └── build-profile.json5     # 构建配置
├── AppScope/                   # 应用级配置
│   └── app.json5               # 应用名、包名、版本
└── oh-package.json5            # 依赖声明（ohpm 管理）

module.json5 是模块的核心配置，声明入口 Ability 和所需权限：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ts",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      }
    ],
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" }
    ]
  }
}

---

五、入口 Ability：应用的起点

EntryAbility.ts 是应用进程的入口，负责窗口创建与页面加载：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    // 加载主页面 pages/Index
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load page: %{public}s', err.message);
        return;
      }
    });
  }

  onForeground(): void {
    // 应用进入前台
  }

  onDestroy(): void {
    // 资源释放
  }
}

UIAbility 管理一个窗口舞台（WindowStage），loadContent 指定首个页面路由。

---

六、第一个 ArkUI 页面

打开 pages/Index.ets，这是声明式 UI 的核心。一个最小页面：

// 装饰器 @Entry 表示这是页面入口组件
// @Component 表示这是一个自定义组件
@Entry
@Component
struct Index {
  // @State 声明响应式状态：变化时 UI 自动刷新
  @State message: string = 'Hello HarmonyOS';

  build() {
    // 声明式描述 UI 结构
    Column() {
      Text(this.message)
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
        .fontColor('#0A59F7')

      Button('点我切换')
        .margin({ top: 20 })
        .onClick(() => {
          // 修改状态变量，UI 自动更新
          this.message = '你好，鸿蒙！';
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

关键点：

• @Entry + @Component + struct + build() 是页面的标准骨架。
• Column() 是线性纵向布局容器，类似 Flex 纵向排列。
• Text / Button 是内置组件，链式调用 .fontSize() 等设置属性。
• @State message 改变时，引用它的 Text 自动重渲染------声明式 + 响应式。

---

七、运行到模拟器

1. 在 DevEco 顶部工具栏点击 Device Manager，下载并启动一个 Phone 模拟器（如 Huawei_P60）。
2. 选择该模拟器作为运行目标，点击 ▶ Run。
3. 首次运行会自动安装 HAP（Harmony Ability Package）到模拟器并启动。

你也可以用真机：手机开启"开发者模式 → USB 调试"，用 hdc 连接后选择设备运行。

---

八、热重载与调试

DevEco 支持 Hot Reload（热重载）：修改 ArkTS 代码后保存，UI 即时刷新，无需重新安装。对 UI 调试极高效。

断点调试：在 .ets 行号左侧单击打点，Run 时选择 Debug，变量、调用栈一目了然。hilog 是鸿蒙日志工具：

import { hilog } from '@kit.PerformanceAnalysisKit';

hilog.info(0x0000, 'myTag', '用户点击，当前计数=%{public}d', this.count);

%{public} 表示日志内容可公开显示（隐私字段用 %{private} 避免泄露）。

---

九、资源与国际化

resources/ 目录按限定符组织资源，支持多语言、多分辨率：

resources/
├── base/
│   ├── element/string.json      # 默认字符串
│   ├── media/                    # 图片
│   └── color/color.json
└── zh_CN/element/string.json    # 中文覆盖

引用方式：

Text($r('app.string.welcome'))   // 引用字符串资源
Image($r('app.media.icon'))      // 引用图片

$r('app.string.xxx') 由框架按当前语言环境自动选择，天然支持国际化。

---

十、常见新手问题与排查

问题	原因	解决
模拟器启动黑屏	未开启硬件加速	BIOS 开启 VT，或改用真机
@State 不刷新	改了对象内部属性但引用未变	用 @Observed + 替换整个对象
真机无法识别	hdc 未授权	手机弹窗点"允许"，重连
包体积过大	未开启混淆/压缩	build-profile 开启 release 优化

---

十一、下一步学什么

到这里，你已经跑通了第一个鸿蒙应用。下一步建议顺序：

1. 吃透 ArkTS 语言基础（类型、装饰器、声明式语法）。
2. 掌握 ArkUI 组件与布局（Column/Row/Flex/Grid）。
3. 理解 状态管理（@State/@Prop/@Link/@Provide）。
4. 深入 路由、网络、存储、动画、并发、分布式。

---

十二、总结

鸿蒙开发的第一步，是建立"声明式 + 响应式 + 分布式"的心智模型。本文带你装好 DevEco、看清工程结构、写出并运行了第一个 ArkUI 页面。你会发现：ArkTS 的 UI 写法比传统命令式直观得多------你描述的是"界面应该长什么样"，而不是"一步步怎么改界面"。这正是鸿蒙开发高效的根本原因。下一讲，我们深入 ArkTS 语言本身。