JSSDK 使用指南

`@htyf-mp/js-sdk` 使用指南

本文基于当前项目已安装的 @htyf-mp/js-sdk@0.2.20，整理一份可直接落地的使用说明：从安装、环境判断到常用 API 分组示例。

适用场景

在红糖云服容器内调用原生能力（扫码、弹窗、播放器、相册、文件等）。
在 app-template / web-template 中统一使用同一套 JS 调用方式。
在业务页面中快速接入宿主能力，而不是直接操作底层原生模块。

1. 安装与引入

npm i @htyf-mp/js-sdk

import jssdk from '@htyf-mp/js-sdk';

若模板已自带该依赖，通常无需重复安装。

2. 先做环境判断（强烈建议）

很多 API 依赖宿主容器；在浏览器或非容器环境下直接调用可能无效果。

const inHostApp = !!jssdk.client;
 
if (!inHostApp) {
  console.warn('当前不在红糖云服容器内，部分 API 不可用');
}

3. 最常用 API（推荐先接这几类）

3.1 交互反馈：`showToast` / `showModal`

await jssdk.showToast({
  type: 'success',
  title: '保存成功',
});
 
await jssdk.showModal({
  title: '确认提交',
  description: '提交后将不可撤销，是否继续？',
  confirmText: '继续',
  cancelText: '取消',
  onConfirm: () => console.log('用户确认'),
});

3.2 扫码：`openQR`

const result = await jssdk.openQR({ text: '请扫描二维码' });
if (result?.data) {
  console.log('扫码结果:', result.data);
}

3.3 布局适配：`getMenuButtonBoundingClientRect` / `getSafeAreaInsets`

const rect = jssdk.getMenuButtonBoundingClientRect();
const insets = await jssdk.getSafeAreaInsets();
 
console.log('胶囊按钮:', rect);
console.log('安全区:', insets);

3.4 剪贴板：`setClipboardString` / `getClipboardString`

await jssdk.setClipboardString('https://mp.dagouzhi.com');
const text = await jssdk.getClipboardString();
console.log(text);

3.5 文件能力：`downloadAndSaveFile`

const file = await jssdk.downloadAndSaveFile({
  fromUrl: 'https://example.com/demo.pdf',
  filename: 'demo.pdf',
  onProgress: ({ progress, speed }) => {
    console.log(`下载进度 ${progress}% (${speed})`);
  },
});
 
console.log('文件保存路径:', file.filePath);

4. 进阶能力索引（按类型）

媒体与选择器：openCamera、launchImageLibrary、launchCamera、getPhotos、pickDocument
播放能力：openAudioPlayer、openVideoPlayer
相册保存：saveImageToAlbum、saveVideoToAlbum
网络与系统：getNetworkState、addNetworkListener、getLocales、getCountry、getTimeZone
方向控制：lockToPortrait、lockToLandscapeLeft、unlockAllOrientations、addOrientationListener
文件系统：fsReadFile、fsWriteFile、fsReadDir、fsExists、zip、unzip
触感与音量：triggerHaptic、getVolume、setVolume、addVolumeListener
蓝牙 BLE：bleStart、bleScan、bleConnect、bleRead、bleWrite、bleAddListener

5. 在现有教程中的落点建议

todolist-workflow（app-template）：优先接 showToast、showModal、openQR。
todolist-web-workflow（web-template）：优先接 showToast、setClipboardString、getMenuButtonBoundingClientRect。
jump-game-workflow（game-template）：优先接 showToast、方向控制 API、音量/触感 API。

6. 常见问题

Q1：为什么本地 H5 环境调用没反应？

通常是因为不在宿主容器环境，jssdk.client 不可用。先做环境判断，再决定是否降级为普通 Web 逻辑。

Q2：怎么知道某个 API 的参数类型？

可直接看包内类型定义：node_modules/@htyf-mp/js-sdk/dist/types，尤其是 SDK.d.ts 与 types/options.d.ts。

Q3：如何避免 API 调用导致页面报错？

建议统一封装一层：

先判断 jssdk.client 是否存在；
使用 try/catch 包裹异步调用；
失败时回退到 Web 方案（如 navigator.clipboard / 自定义弹窗）。

JSSDK 使用指南

On this page