K1 OH5.0 应用开发说明
修订记录
修订版本 | 修订日期 | 修订说明 |
001 | 2025-06-10 | 初始版本 |
1. OpenHarmony 应用开发概述
1.1. ArkTS
ArkTS 是鸿蒙(HarmonyOS/OpenHarmony)生态的官方主力应用开发语言,基于 TypeScript(TS)扩展而来,是 TS 的超集扩展,继承 TypeScript 语法风格,强化静态类型检查(编译时检测错误,提升代码健壮性),兼容 JS/TS 生态,支持高效互操作,降低迁移门槛。
1.1.1. 核心技术特性
-
声明式 UI 开发范式
- 通过装饰器(如
@Entry
、@Component
)定义组件,以简洁的声明式语法构建界面逻辑 - 提供状态管理(如
@State
),驱动数据变化自动更新 UI
- 通过装饰器(如
-
分布式与并发增强
- 优化并发编程 API,支持多线程任务调度(如 Taskpool 机制),提升跨设备协同性能
- 为“一次开发,多端部署”提供底层支持,适配手机、平板、车机等全场景设备
-
性能与稳定性优化
- 静态类型约束减少运行时类型检查,提高执行效率
- 强制属性显式初始化(如类成员变量),避免未定义错误导致的运行时崩溃
1.2. ArkUI
ArkUI(方舟 UI 框架)是华为为 HarmonyOS/OpenHarmony 生态系统构建的声明式 UI 开发框架,专注于实现高效、高性能的跨设备应用界面开发。基于 ArkTS 语言扩展(TypeScript 超集),通过组件化、状态驱动等机制简化 UI 构建逻辑,提供极简的 UI 语法(如装饰器 @Component
),开发者通过声明式描述界面结构而非命令式操作。
1.2.1. 核心技术特性
-
高性能渲染架 构
- 优化 UI 更新机制:将 Diff 算法从树形结构对比升级为单节点函数式更新,大幅提升渲染效率
- 统一渲染引擎保障流畅动效,减少主线程卡顿
-
逻辑与 UI 解耦
- 通过数据双向绑定简化状态管理,跨端开发代码量减少 40% 以上
- 支持状态管理(如
@State
、@Link
),实现数据变化自动驱动 UI 刷新
-
多形态组件库
- 提供丰富内置组件(文本、按钮、列表等)及布局能力,覆盖基础界面到复杂交互场景
- 支持自定义组件开发,满足业务定制化需求
1.3. Ark 运行时(方舟运行时)
Ark 运行时(又称方舟运行时)是 HarmonyOS/OpenHarmony 生态中支撑 ArkTS/JS/TS 语言执行的核心引擎,负责字节码运行、内存管理及跨语言互调等关键能力。
1.3.1. 核心架构组成
-
核心子系统(Core Subsystem)
- 提供基础运行库,支撑字节码文件解析(File 组件)、调试工具链(Tooling 组件)及系统调用适配(Base 库)
-
执行子系统(Execution Subsystem)
- 包含字节码解释器、内联缓存优化机制,实现高效执行方舟字节码(.abc 文件)
-
编译器子系统(Compiler Subsystem)
- 支持 AOT(预编译优化)、JIT(动 态编译实验阶段)及基于 IR 的编译框架,提升代码执行效率
-
运行时子系统(Runtime Subsystem)
- 内存管理:CMS-GC 垃圾回收器实现并发标记与部分内存压缩
- 跨语言接口:通过 Node-API 支持 TS/JS/C++ 等多语言混合开发
1.3.2. 关键技术特性
-
多模式执行引擎
- 同时支持解释执行、AOT 预编译及实验性 JIT 动态编译,平衡启动速度与运行效率
-
高性能内存管理
- 采用并行标记的 CMS-GC 算法,减少暂停时间;支持部分内存压缩,优化内存碎片
-
分布式调试支持
- 内置 Debugger 工具链,实现跨设备协同开发时的实时诊断与性能分析
-
标准库兼容性
- 完整实现 ECMAScript 规范,提供高效容器库(如 Map/Set),保障 JS/TS 生态兼
2. 开发环境搭建(windows)
2.1. DevEco Studio 安装配置
- 下载工具:点我下载 DevEcoStudio5.0.5.310
- 双击下载的
deveco-studio-xxxx.exe
,进入 DevEco Studio 安装向导,默认安装于C:\Program Files
路径下,也可以安装到指定位置(不要出现中文或特殊字符)
,然后单击 NEXT。
2.2. SDK 工具链配置
2.2.1. Public SDK 与 Full SDK
在 OpenHarmony
中,Public SDK
与 Full SDK
是面向不同开发场景的工具包,其核心差异如下:
- API 权限
类型 | 权限说明 |
Public SDK | 提供给普通应用开发者使用,仅包含开放API,不涉及系统敏感权限(如@ohos.app.ability.abilityManager 、蓝牙控制等高权限接口) |
Full SDK | 面向OEM厂商及系统应用开发者,包含所有系统级API(包括需要高权限调用的接口) |
- 获取与部署方式
类型 | 获取途径 |
Public SDK | 在DevEco Studio中下载,开发者无需额外操作 |
Full SDK | 需手动单独下载(从OpenHarmony镜像站点或编译源码获取),并替换Public SDK |
- 适用场景
场景 | 推荐SDK | 原因 |
普通三方应用开发 | Public SDK | 满足基础功能需求,避免权限滥用风险 |
系统级应用(如Launcher) | Full SDK | 需调用高权限接口实现系统管理、硬件控制等能力 |
依赖未开放API的功能 | Full SDK | 如使用mediaLibrary 深度媒体处理或定 制系统服务 |
2.2.2. 下载 Public SDK
DevEco Studio
提供开箱即用的开发体验,将 HarmonyOS SDK
、Node.js
、Hvigor
、OHPM
、模拟器平台等进行合一打包,简化 DevEco Studio
安装配置流程。
HarmonyOS SDK
已嵌入 DevEco Studio
中,无需额外下载配置。但 OpenHarmony
的 SDK 没有集成,如需进行 OpenHarmony 应用开发,可通过 File
-> Settings
-> OpenHarmony SDK
页签下载 OpenHarmony SDK
。
上图中,下载了 API10/API11/API12
的 3 个 SDK,保存在 Z:\workspace\ohsdk
的路径下
2.2.3. 替换 Full SDK
- 下载 K1 OH5.0 的 Full SDK,点我下载,目前 K1 OH5.0 仅支持 API12,系统支持 windows/macos/ubuntu 等,按照自己的开发机系统来下载。
- 下载了 Full SDK 后,进行解压,并将 Public SDK 中对应的目录替换掉即可
2.3. 真机调试
通过 hdc 成功连接开发设备后,Deveco Studio 右上角会显示连接的设备,以及一些运行调试的按键。
编译好的应用可以点击绿色的箭头在真机运行调试。hdc 的安装与使用方法请参照 K1 OH5.0 系统调试说明的 1.2 章节进行。
3. HelloWorld
3.1. 创建工程
- 双击运行
Deveco Studio
应用,进入配置导入页面,选择不导入任何配置(第一次是没有项目和配置的) - 根据工程创建向导,选择创建
Application
应用服务或Atomic Service
元服务。再选择需要的 Ability 工程模板,然后单击 Next。
- 在工程配置页面,需要根据向导配置工程的基本信息
Project name
:工程的名称,可以自定义,由大小写字母、数字和下划线组成。Bundle name
:标识应用的包名,用于标识应用的唯一性。Save location
:工程文件本地存储路径,由大小写字母、数字和下划线等组成,不能包含中文字符。Compatible SDK
:兼容的最低 API Version。Device type
:该工程模板支持的设备类型。
- 单击 Finish,工具会自动生成示例代码和相关资源,等待工程创建完成
3.2. 项目结构
AppScope
->app.json5
: 应用的全局配置信息entry
:OpenHarmony
工程模块,编译构建生成一个 HAP 包entry
->src
->main
->ets
:用于存放 ArkTS 源entry
->src
->main
->ets
->entryability
:应用/服务的入口。entry
->src
->main
->ets
->entrybackupability
:应用提供扩展的备份恢复能力。entry
->src
->main
->ets
->pages
:应用/服务包含的页面。entry
->src
->main
->resources
:用于存放应用/服务所用到的资源文件,如图形、多媒体、字符串、布局文件等entry
->src
->main
->module.json5
:模块配置文件。主要包含 HAP 包的配置信息、应用/服务在具体设备上的配置信息以及应用/服务的全局配置信息。entry
->build-profile.json5
: 当前的模块信息 、编译信息配置项,包括 buildOption、targets 配 置等。entry
->hvigorfile.ts
: 模块级编译构建任务脚本。entry
->obfuscation-rules.txt
: 混淆规则文件。混淆开启后,在使用 Release 模式进行编译时,会对代码进行编译、混淆及压缩处理,保护代码资产。entry
->oh-package.json5
: 用来描述包名、版本、入口文件(类型声明文件)和依赖项等信息。oh_modules
: 用于存放三方库依赖信息。build-profile.json5
: 工程级配置信息,包括签名signingConfigs
、产品配置 products 等。其中 products 中可配置当前运行环境,默认为 HarmonyOS。oh-package.json5
: 主要用来描述全局配置,如:依赖覆盖(overrides)、依赖关系重写(overrideDependencyMap)和参数化配置(parameterFile)等。
3.3. 页面编写
点击 entry
-> src
-> main
-> ets
-> pages
,打开 Index.ets
文件,进行页面的编写。
3.4. 修改 build-profile.json5
应用根目录的 build-profile.json5
中,将
"products": [
{
"name": "default",
"signingConfig": "default",
"compatibleSdkVersion": "5.0.0(12)",
"runtimeOS": "HarmonyOS",
"buildOption": {
"strictMode": {
"caseSensitiveCheck": true,
"useNormalizedOHMUrl": true
}
}
}
],
修改为
"products": [
{
"name": "default",
"signingConfig": "default",
"compileSdkVersion": 12,
"compatibleSdkVersion": 12,
"runtimeOS": "OpenHarmony"
}
],
3.5. 签名
点击 File
-> Project Structure
-> Signing Configs
,进入签名页面,进行如下设置,点击 Apply
,再点击 OK
即可。
3.6. 编译
点击 Build
-> Build Hap(s)/APP(s)
-> Build Hap(s)
进行编译,Build Output 中有如下输出,说明编译成功。
> hvigor Finished :entry:default@SignHap... after 3 ms
> hvigor Finished :entry:assembleHap... after 1 ms
> hvigor BUILD SUCCESSFUL in 35 s 204 ms
Process finished with exit code 0
Build Analyzer results available
3.7. 真机运行
点击右上角的运行按键,进行安装和运行。
4. 系统应用编译安装
以 launcher 为例说明系统应用编译安装过程。
注意:编译系统应用需要 Full SDK。