MiniAppParams 入口与解析（鸿蒙）

JSViewMainPage / MainPageController.loadParams 除了直接传 MiniAppParams，还支持传入 string 链接。 内部走 JSViewApp.getInstance().getDefaultParser()，按 URL scheme 分发到不同 Parser。

本文说明：

1. string 支持哪些链接形式（含 jsvconfig 等）
2. 如何把 Ability 的 Want 转成 MiniAppParams
3. 链接 query / Want parameters 里常用的参数名

页面放置见 鸿蒙集成指南；Controller API 见 MainPageController 与相关 API。

1. 解析总览

loadParams(string | MiniAppParams)
  │
  ├─ MiniAppParams ──► 再经 DefaultParser 按 url 解析 / 合并
  │
  └─ string
       └─ DefaultParser：按 scheme 选 Parser
            ├─ http / https / file
            ├─ jsvconfig
            ├─ jsvappid
            └─ localjs

Want 不能直接传给 loadParams。请先 parse(want) 得到 MiniAppParams，再 loadParams（见第 4 节）。

2. loadParams(string) 支持的链接形式

均通过 DefaultParser 识别 scheme。未知 scheme 解析失败，不会加载。

2.1 http / https（最常用）

直接作为小程序入口；query 中的已知参数会写入 MiniAppParams，其余保留在最终 url 上。

https://cdn.example.com/app/js/main.jsv.mjs
https://cdn.example.com/app/js/main.jsv.mjs?startImg=https://cdn.example.com/s.png&enableDevTools=1

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

2.2 file

本地文件入口，解析规则与 http 类似（按路径与 query 填充参数）。

file:///data/.../homepage/js/main.jsv.mjs
file://${resourceDir}/homepage/js/main.jsv.mjs?startImg=file://${resourceDir}/startup.png

宿主需保证路径可读（如 resfile / resourceDir）。

2.3 jsvconfig（远程 JSON 配置）

形式：

jsvconfig://<原 scheme>/<host>/<path>...<可选原 query>

解析步骤：

1. 去掉 jsvconfig://
2. 把第一个 / 换成 ://，得到真实配置地址
3. HTTP GET 该地址，响应体为 JSON
4. JSON 字段通过 recvKeyValue 写入 MiniAppParams；必须含可识别的 url（或参数名 url）

示例：

jsvconfig://https/cdn.example.com/config/demo.json

实际请求：

https://cdn.example.com/config/demo.json

JSON 示例：

{
  "url": "https://cdn.example.com/app/js/main.jsv.mjs",
  "startImg": "https://cdn.example.com/startup.png",
  "miniAppName": "demo.app",
  "enableDevTools": true
}

注意：

• 需要网络权限（ohos.permission.INTERNET）。
• 若解析出的 url 仍是 http(s)，DefaultParser 还会再跑一遍 http 解析，合并参数。
• baseUrl 会记成原始的 jsvconfig://... 字符串。

2.4 jsvappid（按 AppId 拉取入口）

jsvappid://APPID_xxx
jsvappid://APPID_xxx?startImg=https://.../s.png&enableDevTools=1

• host 为 appId
• 向发现服务请求最新入口（默认 http://launcher.cluster.qcast.cn/discovery/entrance?category=lightapp&subtype=latestInfo，可通过 JsViewPreConfig.AppIdBaseUrl 覆盖），并附带 mac、appid
• 响应 status === 200 且 data[appId].url 存在时，得到最终小程序 URL
• 链路上的 query 会合并进 MiniAppParams，并拼进最终 url

依赖网络与正确的设备 mac 配置（JsViewPreConfig）。

2.5 localjs（本地化缓存）

localjs://...?miniAppName=<appName>&...

根据 query 里的 miniAppName 等读本地缓存参数；需业务侧先完成本地化相关缓存写入。无缓存时解析失败。

一般面向有本地化升级链路的宿主，普通集成可先用 http(s) / file / jsvconfig。

2.6 对照表

scheme	用途	是否网络	最终须落到可加载的小程序 url
http / https	直接入口	通常要	是（自身）
file	本地入口	否	是（自身）
jsvconfig	拉 JSON 配置再取 url	是	JSON 内 url
jsvappid	按 AppId 发现入口	是	服务返回的 url
localjs	本地化缓存入口	否	缓存内 url

3. Want → MiniAppParams

3.1 为什么要单独转？

• MainPageController.loadParams 只接受 string | MiniAppParams
• Ability 收到的是 Want
• 内部 WantParser（scheme 逻辑名 ability_want）从 want.parameters 读键值，填入 MiniAppParams；必须能解析出 url（参数名不区分大小写，见下表），否则返回 null

3.2 推荐写法

import { JSViewApp, MainPageController } from '@shijiu/jsview-app';
import { Want } from '@kit.AbilityKit';

// Ability.onCreate / onNewWant
async function openFromWant(want: Want, controller: MainPageController) {
  const result = await JSViewApp.getInstance().getDefaultParser().parse(want);
  if (result?.miniAppParams) {
    controller.loadParams(result.miniAppParams);
    return;
  }
  // 无 url：走业务默认入口
  controller.loadParams('https://cdn.example.com/js/main.jsv.mjs');
}

Want 示例（parameters 键名不区分大小写）：

const want: Want = {
  bundleName: 'com.example.app',
  abilityName: 'EntryAbility',
  parameters: {
    url: 'https://cdn.example.com/js/main.jsv.mjs',
    // 或 URL（见下表别名）
    startImg: 'https://cdn.example.com/startup.png',
    miniAppName: 'demo.app',
    enableDevTools: true,
  },
};

也可让 parameters.url 本身是 jsvconfig://... / jsvappid://...： WantParser 先写入 url，DefaultParser 在非 http(s) 方案且结果 url 以 http 开头时，会再套一层 http 解析合并参数。若 url 是 jsvconfig://...，需要你们在拿到 MiniAppParams 后再次 loadParams(params.url) 或 loadParams 整串，好让 jsvconfig Parser 跑完整流程——更稳妥的做法是：Want 里直接放最终 https 地址，或宿主对 jsvconfig / jsvappid 字符串走 loadParams(string)，不要只塞进 Want 指望一次 parse(want) 完成远程拉取。

实践建议：

场景	建议
外链拉起，已有最终 mjs	parameters.url = 'https://.../main.jsv.mjs'，parse(want) → loadParams
配置中心 / AppId	Ability 里对 string 直接 controller.loadParams('jsvconfig://...') 或 jsvappid://...
仅调试	parameters 带 url + startImg 等即可

3.3 与 JSViewApp.getDefaultParser() 的关系

loadParams(string)、Want 解析、首屏 defaultParams 字符串，都走同一套 DefaultParser。 业务一般不必自己注册 Parser；特殊定制可通过 JSViewApp.getInstance().setDefaultParser(...)（进阶用法）。

4. 常用参数名（query / Want.parameters / JSON）

写入 MiniAppParams 时键名不区分大小写，以下为可识别别名与属性对应关系：

MiniAppParams 字段	可识别参数名（任一）	类型	说明
url	url	string	小程序入口；Want 场景必填
baseUrl	baseurl	string	原始入口串（Parser 常自动填）
startUpImg	startimg / startupimage	string	启动图
enableDevTools	enabledevtools	boolean	调试开关（还受 JsViewPreConfig 影响）
appName	miniappname	string	小程序名；缓存 / launchMode 用
launchMode	miniapplaunchmode	number	1：同 appName 走 onNewIntent

布尔：true / 1 为真。数字：按整型解析。

未识别的键：http(s) 场景会留在最终 url 的 query 中；jsvconfig JSON 里则进入 invalidParams。

5. 与 loadParams 行为的衔接

解析成功后的去重 / 复用逻辑见 MainPageController 与相关 API，摘要：

• 相同 url：跳过
• launchMode === 1 且 appName 相同：onNewIntent，不整页重载

6. 示例汇总

import { JSViewApp, MainPageController, MiniAppParams } from '@shijiu/jsview-app';
import { Want } from '@kit.AbilityKit';

const controller = new MainPageController();

// A. https
controller.loadParams('https://cdn.example.com/js/main.jsv.mjs?startImg=https://cdn.example.com/s.png');

// B. jsvconfig
controller.loadParams('jsvconfig://https/cdn.example.com/config/demo.json');

// C. jsvappid
controller.loadParams('jsvappid://APPID_demo?enableDevTools=1');

// D. 手写 MiniAppParams
const p = new MiniAppParams();
p.url = 'https://cdn.example.com/js/main.jsv.mjs';
p.appName = 'demo.app';
controller.loadParams(p);

// E. Want
async function fromWant(want: Want) {
  const ret = await JSViewApp.getInstance().getDefaultParser().parse(want);
  if (ret?.miniAppParams) {
    controller.loadParams(ret.miniAppParams);
  }
}