跳到主要内容

K1 OH5.0 应用开发说明

修订记录

修订版本修订日期修订说明
0012025-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。

4.1. 打开应用工程​

将 applications/standard/launcher 拷贝到 D 盘，目录不要有中文，可能会有问题，Deveco Studio 中，点击 File -> Open，选择 launcher 文件夹打开。

4.2. 编译​

点击 Build -> Build Hap(s)/APP(s) -> Build Hap(s) 进行编译，Build Output 中有如下输出，说明编译成功。

> hvigor Finished :pad_launcher:assembleHap... after 1 ms 
> hvigor Finished :phone_launcher:default@SignHap... after 3 s 484 ms 
> hvigor Finished :phone_launcher:assembleHap... after 1 ms 
> hvigor BUILD SUCCESSFUL in 4 min 16 s 555 ms 

Process finished with exit code 0

Build Analyzer results available

launcher 编译完成后，会生成 2 个 hap，launcher\product\phone\build\default\outputs\default\phone_launcher-default-signed.hap 和 launcher\feature\settings\build\default\outputs\default\launcher_settings-phone_launcher-default-signed.hap

4.3. 安装​

系统应用安装没办法像非系统应用那样直接点击安装按键，需要执行一系列操作，可以写一个脚本一键安装，如下：

hdc shell mount -o rw,remount /
hdc shell rm -rf /system/app/com.ohos.launcher/*
hdc shell rm -rf /data/*
hdc file send D:\HAP_CODE\launcher\product\phone\build\default\outputs\default\phone_launcher-default-signed.hap /system/app/com.ohos.launcher/Launcher.hap
hdc file send D:\HAP_CODE\launcher\feature\settings\build\default\outputs\default\launcher_settings-phone_launcher-default-signed.hap /system/app/com.ohos.launcher/Launcher_Settings.hap
hdc shell rm -rf /data/*
hdc shell sync /system/bin/udevadm trigger

pause

hdc shell reboot

5. 系统签名

如何将 1 个普通应用赋予系统权限呢？那就是用 Full SDK 对其进行系统签名，下面介绍进行系统签名的过程。

5.1. 签名工具介绍​

签名工具的路径在 ohsdk\12\toolchains\lib，如下：

fuqiang@snode1:~/workspace/ohsdk/12/toolchains/lib$ tree
.
├── app_check_tool.jar
├── app_packing_tool.jar
├── app_unpacking_tool.jar
├── hap-sign-tool.jar
├── OpenHarmony.p12
├── OpenHarmonyProfileDebug.pem
├── OpenHarmonyProfileRelease.pem
├── UnsgnedDebugProfileTemplate.json
└── UnsgnedReleasedProfileTemplate.json

0 directories, 9 files

5.2. 修改配置​

修改 UnsgnedDebugProfileTemplate.json 文件和 UnsgnedReleasedProfileTemplate.json 文件的应用包名、权限、应用类型，如下：

"bundle-name":"com.example.myapplication",
"apl":"normal",
"app-feature":"hos_normal_app"

修改为：

"bundle-name":"com.example.myapplication",
"apl":"system_core",
"app-feature":"hos_system_app"

5.3. 生成 p12​

java -jar hap-sign-tool.jar generate-keypair -keyAlias "ohos-app" -keyAlg "ECC"  -keySize "NIST-P-256" -keystoreFile "app.p12" -keyPwd "ohos123456" -keystorePwd "ohos123456"

5.4. 生成 csr​

java -jar hap-sign-tool.jar generate-csr -keyAlias "ohos-app" -keyPwd "ohos123456" -subject "C=CN,O=OpenHarmony,OU=OpenHarmony Team,CN=OpenHarmony Application Release" -signAlg "SHA256withRSA" -keystoreFile "app.p12" -keystorePwd "ohos123456" -outFile "app.csr"

5.5. 生成 cer​

keytool -gencert -alias "OpenHarmony Application CA" -infile app.csr -outfile app-release.cer -keystore OpenHarmony.p12 -sigalg SHA384withECDSA -storepass 123456 -ext KeyUsage:“critical=digitalSignature” -validity 36500 -rfc

5.6. 生成 p7b​

java -jar hap-sign-tool.jar sign-profile -keyAlias "openharmony application profile release" -signAlg "SHA256withECDSA" -mode "localSign" -profileCertFile "OpenHarmonyProfileRelease.pem" -inFile "UnsgnedReleasedProfileTemplate.json" -keystoreFile "OpenHarmony.p12" -outFile "app-release-profile.p7b" -keyPwd "123456" -keystorePwd "123456"

5.7. 配置 Deveco Studio 的签名​

Store file(*.p12)：    app.12
keyAlias：             ohos-app
Store Password：       ohos123456
key Password：         ohos123456
Profile file(*.p7b)：  app-release-profile.p7b
Certpath file(*.cer)： app-release.cer

6. FAQ

6.1. deveco studio 中新建项目时候，application 和 atomic service 有什么差别？​

在 DevEco Studio 中新建项目时，Application（普通应用）和 Atomic Service（元服务）是两种不同的工程类型，核心差异如下：

功能定位与入口形式​

典型场景‌：

  • 天气预报卡片（Atomic Service）无需安装即可展示信息
  • 购物应用（Application）需用户安装并主动打开

工程结构与部署方式​

关键配置差异‌：

  • Atomic Service 需在 module.json5 中声明 abilities.formEnabled: true 以支持卡片形态
  • 若误选 Atomic Service 但需桌面图标，需修改 config.json 中 installationFree: false

开发限制与兼容性​

适用场景总结​

  • 选 Application‌： 需独立安装、完整交互的应用（如游戏、社交软件）
  • 选 Atomic Service‌： 无需安装的场景化服务（如快递卡片、智能家居控制卡片）

6.2. 安装应用报签名错误​

报错如下：

Install Failed: error: failed to install bundle.
code:9568393
error: verify code signature failed.
The target device does not work with apps with an OpenHarmony signature. Sign the app with a HarmonyOS signature before installing it on the device.
Open signing configs
06/10 19:21:15:585: $ hdc shell rm -rf data/local/tmp/23b3eb890bb24bfb9d7ec34993386a6a
06/10 19:21:15:586: Launch com.example.myapplication failed, starting handle failure progress
Error while Deploy Hap

解决方案：

  • 应用根目录的 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"
  }
],
  • 进入签名设置页面，勾选 Automatically generate signature，不要勾选 Support HarmonyOS，再点击 Apply 和 OK 即可。

  • 重新编译安装应用