鸿蒙（OpenHarmony）集成指南

本文说明如何在 OpenHarmony 工程中接入 JsView SDK。

范围：HAR 交付与依赖接入；页面侧通过 JSViewMainPage 承载小程序。能力侧 Ability 如何拉起页面由业务自行决定，本文不约定。更细的 URL / Want / Bridge 约定见后续使用文档。

1. 交付内容

集成方会收到以下 HAR（版本号 v1.0.xxx 以实际交付为准，须整套同版本使用）：

text

com.qcode.jsview-JsViewApp-v1.0.xxx.har
com.qcode.jsview-JsViewCore-v1.0.xxx.har
com.qcode.jsview-jsview_plugin_interface-v1.0.xxx.har
com.qcode.jsview-jsvplayer-v1.0.xxx.har
com.qcode.jsview-v8engine-v1.0.xxx.har
com.qcode.jsview-jsvxtrn-v1.0.xxx.har
com.qcode.jsview-v8enhance-v1.0.xxx.har
com.qcode.jsview-forge_canvas-v1.0.xxx.har

与 ohpm 包名对应关系：

包名	HAR 文件	说明
`@shijiu/jsview-app`	`-JsViewApp-.har`	宿主层（Ability/Page 封装、参数解析、Bridge 入口）
`@shijiu/jsview-core`	`-JsViewCore-.har`	引擎与渲染核心
`@shijiu/jsview-plugin-interface`	`-jsview_plugin_interface-.har`	插件接口定义
`@shijiu/jsvplayer`	`-jsvplayer-.har`	播放器
`@shijiu/v8engine`	`-v8engine-.har`	V8 / JSE
`@shijiu/jsvxtrn`	`-jsvxtrn-.har`	扩展接口
`@shijiu/v8enhance`	`-v8enhance-.har`	V8 增强
`@shijiu/forge_canvas`	`-forge_canvas-.har`	Canvas

业务模块通常只需直接依赖 @shijiu/jsview-app；其余包通过工程根 overrides 统一锁定到上述本地 HAR。

2. 环境要求

DevEco Studio（或命令行 hvigorw / ohpm）
OpenHarmony SDK，compile / target / compatible = 18

3. 放入工程

将整套 HAR 放到工程目录，例如：

text

YourApp/
├── deps/
│   └── ohos-jsview-libs/
│       ├── com.qcode.jsview-JsViewApp-v1.0.xxx.har
│       ├── com.qcode.jsview-JsViewCore-v1.0.xxx.har
│       ├── com.qcode.jsview-jsview_plugin_interface-v1.0.xxx.har
│       ├── com.qcode.jsview-jsvplayer-v1.0.xxx.har
│       ├── com.qcode.jsview-v8engine-v1.0.xxx.har
│       ├── com.qcode.jsview-jsvxtrn-v1.0.xxx.har
│       ├── com.qcode.jsview-v8enhance-v1.0.xxx.har
│       └── com.qcode.jsview-forge_canvas-v1.0.xxx.har
├── oh-package.json5          # 根 overrides
├── build-profile.json5
└── entry/                    # 或 app/xxx feature 模块
    └── oh-package.json5      # 模块 dependencies

目录名可自定，只要与下文 overrides 路径一致即可。

注意：8 个 HAR 必须同版本，不要混用不同 v1.0.xxx。

4. 配置依赖

4.1 根工程 `oh-package.json5`（必须）

用 overrides 把所有 @shijiu/* 指到本地 HAR：

json5

{
  "modelVersion": "5.0.0",
  "dependencies": {},
  "overrides": {
    "@shijiu/jsview-app": "file:./deps/ohos-jsview-libs/com.qcode.jsview-JsViewApp-v1.0.xxx.har",
    "@shijiu/jsview-plugin-interface": "file:./deps/ohos-jsview-libs/com.qcode.jsview-jsview_plugin_interface-v1.0.xxx.har",
    "@shijiu/jsview-core": "file:./deps/ohos-jsview-libs/com.qcode.jsview-JsViewCore-v1.0.xxx.har",
    "@shijiu/jsvplayer": "file:./deps/ohos-jsview-libs/com.qcode.jsview-jsvplayer-v1.0.xxx.har",
    "@shijiu/jsvxtrn": "file:./deps/ohos-jsview-libs/com.qcode.jsview-jsvxtrn-v1.0.xxx.har",
    "@shijiu/v8engine": "file:./deps/ohos-jsview-libs/com.qcode.jsview-v8engine-v1.0.xxx.har",
    "@shijiu/v8enhance": "file:./deps/ohos-jsview-libs/com.qcode.jsview-v8enhance-v1.0.xxx.har",
    "@shijiu/forge_canvas": "file:./deps/ohos-jsview-libs/com.qcode.jsview-forge_canvas-v1.0.xxx.har"
  }
}

将路径中的 v1.0.xxx 改成实际交付版本号。

overrides：ohpm 根工程强制依赖覆写。无论各模块声明的是 latest 还是其它版本，最终都解析到此处指定的本地 HAR。

4.2 宿主模块 `oh-package.json5`

json5

{
  "name": "entry",
  "version": "1.0.0",
  "dependencies": {
    "@shijiu/jsview-app": "latest",
    "@shijiu/jsvplayer": "latest"
  }
}

说明：

latest 会被根 overrides 解析到本地 HAR，无需在模块里写文件路径。
@shijiu/v8engine 等其余包只需出现在根 overrides 中，业务模块一般不必直接依赖。

4.3 安装依赖

bash

ohpm install

或在 DevEco 中执行 Sync。

4.4 `build-profile.json5`

不需要把 JsView HAR 登记为工程 modules，作为 ohpm 依赖即可。

保证 product SDK 为 18：

json5

{
  "app": {
    "products": [
      {
        "name": "default",
        "targetSdkVersion": 18,
        "compileSdkVersion": 18,
        "compatibleSdkVersion": 18,
        "runtimeOS": "OpenHarmony"
      }
    ]
  },
  "modules": [
    { "name": "entry", "srcPath": "./entry", "targets": [{ "name": "default", "applyToProducts": ["default"] }] }
  ]
}

5. 权限（必须）

接入 JSViewMainPage 之前，宿主模块 module.json5 必须声明网络权限，否则无法加载线上小程序（含 CDN / http(s) 入口）：

json5

{
  "module": {
    // ...
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:PermissionReason"
      }
    ]
  }
}

ohos.permission.INTERNET 为必加项，其它权限按业务需要另行申请。

6. 代码接入：`JSViewMainPage`

从 @shijiu/jsview-app 引入 JSViewMainPage 与 MainPageController，放在任意页面中即可显示并加载小程序。组件自带启动图与加载失败提示。

请确认已完成第 5 节权限配置后再接入。

6.1 最小示例

typescript

import { JSViewMainPage, MainPageController } from '@shijiu/jsview-app';

@Entry
@Component
struct Index {
  private controller: MainPageController = new MainPageController();

  build() {
    JSViewMainPage({
      controller: this.controller,
      // 入口：完整小程序 URL，或已构造好的 MiniAppParams
      defaultParams: 'https://example.com/js/main.jsv.mjs',
    })
      .width('100%')
      .height('100%')
  }
}

加载完成后会隐藏启动图；失败时默认弹出加载失败对话框（可用 enableLoadFailPrompt 关闭）。

6.2 组件参数

参数	类型	必填	说明
`controller`	`MainPageController`	建议必填	不传也能用 `defaultParams` 首载，但无法再调用 `loadParams`、注册 Bridge、转发前后台等
`defaultParams`	`string \| MiniAppParams \| null`	条件必填	首次进入自动加载时必填；也可不传，改在合适时机调用 `controller.loadParams`。二者至少使用一种才会加载小程序
`localStartupImage`	`Resource \| string`	否	本地默认启动图；不传则用组件内置默认资源
`keepSurfaceInBackground`	`boolean`	否	退到后台时是否保持 Surface
`enableLoadFailPrompt`	`boolean`	否	是否弹出加载失败对话框，默认 `true`
`appLauncher`	`AppLauncher`	否	自定义小程序拉起逻辑；不传则用默认实现

6.3 通过 Controller 加载 / 切换

aboutToAppear 之后可用 controller 再次加载（例如收到新 Intent、按钮切换应用）：

typescript

// URL
this.controller.loadParams('https://example.com/js/main.jsv.mjs?startImg=https://.../startup.png');

// 或 MiniAppParams
import { MiniAppParams } from '@shijiu/jsview-app';
const params = new MiniAppParams();
params.url = 'https://example.com/js/main.jsv.mjs';
params.startUpImg = 'https://example.com/startup.png';
this.controller.loadParams(params);

行为摘要：

会先走内部 parser 解析 URL / 参数，再打开小程序。
相同 url 会跳过重复加载。
launchMode === 1 且 appName 相同时，不整页重载，改为向当前实例发 onNewIntent。

string 支持的 scheme（http(s)、file、jsvconfig、jsvappid、localjs 等）、以及 Want → MiniAppParams 的转换，见专用文档： MiniAppParams 入口与解析。

常用 MiniAppParams 字段（也可写在 URL query 里，如 startImg、enableDevTools、miniAppName）：

字段	含义
`url`	小程序入口地址
`startUpImg`	启动图 URL
`appName`	小程序名（缓存 / `launchMode` 判断用）
`launchMode`	启动模式；`1` 表示同 `appName` 时走 `onNewIntent`
`enableDevTools`	是否开启调试（还受 `JsViewPreConfig` 影响）

6.4 注册 JSBridge（公开接口）

通过 MainPageController.addJavascriptInterface 注册，入参为 @shijiu/jsview-app 的 JSBridge：

typescript

import { JSBridge, JSViewItemController, MainPageController } from '@shijiu/jsview-app';

const bridge: JSBridge = {
  bridgeName: 'demoBridge',
  syncMethodList: ['ping'],
  asyncMethodList: [],
  onJsViewBind: (jsView: JSViewItemController): object => {
    return {
      ping: (): string => 'pong',
    };
  },
};

this.controller.addJavascriptInterface(bridge);

在页面 aboutToAppear、且调用 loadParams / 依赖 defaultParams 加载之前注册，确保绑到即将启动的实例。方法明细与 JS 侧调用约定见 MainPageController 与相关 API。

6.5 前后台（嵌入宿主 Ability 时）

Ability 进入前台 / 后台时建议转发给 controller，便于引擎暂停 / 恢复：

typescript

// Ability.onForeground
this.controller.onAbilityForeground();

// Ability.onBackground
this.controller.onAbilityBackground();

若页面拿不到同一个 controller 实例，需自行在业务层把 Ability 与持有 controller 的页面打通。

6.6 加载状态监听（可选）

typescript

import { JSViewItem, JSViewRunTimeListener } from '@shijiu/jsview-app';

const listener: JSViewRunTimeListener = {
  onStartLoad: (item: JSViewItem): void => {},
  onLoadSuccess: (item: JSViewItem): void => {},
  onLoadFail: (item?: JSViewItem): void => {},
};

this.controller.addListener(listener);
// 页面销毁时：
this.controller.removeListener(listener);

7. 依赖侧验证

配置完第 4 节后，可先确认依赖能装上：

bash

ohpm install

成功标志：能解析到各 @shijiu/* HAR，无 ohpm 缺包；业务工程可继续按自身模块正常编译。

8. 升级

用新版本整套 HAR 替换旧文件。
更新根 oh-package.json5 → overrides 中的版本号路径。
重新 ohpm install，Clean 后全量编译。

不要只替换其中某一个 HAR，避免版本错配。

9. 常见问题

现象	排查
ohpm 找不到 `@shijiu/jsview-app`	根 `overrides` 路径是否与实际文件一致；是否执行过 `ohpm install`
编译期 HAR / so 冲突	`overrides` 是否锁同一套版本；是否残留旧 `oh_modules`
页面空白 / 不加载	是否设置了 `defaultParams`，或在合适时机调用了 `controller.loadParams`
无法访问线上 `.mjs`	是否已声明必选权限 `ohos.permission.INTERNET`（见第 5 节）；设备网络是否可达

10. 相关文档

MainPageController 与相关 API
MiniAppParams 入口与解析（jsvconfig 等链接形态、Want → MiniAppParams）

引导

Android 集成

如何启动小程序

Android-JS API

插件开发方案

高级功能

常见问题