小工具容器 · 能力清单

01运行环境

小工具是运行在受限沙箱环境里的纯 Web 应用（HTML / CSS / JS），请把它当作一个"能力受限的浏览器页面"来开发。

02可用能力

2.1 页面与渲染

2.2 媒体与文件

2.3 数据存储

• 数据仅属于当前小工具，其他小工具与外部无法访问。请勿假设数据永久持久化。
• Cookie 仅作本地存储：可正常读写并按 origin 隔离，但因不联网，cookie 不会随请求发往任何服务端，无法用于登录态 / 鉴权透传。需要本地存储优先用 localStorage / IndexedDB。

2.4 交互

2.5 资源加载规则

小工具为本地运行、不联网，容器对页面如何加载各类资源有明确约束（对应浏览器 CSP 限制）。所有资源须打包在小工具内（下表"包内资源"），另按类型额外允许 data: / blob: 等内存来源。

支持的文件类型

小工具包内仅支持以下文件类型：

实践要点

• 脚本必须外置：容器禁止内联脚本与行内事件处理器，请把 JS 写进包内 .js 文件用 <script src> 引入，事件绑定改用 addEventListener（不要用 onclick= 属性）。
• 样式可内联：<style> 和 style="..." 都能用，无需外置。
• 选图预览用 <img src> 配 data: 或 blob: 均可显示（如 FileReader.readAsDataURL 或 URL.createObjectURL）。

03端能力 JS API

除标准 Web 能力外，容器会自动注入 JS API SDK，小工具可通过 window.xhs.miniTool.* 调用 App 原生能力：发布笔记、保存图片到相册、把 base64 写成临时文件。无需在包内引入任何 SDK 脚本。

3.1 调用约定

const miniTool = window.xhs?.miniTool;
if (!miniTool) return; // 当前环境未注入端能力

// Promise 形态
try {
  await miniTool.saveImageToPhotosAlbum({ filePath });
} catch (err) {
  console.log(err.errMsg); // "saveImageToPhotosAlbum:fail ..."
}

// 回调形态（返回 undefined）
miniTool.saveImageToPhotosAlbum({
  filePath,
  success: (res) => console.log(res.errMsg),
  fail: (err) => console.log(err.errMsg),
  complete: () => {},
});

3.2 API 一览

3.3 postNote — 发布笔记

唤起 App 笔记发布页，并带入小工具产出的内容与媒体。用户在发布页可继续编辑或取消。

// 图文笔记
await window.xhs.miniTool.postNote({
  title: "我的作品",
  content: "用小工具生成的",
  mediaInfo: {
    image_resources: [{ url: "data:image/png;base64,iVBORw0KGgo..." }],
  },
});

// 视频笔记
await window.xhs.miniTool.postNote({
  mediaInfo: {
    video_resources: { video_url: videoPath, cover_url: coverPath },
  },
});

3.4 saveImageToPhotosAlbum — 保存图片到相册

// Canvas 导出直接保存
const dataUrl = canvas.toDataURL("image/png");
await window.xhs.miniTool.saveImageToPhotosAlbum({ filePath: dataUrl });

• 需由用户主动操作（点击等）触发，首次调用可能弹出系统相册权限弹窗；用户拒绝授权会走失败回调。
• 大图建议先 writeTempFile 落成文件再保存，避免超长 base64 上行。

3.5 writeTempFile — base64 转临时文件

把内存里的 base64（Canvas 导出、选图预览结果等）写成容器内的临时文件，换取可传给其他 JS API 的 filePath。

const { filePath } = await window.xhs.miniTool.writeTempFile({
  data: canvas.toDataURL("image/png"),
});

await window.xhs.miniTool.saveImageToPhotosAlbum({ filePath });
// 或带入发布页
await window.xhs.miniTool.postNote({
  mediaInfo: { image_resources: [{ url: filePath }] },
});

• 返回的是临时文件，不保证长期有效，请即用即弃，不要持久化保存该路径。
• 仅支持常见图片 / 视频类型（png、jpeg、webp、gif、mp4），其他类型会失败。

04不可用能力

以下能力在容器内已被禁用，调用会失败（抛出异常、返回空值或被拦截），请勿使用。

4.1 已禁用的 Web API

4.2 已禁用的行为

4.3 移动端不支持

以下能力移动端 WebView 本身不支持，无法使用：支付 PaymentRequest、系统通知 / 推送、NFC、MIDI、XR / AR / VR、后台同步 / 下载、PWA 安装、窗口管理、指针 / 键盘锁定等。

05WebGL / 图形计算边界

纯 WebGL 渲染可用，但组合能力受限：

WebGL 适合用打包在小工具内的资源做本地渲染；需要 AI 图像处理等重计算的场景无法支持（既不能联网也不能跑 WASM 模型）。