HarmonyOS 探秘手记：我在 “鸿蒙星球” 的第一天

一、ArkTS

​ ArkTS 是华为鸿蒙操作系统（HarmonyOS）推出的声明式编程语言，专为高效构建跨设备应用而设计。它基于 TypeScript 语法，提供简洁、直观的语法糖和工具链，帮助开发者快速实现高性能、响应式的应用界面。

1、语言定位与设计目标

1. 声明式编程范式 ArkTS 采用声明式语法（如 @Component、@State 装饰器），通过描述 UI “是什么” 而非 “如何做” 来构建界面。相比传统命令式编程，声明式代码更简洁、易读，且更符合现代前端开发趋势。
2. TypeScript 超集 ArkTS 完全兼容 TypeScript，继承了其静态类型检查、接口、枚举等特性，同时扩展了鸿蒙特有的装饰器和 API，降低了前端开发者的学习成本。
3. 跨设备统一开发 设计初衷是支持一次开发，多端部署，通过同一套代码适配手机、平板、手表、车机等不同设备形态，减少重复开发。

2、核心特性

1. 组件化与装饰器

• @Component：声明 UI 组件，支持嵌套组合，实现界面复用。
• @Entry：标记应用入口组件。
• @State：实现响应式状态管理，自动追踪数据变化并更新 UI。

2. 响应式系统

• 自动状态绑定：通过 @State 装饰器声明响应式变量，当变量值变化时，关联的 UI 元素自动刷新。

3. 布局系统

• 声明式布局：提供 DirectionalLayout（线性布局）、Stack（层叠布局）、RelativeContainer（相对布局）等容器组件，支持灵活排列子元素。

4. 事件处理

• 直观的事件绑定：通过 .onClick()、.onChange() 等方法绑定事件回调，支持触摸、键盘、手势等多种交互。

5. 生命周期管理

• 自动内存管理：基于垃圾回收机制，减少手动内存管理的风险。

6. 资源管理

• 统一资源引用：通过 $r() 函数引用应用资源（如图像、字符串、布局文件），支持多语言和设备适配。

3、开发工具与生态

1. DevEco Studio 华为官方 IDE，集成代码编辑、调试、预览等功能，支持 ArkTS 语法高亮、智能提示和实时预览。
2. ArkUI 框架 基于 ArkTS 的 UI 框架，提供丰富的组件库和布局系统，支持声明式构建跨设备界面。
3. 鸿蒙 SDK 提供系统 API 访问能力（如文件操作、网络请求、传感器数据等），支持与原生功能深度集成。
4. 跨平台支持 通过鸿蒙的 分布式技术，ArkTS 应用可无缝扩展到多设备，实现设备间协同（如手机控制智能家电）。

4、学习资源

• 官方文档：HarmonyOS 开发者文档
• 教程与示例：华为开发者联盟提供的官方教程和开源示例项目。
• 社区支持：HarmonyOS 开发者论坛、Stack Overflow 等社区提供技术交流和问题解答。

二、DevEco Studio空项目部分默认目录介绍

1、基础的工程结构

（1）pages

​ 在 DevEco Studio 的鸿蒙项目中，pages 目录是存放与应用页面相关代码文件的地方。

• 存放位置：对于使用 ArkTS 语言开发的项目，通常在 entry/src/main/ets 目录下。
• 文件结构：pages 文件夹下可以包含一个或多个页面，每个页面都有对应的文件夹。
• 作用：用于管理应用的各个页面，每个页面单独进行文件管理，通过路由 API 实现页面的调度管理，以实现应用内功能的解耦。例如，在开发一个具有多个界面的鸿蒙应用时，不同界面的相关代码就会分别存放在 pages 目录下对应的页面文件夹中，方便开发者对各个页面的逻辑、样式和布局进行独立开发和维护。

（2）resources

​ 在 DevEco Studio 的鸿蒙项目中，resources 目录是存放应用资源文件的核心位置，用于管理应用的静态资源（如图像、字体、字符串、颜色、布局文件等）。

1. base 目录（基础资源）

​ 存放应用的默认资源，不区分设备、语言、屏幕密度等条件，是资源加载的**“兜底” 目录**。

2. 多语言目录（如 en-US、zh-CN）

​ 用于适配不同语言环境，目录结构与 base/string 一致，但存储对应语言的字符串资源。

3. screenable 目录（屏幕密度适配）

​ 根据屏幕像素密度（DPI）存放不同版本的图片资源，目录命名规则为 dpi-xxx（如 dpi-160、dpi-240、dpi-320）。 作用：系统会根据设备屏幕密度自动加载对应目录的图片，确保显示清晰。

4. device 目录（设备类型适配）

​ 根据设备类型（如手机、平板、车机）存放特定布局或资源，目录命名规则为 device-xxx（如 device-phone、device-tablet）。

三、DevEco Studio空项目默认代码index.ets介绍

​ 鸿蒙应用开发中 ArkTS 语言编写的 index.ets 文件，采用 Stage 模型（鸿蒙 3.0+ 推荐架构）：

1、组件结构与装饰器

（1）内容

@Entry
@Component
struct Index {// 组件内容
}

• @Entry：标记该组件为应用的 入口点，每个应用只能有一个 @Entry 组件。
• @Component：声明这是一个 UI 组件，可被其他组件引用或作为页面展示。
• struct Index：定义组件名称为 Index，采用 结构体（struct）语法，符合 ArkTS 的面向对象设计。

（2）装饰器

​ 在 ArkTS 语言中，@ 符号开头的是装饰器（Decorator），用于为类、方法或属性添加额外的元数据或行为。这些装饰器是 ArkTS 框架的核心特性，用于实现组件化、状态管理和生命周期控制。

1. @Component：声明一个类为 UI 组件，使其能够被渲染为界面元素。

2. @Entry：标记组件为应用的 入口点，每个应用只能有一个 @Entry 组件。

3. @State：声明一个 响应式状态变量。当变量值变化时，依赖它的 UI 会自动刷新。

4. @Link：创建一个 双向数据绑定，子组件可以修改父组件的状态。

5. @Prop：从父组件 单向接收数据，子组件不能直接修改。

6. @Builder：定义一个 可复用的 UI 片段，提高代码复用性。

（3）装饰器的工作原理

• 元数据注入：装饰器在编译时为类或属性添加额外信息，框架通过这些信息实现特定功能（如状态监听、生命周期管理）。
• 响应式系统：@State、@Link 等装饰器使变量成为 可观察对象，当值变化时，框架会自动更新关联的 UI。

2、状态管理（@State）

@State message: string = 'Hello World';

• @State：声明 message 为 响应式状态变量。当 message 变化时，依赖它的 UI 元素会自动刷新。
• 初始值：默认显示 “Hello World”。

3、UI 构建（build 方法）

build() {// UI 布局
}

• build()：组件的核心方法，用于 定义 UI 结构。当组件被渲染时，此方法会被调用。

4、容器组件（RelativeContainer）

RelativeContainer() {// 子组件
}
.height('100%')
.width('100%')

• RelativeContainer：鸿蒙的 相对布局容器，支持子组件通过相对位置（如居中、对齐）排列。
• 宽高设置：height('100%') 和 width('100%') 使容器占满整个屏幕。

5、文本组件（Text）

Text(this.message).id('HelloWorld').fontSize($r('app.float.page_text_font_size')).fontWeight(FontWeight.Bold)

• 内容绑定：Text(this.message) 将文本内容绑定到状态变量 message。
• ID 设置：.id('HelloWorld') 为组件设置唯一标识（用于自动化测试或样式引用）。
• 字体设置：
  • fontSize($r('app.float.page_text_font_size'))：通过 $r 引用资源文件中的字体大小（如 resources/base/element/dimens.json 中定义的值）。
  • fontWeight(FontWeight.Bold)：设置字体为粗体。

6、布局对齐（alignRules）

.alignRules({center: { anchor: '__container__', align: VerticalAlign.Center },middle: { anchor: '__container__', align: HorizontalAlign.Center }
})

• 垂直居中：center 规则使文本在容器中 垂直居中。
• 水平居中：middle 规则使文本在容器中 水平居中。
• container：表示当前组件的父容器（即 RelativeContainer）。

7、点击事件（onClick）

.onClick(() => {this.message = 'Welcome';
})

• 事件绑定：.onClick() 监听文本的点击事件。
• 状态更新：点击后，message 被更新为 “Welcome”，触发 UI 重新渲染。

8、资源引用说明

$r('app.float.page_text_font_size')

• $r：资源引用函数，用于获取 resources 目录下的资源。
• 引用路径：app.float.page_text_font_size 对应 resources/base/element/dimens.json 中的字体大小定义，例如：

{"float": [{ "name": "page_text_font_size", "value": "30fp" }]
}

四、ArkUI

1、ArkUI（方舟开发框架）

（1）核心定位与背景

​ ArkUI 是华为为 HarmonyOS（鸿蒙系统） 打造的 跨设备应用开发框架，旨在通过统一的开发语言和工具链，帮助开发者高效构建 多端（手机、平板、智能穿戴、智慧屏、车机等）一致、性能优越 的应用界面，实现 “一次开发，多端部署” 的跨设备开发目标。

（2）开发工具与生态支持

1. DevEco Studio
   • 官方集成开发环境（IDE），提供 代码编辑、实时预览、多端调试、性能分析 等全流程工具，大幅提升开发效率。
   • 内置 模拟器，可快速预览应用在不同设备（如手机、平板、手表）上的显示效果。
2. 生态与社区
   • 华为开发者联盟提供 文档、教程、示例代码 及技术支持，社区活跃，开发者可通过论坛、直播等获取资源。

2、组件基础

​ 在 HarmonyOS 中，ArkUI 是官方推荐的 UI 框架，它提供了声明式语法（如 ArkTS/TS）和丰富的组件库，让开发者可以高效构建美观、流畅的界面。

（1）组件分类

​ ArkUI 组件按功能可分为以下几类。

1. 容器组件（Layout Containers）：用于组织和排列子组件，控制布局结构。

• DirectionalLayout：线性布局（水平 / 垂直排列）：线性排列子组件，支持水平 / 垂直方向。

• RelativeContainer：相对布局（通过相对位置定位）：通过相对位置定位子组件（如居中、对齐父容器边缘）。

2. 基础组件（Basic Components）：构成界面的基本元素。

• Text：文本显示。

常用属性：

• text：文本内容
• fontSize：字体大小
• fontColor：字体颜色
• fontWeight：字体粗细
• textAlign：文本对齐方式

• Button：按钮（可点击）。

常用属性：

• type：按钮类型（普通、胶囊、圆角等）
• onClick：点击事件
• backgroundColor：背景色
• enabled：是否启用

3. 导航组件（Navigation）：用于页面导航和层级管理。

4. 数据展示组件（Data Display）：用于展示列表、网格等数据。

5. 交互组件（Interaction）：提供用户交互功。

3、界面布局思路

​ “先界面，后内容” 指的是在进行界面开发时，首先搭建好整体的界面框架和布局结构，确定好界面的分区、组件的排列方式、视觉层次等，就像建造房屋时先搭建好框架；然后再往这个框架中填充具体的内容，如文字、图片、数据等，如同在房屋框架内装修布置。这样的开发流程可以避免内容和布局混杂导致的逻辑混乱，使开发过程更具条理性。

五、属性

1、通用属性

（1）width

width(value: Length)：设置组件自身的宽度，缺省时使用元素自身内容需要的宽度。若子组件的宽大于父组件的宽，则会画出父组件的范围。

参数名	类型	必填	说明
value	Length	是	要设置的组件宽度。单位：vp

（2）height

height(value: Length)：设置组件自身的高度，缺省时使用元素自身内容需要的高度。若子组件的高大于父组件的高，则会画出父组件的范围。

参数名	类型	必填	说明
value	Length	是	要设置的组件高度。单位：vp

（3）backgroundColor

backgroundColor(value: ResourceColor): T：设置组件背景色。

参数名	类型	必填	说明
value	ResourceColor	是	设置组件的背景色。

（4）padding

padding(value: Padding | Length | LocalizedPadding)：设置组件的内边距属性（组件内容与组件边界之间的距离）。

参数名	类型	必填	说明
value	Padding | Length | LocalizedPadding12+	是	设置组件的内边距。参数为Length类型时，四个方向内边距同时生效。默认值：0单位：vppadding设置百分比时，上下左右内边距均以父容器的width作为基础值。

（5）margin

margin(value: Margin | Length | LocalizedMargin)：设置组件的外边距属性（组件与其他组件之间的距离）。

参数名	类型	必填	说明
value	Margin | Length | LocalizedMargin12+	是	设置组件的外边距。参数为Length类型时，四个方向外边距同时生效。默认值：0单位：vpmargin设置百分比时，上下左右外边距均以父容器的width作为基础值。在Row、Column、Flex交叉轴上布局时，子组件交叉轴的大小与margin的和为整体。例如Column容器宽100，其中子组件宽50，margin left为10，right为20，子组件水平方向偏移10。

（6）border

border(value: BorderOptions)：设置边框样式。

参数名	类型	必填	说明
value	BorderOptions	是	统一边框样式设置接口。**说明：**边框宽度默认值为0，即不显示边框。从API version 9开始，父节点的border显示在子节点内容之上。

2、文本属性

（1）fontSize

fontSize(value: number | string | Resource)：设置字体大小。

参数名	类型	必填	说明
value	Resource | number | string	是	字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、“10fp”，不支持设置百分比字符串。

（2）fontColor

fontColor(value: ResourceColor)：设置字体颜色。

参数名	类型	必填	说明
value	ResourceColor	是	字体颜色。

（3）fontWeight

fontWeight(value: number | FontWeight | string)：设置文本的字体粗细，设置过大可能会在不同字体下有截断。

参数名	类型	必填	说明
value	FontWeight | number | string	是	文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、“bolder”、“lighter”、“regular”、“medium”，分别对应FontWeight中相应的枚举值。默认值：FontWeight.Normal

六、渲染

1、条件渲染

let num: number = 1@Entry
@Component// 组件
struct Index {build() { // 构建Column() {if (num === 1) {Text('text 1')} else if (num === 2) {Text('text 2')} else {Text('text 3')}}.padding(20)}
}

2、循环渲染

let names: string[] = ['a', 'b', 'c']@Entry
@Component// 组件
struct Index {build() { // 构建Column() {ForEach(names, (item: string, index: number) => {Text(item + ' ' + index)})}.padding(20)}
}

3、状态管理和事件

（1）onClick

onClick(event: (event: ClickEvent) => void): T：点击动作触发该回调。

参数：

参数名	类型	必填	说明
event	ClickEvent	是	获得ClickEvent对象。

返回值：

类型	说明
T	返回当前组件。