HarmonyOS 入门 · 第1周

掌握基础语法与
开发环境搭建

从 TypeScript 到 ArkTS，从零搭建 DevEco Studio，写出第一个 Hello World。

📅 预计耗时：5–7 天 🎯 目标：在真机/模拟器运行首个程序

1 TypeScript 基础复习

ArkTS 脱胎于 TypeScript，扎实的 TS 基础是高效学习的前提

📦 类型系统

TypeScript 的核心价值在于静态类型检查——在编译阶段发现类型错误，而非运行时。

                // 基础类型
                let name: string = "HarmonyOS";
                let version: number = 5;
                let isStable: boolean = true;

                // 联合类型 & 可选
                let id: string | number;
                function greet(name?: string) {
                    return `Hello, ${name ?? 'World'}`;
                }
            

💡 重点掌握：类型注解、联合类型、类型推断、null/undefined 处理

🔌 接口（Interface）

接口是 TypeScript 中定义对象结构的主要方式。ArkTS 中同样大量使用。

                interface AppConfig {
                    name: string;
                    version: string;
                    permissions?: string[];  // 可选属性
                    readonly appId: number;            // 只读
                }

                const config: AppConfig = {
                    name: "MyApp",
                    version: "1.0.0",
                    appId: 10001
                };
            

💡 扩展：extends 实现接口继承，Pick/Omit 工具类型

🧩 泛型（Generics）

泛型让你编写可复用的类型安全组件。在 ArkUI 的自定义组件中也常用到。

                // 泛型函数
                function first<T>(arr: T[]): T | undefined {
                    return arr[0];
                }

                // 泛型接口
                interface ListResponse<T> {
                    code: number;
                    data: T[];
                    total: number;
                }

                // 使用
                const res: ListResponse<string> = await fetchData();
            

💡 ArkTS 注意：ArkTS 对泛型约束更严格，不支持泛型类（class）——使用接口 + 函数组合替代。

2 ArkTS 与 TypeScript 差异

ArkTS 是 TS 的严格子集——了解"少了什么"和"多了什么"

⚖️ 主要差异对比

TypeScript 中可用

❌ any / unknown
❌ 装饰器（原生TS语法）
❌ 私有构造函数
❌ 类泛型
❌ JSX
❌ 动态属性操作

ArkTS 中可用

✅ 严格类型（interface / type）
✅ @Component @State 等装饰器
✅ 声明式 UI 范式
✅ 函数式 + 面向对象混合
✅ 异步（async/await）
✅ 模块化（import/export）

✨ ArkTS 专属装饰器

装饰器是 ArkTS 声明式 UI 的核心机制，通过 @ 语法为组件附加元数据和行为。

                @Component
                struct MyComponent {
                    @State count: number = 0;

                    build() {
                        Column() {
                            Text(`点击了 ${this.count} 次`)
                                .fontSize(16)
                            Button("点击")
                                .onClick(() => {
                                    this.count++;
                                })
                        }
                        .width('100%')
                        .padding(20)
                    }
                }
            

🔑 关键装饰器速览：
@Component — 标记自定义组件
@State — 组件内可变状态，变化时触发 UI 重绘
@Prop — 从父组件接收的单向数据
@Link — 与父组件双向同步
@Builder — 定义可复用的 UI 片段
@Styles / @Extend — 样式复用

🚫 ArkTS 限制（必须知道的坑）

不允许使用 any 和 unknown——必须显式声明类型
不支持装饰器语法糖——ArkTS 的 @Decorator 是框架内置的，不是 TS 实验性装饰器
不支持 Object.keys() / for..in——遍历对象需用 Object.entries() 或 forEach
不支持 Symbol / BigInt——这些 ECMAScript 特性被裁剪了
不支持泛型类——使用泛型函数或接口替代
JSON 解析需显式类型断言——JSON.parse 返回类型为 object

⚠️ 最常见错误：从 TS 项目直接复制代码到 ArkTS，遇到 any 或 for..in 报错。记住——ArkTS 不是"TS 子集"，而是"一个更严格的超集子集"。

3 开发环境与 Hello World

从 0 到 1：在你的 Mac 上跑起第一个鸿蒙应用

🖥️ 环境搭建流程

步骤 1 · 10分钟

注册华为开发者账号

访问 developer.huawei.com，注册并完成实名认证。实名认证通常需要 1-2 天审核，建议提前完成。

步骤 2 · 20分钟

下载并安装 DevEco Studio

官网下载 macOS 安装包，拖入 Applications 目录完成安装。首次启动会自动引导下载 HarmonyOS SDK，建议选择 API 14+ 版本。

步骤 3 · 10分钟

配置模拟器

Apple Silicon Mac 用户：推荐使用 Remote Emulator（华为云端模拟器），无需本地镜像，免费额度充足。
Intel Mac 用户：可安装 Local Emulator（x86 镜像）。

步骤 4 · 15分钟

创建第一个项目

File → New → Create Project → 选择 "Empty Ability" 模板 → 等待 Gradle 同步 → 点击 Run

📱 Hello World 工程结构

创建一个 Empty Ability 后，项目结构如下：

├── entry/                          // 主模块
│   ├── src/main/
│   │   ├── ets/
│   │   │   ├── entryability/       // Ability 生命周期
│   │   │   │   └── EntryAbility.ets
│   │   │   └── pages/
│   │   │       └── Index.ets       // 页面入口 ← 主要编辑文件
│   │   ├── resources/             // 资源文件（图片、字符串、颜色）
│   │   └── module.json5           // 模块配置声明
│   └── build-profile.json5        // 构建配置
├── oh_modules/                    // 依赖库
├── build-profile.json5            // 项目级构建配置
└── hvigor/                        // 构建工具配置

🚀 Hello World 代码

打开 Index.ets，默认的 Hello World 如下：

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

                    build() {
                        Column() {
                            Text(this.message)
                                .fontSize(28)
                                .fontWeight(FontWeight.Bold)
                                .fontColor('#6c63ff')
                        }
                        .width('100%')
                        .height('100%')
                        .justifyContent(FlexAlign.Center)
                    }
                }
            

🧪 动手试试：将 message 改为你的名字，添加一个 Button 组件点击后改变文字。这会让你第一次感受到 ArkTS 声明式 UI 的"状态驱动"工作流。

🔍 常见环境问题排查

Gradle 同步失败 → 检查网络代理，建议关闭 VPN 或配置 Gradle 国内镜像
模拟器连接超时 → Remote Emulator 需登录华为账号，检查网络是否屏蔽 huawei.com
代码报红但不影响编译 → DevEco Studio Lint 规则比编译更严格，检查是否使用了 any 类型
真机调试无法识别设备 → 开启开发者模式，授权调试，USB 连接使用 MTP 模式

✓ 第1周通关清单

完成以下事项，即可进入第2周的学习

掌握 TypeScript 类型系统基础类型注解、接口、泛型、联合类型
理解 ArkTS 与 TypeScript 的核心差异装饰器语法、限制规则、类型严格性
安装 DevEco Studio 并完成 SDK 配置注册开发者账号 → 安装 IDE → 下载 SDK
成功运行 Hello World 到模拟器或真机创建 Empty Ability 项目 → Run → 看到界面
动手扩展：给 Hello World 加一个按钮体验 @State 状态驱动的 UI 更新

📖 下一步：返回完整入门指南，查看第 2 周的学习路线。