HarmonyOS SDK for OpenHarmony 实战指南:让 OpenHarmony 用上 HarmonyOS 的八个 Kit

适用读者:① 想在 OpenHarmony 应用里调 Preview Kit(文件预览)、Share Kit(分享)、Scan Kit(扫码)、Push Kit(推送)、Core Speech/Vision Kit(语音/视觉 AI)、Remote Communication Kit(HTTP)、Desktop Extension Kit(状态栏/快捷栏)的应用开发者;② 需要把这些 Kit 的系统侧实现编进自己产品镜像的设备开发者。

一、它是什么,和普通 HarmonyOS SDK 有什么区别

HarmonyOS SDK for OpenHarmony 是华为 2026 年 8 月首次发布的开源 Kit 合集,托管在 GitCode 组织 harmonyos-sdk-for-openharmony 下。一句话定位:

HarmonyOS SDK 的开源实现,接口定义与 HarmonyOS 保持一致,用来扩展 OpenHarmony SDK 的能力。

它分两个视角,这也是本文的两条主线:

视角你拿到的东西形态
应用开发8 类 API 接口(SDK 包)一个 526KB 的 harmonyos_sdk_for_openharmony.har
设备开发8 类 API 的系统侧实现(Framework)一堆源码仓,编进 OH 6.1 LTS 镜像

为什么需要它?因为 @ohos.file.preview、@kit.ShareKit 这类接口不在开源 OpenHarmony SDK 里(笔者在 DevEco Studio 6.1 内置 SDK 中逐一确认过)。以前想在 OH 设备上用这些能力只有两条歪路:自己逆向闭源 hap,或者从 HarmonyOS NEXT 设备提取(会被签名校验拒绝)。现在华为把接口定义和参考实现都开源了。

网上流传的旧方案(如 CSDN 上的《OpenHarmony 替换 Full SDK 全攻略》系列)解决的是另一个问题——把 OH 公版 SDK 换成带系统 API 的 full-SDK;而本文的方案不动 SDK 本体,只往工程里挂一个 HAR、往编译器插件里加一行路径,干净且可逆。

二、应用开发者:三步接入

2.1 下载 HAR 包

从 release-assets 仓库的 Release 附件下载(当前 6.1.0 Release):

https://gitcode.com/harmonyos-sdk-for-openharmony/release-assets/releases/download/HarmonyOS_SDK_for_OpenHarmony_6.1.0_Release/harmonyos_sdk_for_openharmony.har

(配套 DevEco Studio 6.1.0 Release,OpenHarmony 6.1 LTS / API 23)

2.2 把 HAR 挂进工程

  1. 在项目根目录新建 lib/ 目录,把 har 放进去;
  2. 修改根目录 oh-package.json5:
  "dependencies": {
    "harmonyos_sdk_for_openharmony": "file:lib/harmonyos_sdk_for_openharmony.har"
  },
  1. 点 Sync Now。看到 oh_modules/harmonyos_sdk_for_openharmony 出现即导入成功。

2.3 让编译器认识这些 API(关键一步)

HAR 里的 d.ts 不会被自动纳入 ArkTS 编译的 API 搜索路径,需要给 DevEco 的 hvigor 插件加一行配置。

文件位置:DevEco Studio\tools\hvigor\hvigor-ohos-plugin\src\tasks\abstract\abstract-compile-node.js

在 getExternalApiPaths() 方法里 push 你的 ets 路径:

    getExternalApiPaths() {
        this.externalApiPaths.push("E:/YourProject/oh_modules/harmonyos_sdk_for_openharmony/ets"); // 换成你的实际路径
        return this.compileApiVersion > sdk_const_js_1.ApiVersion.API_VERSION_9 && this.targetData.isHarmonyOS() && this.sdkInfo.getHmsArkDir() && this.externalApiPaths.push(this.sdkInfo.getHmsArkDir()),
        this.externalApiPaths
    }

注意事项(官方文档特别强调):

  • 路径用左斜杠 /;
  • 只加 this.externalApiPaths.push(...) 这一行,不要把整个方法抄进去;
  • 如果 oh_modules/.ohpm/ 下出现 harmonyos_sdk_for_openharmony@pctqlw9... 这样的长哈希目录名,属正常现象(版本哈希标识),路径直接照抄即可;
  • 改完 File → Invalidate Caches 重启 DevEco,然后 BUILD → Clean Project → Rebuild Project。

如果工程里有 Native C++ 代码,还要在 entry/src/main/cpp/CMakeLists.txt 里把 SDK 的工具链文件指给 PACKAGE_FIND_FILE:

# 在 include(${PACKAGE_FIND_FILE}) 之前
set(PACKAGE_FIND_FILE ${CMAKE_CURRENT_SOURCE_DIR}/../../../../oh_modules/harmonyos_sdk_for_openharmony/native/build/cmake/ohos.toolchain.cmake)

2.4 代码调用(以 Preview Kit 为例)

import { filePreview } from '@kit.PreviewKit';

// 两个核心 API(@since 11)
filePreview.canPreview(context, uri).then((supported: boolean) => { /* ... */ });
filePreview.openPreview(context, previewInfo, displayInfo?).then(() => { /* ... */ });

官方样例仓:preview-kit_sample-code(每个 Kit 都有对应的 xxx_sample-code 仓)。

2.5 应用侧的两个坑

  1. 设备镜像必须已包含 Kit 的系统侧实现。filePreview.openPreview() 这类 API 只是壳,真正干活的是系统里预置的服务和应用——Preview Kit 对应的就是预置应用 com.ohos.preview_system_app(开源仓 filemanagement_preview_app)。镜像里没有它,API 调用必然失败。开发板可以直接刷官方提供的 P7885 标准系统 ROM 包(已集成全部 Kit,见 release-notes);自制镜像走第三章。可以用官方 HCTS 包做兼容性测试。
  2. IDE 飘红"缺少 syscap 能力"不影响编译和功能(官方 FAQ 原话),忽略即可。

三、设备开发者:把 Kit 编进自己的镜像

以 Preview Kit + Wukong100(RK 方案参考板)为例,完整走一遍。前置条件:Ubuntu 22.04 环境,已按OpenHarmony 设备开发指导拉取 OH 6.1 LTS 源码并成功编出镜像。

3.1 用 repo manifests 拉取 Kit 源码

在 .repo/manifests/ohos/ 下创建 extension_kits.xml:

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
  <remote fetch="https://gitcode.com/harmonyos-sdk-for-openharmony" name="harmonyos-sdk-for-openharmony"/>

  <!-- Preview Kit:框架仓 + openFileBoost 仓 -->
  <project groups="default,ohos:standard,ohos:system" name="filemanagement_preview"
           path="foundation/filemanagement/file_preview" remote="harmonyos-sdk-for-openharmony" revision="master"/>
  <project groups="default,ohos:standard,ohos:system" name="filemanagement_open_file_boost"
           path="foundation/filemanagement/open_file_boost" remote="harmonyos-sdk-for-openharmony" revision="master"/>
</manifest>

在 .repo/manifests/default.xml 中引入:

  <include name="ohos/extension_kits.xml"/>

然后同步:

repo sync -c

各 Kit 的仓配置(依赖关系)官方文档已列全。几个要点:

  • PDF Kit 依赖最重:要拉 filemanagement_pdf_service + third_party/pdfium + pdfium 的 9 个三方子仓(freetype/zlib/libpng/libopenjpeg/libjpeg_turbo/lcms/icu/agg23/abseil-cpp),并把这一串 GN 目标加入 build/compile_standard_whitelist.json 的 third_deps_bundle_not_add 白名单;
  • Core Vision Kit 和 Scan Kit 都依赖 opencv,同时集成只需配置一次;
  • Remote Communication Kit 依赖带补丁的 curl,需要屏蔽底座 ohos.xml 里原有的 third_party_curl 避免冲突。

3.2 集成配置四步(Preview Kit)

① 产品配置 —— vendor/<厂商>/<产品>/config.json,在 subsystems 里加组件:

  "subsystems": [
    {
      "subsystem": "filemanagement",
      "components": [
        { "component": "hipreview", "features": [] },
        { "component": "open_file_boost", "features": [] }
      ]
    }
  ]

(component 名必须与仓内 bundle.json 的 name 一致)

② 子系统配置 —— build/subsystem_config.json(已有 filemanagement 则跳过):

  "filemanagement": {
    "path": "foundation/filemanagement",
    "name": "filemanagement"
  },

③ 系统能力(syscap)配置 —— developtools/syscap_codec/include/codec_config/syscap_define.h,两处各加两条:

SystemCapabilityNum {
    // ...
    FILEMANAGEMENT_FILEPREVIEW_CORE,
    PCSERVICE_OPENFILEBOOST,
}

SyscapWithNum{
  // ...
  {"SystemCapability.FileManagement.FilePreview.Core", FILEMANAGEMENT_FILEPREVIEW_CORE},
  {"SystemCapability.PCService.OpenFileBoost", PCSERVICE_OPENFILEBOOST},
}

④ 系统应用配置 —— Preview Kit 的用户可见载体是预置应用 PreviewSystemApp,流程:

  1. 单独用 DevEco 编译 filemanagement_preview_app 仓(签名材料在仓内 signature/ 目录,产物命名 PreviewSystemApp.hap)。因为用了系统 API,DevEco 的 OpenHarmony SDK 要先换成 ohos-sdk-full 6.1-LTS,并按第二章配好 harmonyos_sdk_for_openharmony(它 import 了 @kit.ShareKit);
  2. 把 hap 放进 applications/standard/hap/,在 BUILD.gn 挂上:
ohos_prebuilt_etc("preview_hap") {
  source = "PreviewSystemApp.hap"
  module_install_dir = "app/com.ohos.preview_system_app"
  part_name = "prebuilt_hap"
  subsystem_name = "applications"
}

group("hap") {
  deps = [
    "//applications/standard/hap:preview_hap",
  ]
}
  1. 产品 preinstall-config/ 下两个文件:
// install_list.json —— 预安装
{ "app_dir": "/system/app/com.ohos.preview_system_app", "removable": true }

// install_list_capability.json —— 特权(系统应用校验、隐藏图标、关联唤醒)
{
  "bundleName": "com.ohos.preview_system_app",
  "app_signature": ["8E93863FC32EE238060BF69A9B37E2608FFFB21F93C862DD511CBAC9F30024B5"],
  "allowAppUsePrivilegeExtension": true,
  "allowAppDesktopIconHide": true,
  "associatedWakeUp": true
}

⚠️ 签名指纹必须和你实际签名 hap 的证书一致。官方两处文档给的 app_signature 就不一样(集成文档 8E93863F...、仓 README 9EC7BA34...,对应不同签名证书),照抄大概率翻车——预览器内部有 checkIsSysApp 校验,指纹不匹配时特权不生效、系统应用调用方会被拒。用 hdc shell bm dump -n com.ohos.preview_system_app 可查已装应用的 appSignatures 做核对。

3.3 编译与烧录

# 下载预编译工具链
./build/prebuilts_download.sh

# 编译镜像(以 wukong100 为例)
./build.sh --product-name wukong100 --ccache --gn-args make_pac_format_image=true

产物在 out/wukong100/packages/phone/images,按开发板烧录指南刷机。已有设备不想重编的话,直接刷官方 P7885 ROM 包(集成 HMOS SDK for OH 的 OH 6.1.0.35 二进制)也行。

四、能力边界:以 Preview Kit 为例的避坑提示

接入只是开始,实际能力取决于系统侧实现版本。笔者逆向分析过 RT80 设备上的 PreviewSystemApp(v1.0.0)并与开源 master 版逐行比对,几个值得知道的边界:

  1. 应用 API 是壳,能力看系统:filePreview.openPreview() 最终拉起的就是 com.ohos.preview_system_app,它内部再路由到图片/文本/PDF/音视频/网页等查看器;
  2. 开源 master 版比厂商集成版更弱:开源版 SingalFilePreview.loadPreviewPage 里 LOAD_STATE_PDF 分支直接跳失败页(pdfView 被剥离,要 PDF 得再集成 PDF Kit 的 PdfView),而 RT80 厂商版 PDF 预览完整可用(注释/搜索/打印);
  3. Office 全系(doc/docx/xls/xlsx/ppt/pptx/rtf/csv/WPS/OFD)在两版里都是死代码:officeUTDSet 白名单(35 项 UTD)构建后没有任何查询点,Office 文件一律落"不支持"页。想支持 Office,得自己在 getOpenType 里接上这个集合并实现渲染;
  4. .ts 文件会被当视频打开(源码注释:“默认把.ts文件当作视频文件处理”)——TypeScript 源码和 MPEG-TS 视频撞了后缀,系统选择了后者。

所以"能不能用 Preview Kit"要拆成两问:镜像里有没有装(第三章解决)→ 装的版本支持你要的格式吗(看实现,别只看 API)。

五、总结

你是谁你要做的事
应用开发者下载 HAR → 挂依赖 → 改 hvigor 插件一行路径 → 调 @kit.PreviewKit 等 API → 确认设备镜像含 Kit 实现
设备开发者repo 拉 Kit 源码 → 产品/子系统/syscap/预置应用四步配置 → build.sh 编镜像烧录
只想在开发板上体验直接刷官方 P7885 ROM(已集成全部 Kit)

整体设计比社区旧的"替换 Full SDK"方案优雅:SDK 本体零侵入,系统侧以可选部件(component)形式按需集成,符合 OpenHarmony 的部件化架构。当前版本(6.1.0 Release)的主要短板是个别 Kit 的开源实现落后于商业版(如 Preview Kit 的 PDF/Office),选型时务必按第四章的思路核对能力边界,而不是只看接口文档。

参考

# harmonyos # 华为
Logo
开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

OpenHarmony 上读卡、推理和双屏刷新抢 CPU：核验机与消费机的调度差

鸿蒙人脸识别在RK3568+OpenHarmony平台下，卡顿主因常为调度而非算法。关键路径需优化：读卡、活体、推理、落账等环节应合理分配优先级与核绑定，避免资源争抢。门禁、消费、人证三类场景线程配置不可共用，否则易导致丢帧或会话冲突。建议按产品线打包调度参数，强化日志观测，精准定位瓶颈。最终比拼的是关键路径调度能力，而非口号。

avatar 开源鸿蒙跨平台开发者社区

React Native 三方库「react-native-restart-app」的鸿蒙化适配指南

应用完成某些必须重启才能生效的配置后，可以通过明确的用户操作触发重启。重启之前需要先完成必要的持久化，不能依赖进程退出时再保存数据。鸿蒙实现读取当前宿主的 bundleName、moduleName 和 Ability 名称，避免把示例应用的身份硬编码到库中。默认导出 restartApp 与具名 restart 是同一函数，返回 void。系统仅允许顶部前台应用重启，成功重启间隔至少 3 秒；错

avatar 开源鸿蒙跨平台开发者社区

【KMP for OpenHarmony】Cache4k 0.14.0 鸿蒙适配

0.14.0（仅ohosArm64变体）验证设备：nova 14 Ultra，HarmonyOS API 26。

avatar 开源鸿蒙跨平台开发者社区