193 lines
5.9 KiB
Markdown
193 lines
5.9 KiB
Markdown
# 小工具 JSBridge API 规范
|
||
|
||
容器会注入 **`window.xhs.miniTool.*`**，业务代码通过它调用 Native 能力。字段以本文档为准，表中未声明的字段不要传。
|
||
|
||
## 调用约定
|
||
|
||
| 项 | 规则 |
|
||
| --- | --- |
|
||
| 入口 | `window.xhs.miniTool.<apiName>(options)` |
|
||
| 两种用法 | 不传回调 → 返回 `Promise`；传 `success` / `fail` / `complete` 任一 → 返回 `undefined`，经回调拿结果 |
|
||
| 成功 | Promise resolve / `success(result)`；关注业务字段（见各 API「结果」），无业务字段则结果为空 |
|
||
| 失败 | Promise reject / `fail(error)`；失败原因看 `error.errMsg`（形如 `<apiName>:fail …`），可能带 `errCode` |
|
||
| `complete` | 成功或失败都会回调，参数为对应的 result / error |
|
||
| 禁止 | 不要调用本文未列出的 API，不要传字段表未声明的字段 |
|
||
|
||
## API 索引
|
||
|
||
| API | 说明 |
|
||
| --- | --- |
|
||
| [`postNote`](#postnote) | 发布笔记 |
|
||
| [`saveImageToPhotosAlbum`](#saveimagetophotosalbum) | 保存图片到系统相册 |
|
||
| [`openRedPage`](#openredpage) | 通用原生页面跳转 |
|
||
| [`writeTempFile`](#writetempfile) | base64 转临时文件 |
|
||
|
||
## postNote
|
||
|
||
发布笔记。
|
||
|
||
- **调用**：`window.xhs.miniTool.postNote(options)`
|
||
|
||
### 使用规则
|
||
|
||
- `mediaInfo` 必填；`image_resources`（图文）、`video_resources`（视频）、`live_photo_resources`（实况）至少传一种，可同时传。
|
||
- 所有地址（`url` / `video_url` / `cover_url`）承载 base64 data:uri 或网络地址，格式由 Native 侧校验。
|
||
|
||
### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| `title` | string | 否 | 标题，最长 20 |
|
||
| `content` | string | 否 | 正文，最长 1000 |
|
||
| `pageType` | `"video_publish" \| "photo_publish" \| "slides_edit"` | 否 | 页面类型 |
|
||
| `mediaInfo` | object | 是 | 见「mediaInfo」 |
|
||
| `tags` | string | 否 | 标签 |
|
||
|
||
**`mediaInfo`**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| `image_resources` | `{ url }[]` | 否 | 图文，1–18 张；`url` 图片地址 |
|
||
| `video_resources` | `{ video_url, cover_url? }` | 否 | 视频；`video_url` 视频地址，`cover_url` 可选封面 |
|
||
| `live_photo_resources` | `{ url, video_url }[]` | 否 | 实况，1–18 张；`url` 动图封面，`video_url` 动图视频 |
|
||
|
||
### 结果
|
||
|
||
成功结果仅含通用 `errMsg`，无额外业务字段。
|
||
|
||
### 示例
|
||
|
||
图文笔记：
|
||
|
||
```js
|
||
await window.xhs.miniTool.postNote({
|
||
title: "标题",
|
||
content: "正文",
|
||
pageType: "photo_publish",
|
||
mediaInfo: {
|
||
image_resources: [{ url: "data:image/png;base64,..." }],
|
||
},
|
||
});
|
||
```
|
||
|
||
视频笔记：
|
||
|
||
```js
|
||
await window.xhs.miniTool.postNote({
|
||
pageType: "video_publish",
|
||
mediaInfo: {
|
||
video_resources: { video_url: "...", cover_url: "..." },
|
||
},
|
||
});
|
||
```
|
||
|
||
## saveImageToPhotosAlbum
|
||
|
||
保存图片到系统相册。
|
||
|
||
- **调用**：`window.xhs.miniTool.saveImageToPhotosAlbum(options)`
|
||
|
||
### 使用规则
|
||
|
||
- `filePath` 只接受 base64 data:uri 或本地路径，传网络地址（`http(s)://`）会失败。
|
||
- 已有 base64 时可先调 `writeTempFile` 换取本地 `filePath`，再传入本 API。
|
||
- 需由用户主动操作触发；首次调用可能弹系统相册权限。
|
||
|
||
### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| `filePath` | string | 是 | 本地图片路径（base64 data:uri 或本地引用），不支持网络地址 |
|
||
|
||
### 结果
|
||
|
||
成功结果仅含通用 `errMsg`，无额外业务字段。
|
||
|
||
### 示例
|
||
|
||
```js
|
||
await window.xhs.miniTool.saveImageToPhotosAlbum({
|
||
filePath: "data:image/png;base64,...",
|
||
});
|
||
```
|
||
|
||
## openRedPage
|
||
|
||
通用原生页面跳转。
|
||
|
||
- **调用**：`window.xhs.miniTool.openRedPage(options)`
|
||
|
||
### 使用规则
|
||
|
||
- `type` 命中 Native 规则表白名单才放行，未命中直接失败；规则表由客户端维护。
|
||
- `params` 为语义参数，由规则表映射到目标页面；信任字段由客户端强制注入。
|
||
- 跳转会离开当前小工具页面，调用前应完成本地状态持久化。
|
||
|
||
### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| `type` | string | 是 | 规则表 key（如 search / note / user…） |
|
||
| `params` | object | 否 | 语义参数（如 `{ keyword }`） |
|
||
|
||
### 结果
|
||
|
||
成功结果仅含通用 `errMsg`，无额外业务字段。
|
||
|
||
### 示例
|
||
|
||
```js
|
||
await window.xhs.miniTool.openRedPage({
|
||
type: "search",
|
||
params: { keyword: "连衣裙" },
|
||
});
|
||
```
|
||
|
||
## writeTempFile
|
||
|
||
base64 转临时文件，返回可传给其他 API 的 `filePath`。
|
||
|
||
- **调用**：`window.xhs.miniTool.writeTempFile(options)`
|
||
|
||
### 使用规则
|
||
|
||
- 用于把内存中的 base64（Canvas 导出、选图预览等）落成本地文件，换取 `filePath`。
|
||
- **`data` 必须是完整 data:uri**，即 `data:<mime>;base64,<payload>` 开头（如 `data:image/png;base64,iVBORw0KGgo...`）；只传裸 base64 字符串会失败。
|
||
- `canvas.toDataURL()` / `FileReader.readAsDataURL()` 的返回值已是 data:uri，**不要**再截取 `,` 之后的部分。
|
||
- 返回的 `filePath` 为临时文件，即用即弃。
|
||
|
||
### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | :---: | --- |
|
||
| `data` | string | 是 | 完整 data:uri（`data:<mime>;base64,<payload>`），不接受裸 base64 |
|
||
|
||
### 结果
|
||
|
||
成功结果在通用 `errMsg` 之外附带：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `filePath` | string | 转换得到的临时文件路径 |
|
||
|
||
### 示例
|
||
|
||
```js
|
||
// canvas.toDataURL() 直接就是 data:uri，原样传入
|
||
const { filePath } = await window.xhs.miniTool.writeTempFile({
|
||
data: canvas.toDataURL("image/png"), // "data:image/png;base64,iVBORw0KGgo..."
|
||
});
|
||
await window.xhs.miniTool.saveImageToPhotosAlbum({ filePath });
|
||
```
|
||
|
||
错误用法：
|
||
|
||
```js
|
||
// ✗ 裸 base64，会失败
|
||
await window.xhs.miniTool.writeTempFile({ data: "iVBORw0KGgo..." });
|
||
// ✗ 手动去掉了 data:uri 前缀
|
||
await window.xhs.miniTool.writeTempFile({
|
||
data: canvas.toDataURL("image/png").split(",")[1],
|
||
});
|
||
```
|