qsh-webview-sdk

v2.0.9

Published

a month ago

UniApp WebView SDK for WeChat MiniProgram and App

0High
0Medium
0Low

jzdkg

uniapp webview sdk wechat miniprogram

QSH WebView SDK

一个重构后的 QSH WebView SDK，支持微信小程序和 APP 端的 WebView 与原生端通信。

特性

✅ 支持微信小程序 WebView
✅ 支持 APP 端 (Plus/NVUE/UVUE)
✅ 模块化架构，易于维护
✅ TypeScript 类型支持
✅ UMD 和 ESM 双格式输出
✅ 自动环境检测

安装

NPM 安装

npm install qsh-webview-sdk

CDN 引入

<script src="path/to/qsh-webview-sdk.umd.js"></script>

使用方法

在 HTML 中引入

<!-- 引入 QSH WebView SDK（内部会在微信内的小程序 web-view 环境自动注入 jweixin） -->
<script type="text/javascript" src="path/to/qsh-webview-sdk.umd.js"></script>

说明：通过 UMD 方式引入后，默认在全局暴露 window.qsh。

NPM 安装与使用（ESM）

npm install qsh-webview-sdk

import qsh from 'qsh-webview-sdk';

// 等待 SDK 就绪后再调用 API（内部也有自动等待机制）
qsh.ready().then(() => {
  qsh.navigateTo({ url: '/pages/test/test' });
});

初始化

浏览器环境下，SDK 会在 DOM 就绪后自动初始化，并触发 UniAppJSBridgeReady 事件。
SSR/Node 环境不会执行自动初始化；在客户端 Hydration 后会按上述规则自动初始化。
所有对外 API（如 navigateTo、postMessage、getEnv 等）内置自动等待机制：即使在未就绪时调用，也会在就绪后自动执行，无需手动监听事件。
仍可使用 qsh.ready() 等待准备完成；如需“控制初始化时机”，可手动调用 qsh.init()。该方法是幂等的，多次调用仅首次生效。

注：当检测到运行于微信内且为小程序 web-view 场景时，SDK 将自动按需注入 jweixin-1.6.2.js（若页面已引入则不会重复注入）。若你需要自定义版本或自行控制加载时机，可在页面提前引入 jweixin，SDK 将跳过自动注入。

基础使用

// 直接调用，无需等待（内部会自动等待就绪）
qsh.navigateTo({ url: '/pages/detail/detail?id=1' });

// 如需在 UI 上显示“就绪状态”，可以使用 ready()
qsh.ready().then(() => {
  console.log('SDK 已准备就绪');
});

导航功能

// 跳转到新页面
qsh.navigateTo({
  url: '/pages/detail/detail?id=1'
});

// 返回上一页
qsh.navigateBack({
  delta: 1
});

// 切换 Tab
qsh.switchTab({
  url: '/pages/home/home'
});

// 重启应用
qsh.reLaunch({
  url: '/pages/index/index'
});

// 重定向
qsh.redirectTo({
  url: '/pages/login/login'
});

消息通信

// 发送消息到原生端
qsh.postMessage({
  data: {
    action: 'share',
    title: '分享标题',
    content: '分享内容'
  }
});

// 获取环境信息
qsh.getEnv(function(result) {
  console.log('环境信息:', result);
  // result: { miniprogram: true, weixin: true }
  // 或 { app: true, plus: true } 或 { h5: true }
});

环境检测

// 获取当前环境信息
const env = qsh.environment;

console.log('环境类型:', env.type); // 'weixin' | 'plus' | 'nvue' | 'uvue' | 'UniApp' | 'h5'
console.log('是否微信小程序:', env.isWeixinMiniProgram);
console.log('是否 APP:', env.isAppPlus);

API 文档

导航 API

| 方法 | 说明 | 参数 | |------|------|------| | navigateTo | 保留当前页面，跳转到应用内的某个页面 | { url: string } | | navigateBack | 关闭当前页面，返回上一页面或多级页面 | { delta?: number } | | switchTab | 跳转到 tabBar 页面 | { url: string } | | reLaunch | 关闭所有页面，打开到应用内的某个页面 | { url: string } | | redirectTo | 关闭当前页面，跳转到应用内的某个页面 | { url: string } |

消息 API

| 方法 | 说明 | 参数 | |------|------|------| | postMessage | 向原生端发送消息 | { data?: any } | | getEnv | 获取当前环境信息 | callback: Function |

图片 API

| 方法 | 说明 | 参数 | |------|------|------| | chooseImage | 选择图片（自动环境适配） | { count?: number; sizeType?: string[]; sourceType?: string[]; success?: Function; fail?: Function; complete?: Function } | | chooseImageAsync | 选择图片（Promise 版） | { count?: number; sizeType?: string[]; sourceType?: string[] } |

扫码 API

| 方法 | 说明 | 参数 | |------|------|------| | scanCode | 扫码（自动环境适配） | { onlyFromCamera?: boolean; scanType?: string[]; success?: Function; fail?: Function; complete?: Function } | | scanCodeAsync | 扫码（Promise 版） | { onlyFromCamera?: boolean; scanType?: string[] } |

位置 API

| 方法 | 说明 | 参数 | |------|------|------| | getLocation | 获取当前位置 | { type?: string; altitude?: boolean; success?: Function; fail?: Function } | | getLocationAsync | 获取位置（Promise 版） | { type?: string; altitude?: boolean } | | openLocation | 查看位置（打开地图） | { latitude: number; longitude: number; name?: string; address?: string; scale?: number; success?: Function; fail?: Function } | | openLocationAsync | 查看位置（Promise 版） | { latitude: number; longitude: number; name?: string; address?: string; scale?: number } | | startLocationUpdate | 开启前台持续定位（仅 APP） | { type?: string; needFullAccuracy?: boolean; success?: Function; fail?: Function } | | stopLocationUpdate | 停止前台持续定位（仅 APP） | { success?: Function; fail?: Function } | | onLocationChange | 监听实时位置变化（仅 APP） | callback: Function | | offLocationChange | 取消监听位置变化（仅 APP） | callback?: Function | | onLocationChangeError | 监听位置更新错误（仅 APP） | callback: Function | | offLocationChangeError | 取消监听位置更新错误（仅 APP） | callback?: Function |

实现原理

微信小程序侧
- 自动按需加载并配置 jweixin，等待 qsh.weixin.isConfigReady() 为 true 后，SDK 内部调用 wx.chooseImage(options)；开发者统一调用 qsh.chooseImage(options)。
- 透传 count/sizeType/sourceType，回调结果遵循微信规范：res.localIds。
UniApp 侧（APP/NVUE/UVUE/H5+）
- WebView 通过桥接向宿主发送 chooseImage 指令：内部使用 callApiInWebView('chooseImage', params)。
- 宿主侧调用 uni.chooseImage 并将结果回传给 H5 页面；结果包含 res.tempFilePaths、res.tempFiles。
调用时机与等待
- 所有 API 内置 qsh.ready() 等待机制，即使在未就绪时调用也会在 Bridge 就绪后自动执行。
- 微信侧还会在配置完成后再调用；配置失败将进入 fail 回调。

返回结果差异

微信：res.localIds: string[]
UniApp：res.tempFilePaths: string[], res.tempFiles: Array<{ path: string, size: number }>

使用示例

回调版

qsh.chooseImage({
  count: 1,
  sizeType: ['compressed'],
  sourceType: ['album', 'camera'],
  success(res) {
    // 微信：res.localIds
    // UniApp：res.tempFilePaths / res.tempFiles
  },
  fail(err) {
    console.error(err);
  }
});

Promise 版

try {
  const res = await qsh.chooseImageAsync({ count: 1 });
  // 处理 res
} catch (e) {
  console.error(e);
}

常量辅助

qsh.chooseImage({
  sizeType: [qsh.ImageSizeTypes.COMPRESSED],
  sourceType: [qsh.ImageSourceTypes.ALBUM]
});

环境属性

| 属性 | 类型 | 说明 | |------|------|------| | environment.type | string | 环境类型 | | environment.isWeixinMiniProgram | boolean | 是否微信小程序 | | environment.isAppPlus | boolean | 是否 APP Plus | | environment.isNvue | boolean | 是否 NVUE | | environment.isUvue | boolean | 是否 UVUE | | environment.isUniApp | boolean | 是否 UniApp | | environment.isHtml5Plus | boolean | 是否 Html5Plus |

开发

安装依赖

npm install

开发模式

npm run dev

构建

npm run build

本地调试

Vue3 演示系统（推荐）

使用完整的 Vue3 演示系统进行调试和测试：

npm run play
# 或
npm run play:vue3

访问：http://localhost:5173

功能：

11 个功能演示页面
完整的交互界面
实时日志记录
移动端适配

说明：vue3-playground/vite.config.js 已将包名 qsh-webview-sdk 定位到仓库 src/index.js，用于直接联调当前源码。

其他命令

# 生产构建
npm run build:vue3

# 预览构建
npm run preview:vue3

项目结构

src/
├── core/                   # 核心模块
│   ├── environment.js      # 环境检测
│   ├── bridge.js           # 桥接初始化
│   ├── messenger.js        # 消息通信
│   ├── plugin-manager.js   # 插件管理器
│   ├── interceptor.js      # 拦截器链
│   ├── state-store.js      # 状态仓库
│   ├── error-codes.js      # 错误码定义
│   ├── error-normalizer.js # 错误标准化
│   └── ...
├── platforms/              # 平台适配
│   ├── weixin.js           # 微信小程序
│   └── app.js              # APP 端
├── api/                    # API 接口
│   ├── image.js            # 图片 API
│   ├── scan.js             # 扫码 API
│   ├── location.js         # 位置 API
│   ├── navigation.js       # 导航 API
│   └── message.js          # 消息 API
├── index.js                # 主入口
└── index.d.ts              # 类型定义

vue3-playground/            # Vue3 演示系统（功能完整）
├── src/
│   ├── router/             # 路由配置
│   ├── views/              # 11 个演示页面
│   ├── components/         # 公共组件
│   └── composables/        # 组合式函数
└── ...

uni-playground/             # UniApp 宿主端（用于真机测试）
references/                 # 开发参考（如原版 uni.webview.1.5.6.js）

开发计划（Roadmap）

以下为近期需要支持的功能清单，按平台划分（未勾选表示待实现）。

小程序（web-view）

[x] 扫码 ✅
[x] 获取位置 ✅
[x] 查看位置 ✅
[x] 照片选择 ✅
[ ] 相机
[ ] 打开地图选择位置
[ ] 人脸核身

APP（UniApp/Plus/NVUE/UVUE）

[x] 扫码 ✅
[x] 获取位置 ✅
[x] 查看位置 ✅
[x] 照片选择 ✅
[x] 持续定位 ✅
[ ] 相机
[ ] 蓝牙
[ ] WiFi
[ ] 微信分享
[x] 照片选择 ✅
[ ] 文件选择
[ ] 打开地图选择位置
[ ] 人脸核身
[ ] 打印服务

扫码功能

基础使用

// 回调方式
qsh.scanCode({
  success: (res) => {
    console.log('扫码结果:', res.result);
    console.log('扫码类型:', res.scanType);
  },
  fail: (err) => {
    if (err.code === qsh.errors.codes.SCAN_CANCELLED) {
      console.log('用户取消扫码');
    } else {
      console.error('扫码失败:', err);
    }
  }
});

// Promise 版本
try {
  const result = await qsh.scanCodeAsync({
    scanType: ['qrCode']
  });
  console.log('扫码结果:', result.result);
} catch (error) {
  console.error('扫码失败:', error);
}

参数说明

qsh.scanCode({
  onlyFromCamera: true,              // 只从相机扫码（默认 true）
  scanType: ['qrCode', 'barCode'],   // 扫码类型
  success: (res) => {
    // res.result - 扫码内容
    // res.scanType - 扫码类型
    // res.charSet - 字符集（仅 APP/微信）
  }
});

扫码类型

| 类型 | 说明 | 常量 | |------|------|------| | qrCode | 二维码 | qsh.ScanTypes.QR_CODE | | barCode | 一维码（条形码） | qsh.ScanTypes.BAR_CODE | | datamatrix | Data Matrix 码 | qsh.ScanTypes.DATA_MATRIX | | pdf417 | PDF417 条码 | qsh.ScanTypes.PDF417 |

平台差异

微信小程序：调用 wx.scanQRCode，自动配置
APP 端：调用 uni.scanCode，通过 WebView 桥接
返回格式：两端已统一为 { result, scanType, charSet }

参考文档：UniApp scanCode API

位置功能

获取当前位置

// 回调方式
qsh.getLocation({
  type: 'wgs84',  // 坐标类型：wgs84（GPS）, gcj02（国测局）, bd09（百度）
  altitude: false, // 是否返回高度信息
  success: (res) => {
    console.log('纬度:', res.latitude);
    console.log('经度:', res.longitude);
    console.log('精度:', res.accuracy);
    console.log('速度:', res.speed);
  },
  fail: (error) => {
    if (error.code === qsh.errors.codes.LOCATION_NO_PERMISSION) {
      console.log('无定位权限');
    }
  }
});

// Promise 版本
try {
  const location = await qsh.getLocationAsync({
    type: 'gcj02',
    altitude: true
  });
  console.log('位置:', location.latitude, location.longitude);
} catch (error) {
  console.error('定位失败:', error);
}

查看位置（打开地图）

// 打开地图查看指定位置
qsh.openLocation({
  latitude: 39.908823,
  longitude: 116.397470,
  name: '天安门',
  address: '北京市东城区东长安街',
  scale: 15,  // 缩放级别 1-28
  success: () => {
    console.log('地图已打开');
  }
});

// Promise 版本
await qsh.openLocationAsync({
  latitude: 39.908823,
  longitude: 116.397470,
  name: '天安门'
});

坐标类型

| 类型 | 说明 | 常量 | |------|------|------| | wgs84 | GPS 坐标 | qsh.CoordinateTypes.WGS84 | | gcj02 | 国测局坐标（火星坐标） | qsh.CoordinateTypes.GCJ02 | | bd09 | 百度坐标 | qsh.CoordinateTypes.BD09 |

平台差异

微信小程序：调用 wx.getLocation / wx.openLocation
APP 端：调用 uni.getLocation / uni.openLocation（通过 WebView 桥接）
返回格式：已统一

参考文档：UniApp getLocation

持续定位（仅 APP）

// 1. 开启前台持续定位服务
qsh.startLocationUpdate({
  type: 'wgs84',           // 坐标类型
  needFullAccuracy: true,  // 是否需要高精度
  success: () => console.log('定位服务已开启'),
  fail: (err) => console.error('开启失败:', err)
});

// 2. 监听位置变化
qsh.onLocationChange((res) => {
  console.log('位置:', res.latitude, res.longitude);
  console.log('精度:', res.accuracy, '米');
});

// 3. 监听定位错误（可选）
qsh.onLocationChangeError((err) => {
  console.error('定位出错:', err);
});

// 4. 停止监听
qsh.offLocationChange();
qsh.offLocationChangeError();

// 5. 停止定位服务
qsh.stopLocationUpdate({
  success: () => console.log('定位服务已停止')
});

相机功能

// 相机拍照（小程序/APP）
qsh.takePhoto({
  quality: 'high', // 图片质量：low, normal, high
  sizeType: 'compressed', // 图片尺寸：original, compressed
  success: (res) => {
    console.log('照片路径:', res.tempImagePath);
  },
  fail: (err) => console.error(err)
});

蓝牙功能（仅 APP）

// 初始化蓝牙
qsh.openBluetoothAdapter({
  success: () => console.log('蓝牙初始化成功'),
  fail: (err) => console.error('蓝牙初始化失败:', err)
});

// 开始搜索设备
qsh.startBluetoothDevicesDiscovery({
  services: ['0000FFE0-0000-1000-8000-00805F9B34FB'],
  success: () => console.log('开始搜索设备'),
  fail: (err) => console.error('搜索失败:', err)
});

// 监听设备发现
qsh.onBluetoothDeviceFound((devices) => {
  console.log('发现设备:', devices);
});

// 连接设备
qsh.createBLEConnection({
  deviceId: 'device-id',
  success: () => console.log('连接成功'),
  fail: (err) => console.error('连接失败:', err)
});

WiFi 功能（仅 APP）

// 获取 WiFi 信息
qsh.getWifiInfo({
  success: (res) => {
    console.log('WiFi SSID:', res.wifi.SSID);
    console.log('WiFi BSSID:', res.wifi.BSSID);
  },
  fail: (err) => console.error(err)
});

// 连接 WiFi
qsh.connectWifi({
  SSID: 'wifi-name',
  password: 'wifi-password',
  success: () => console.log('连接成功'),
  fail: (err) => console.error('连接失败:', err)
});

微信分享（仅 APP）

// 分享到微信
qsh.shareToWeixin({
  type: 'webpage', // 分享类型：text, image, webpage, music, video
  title: '分享标题',
  description: '分享描述',
  webpageUrl: 'https://example.com',
  imageUrl: 'https://example.com/image.jpg',
  success: () => console.log('分享成功'),
  fail: (err) => console.error('分享失败:', err)
});

文件选择（仅 APP）

// 选择文件
qsh.chooseFile({
  type: 'all', // 文件类型：all, image, video, audio, file
  count: 1,
  success: (res) => {
    console.log('文件路径:', res.tempFilePaths);
    console.log('文件信息:', res.tempFiles);
  },
  fail: (err) => console.error(err)
});

地图选择位置

// 打开地图选择位置（小程序/APP）
qsh.chooseLocation({
  latitude: 39.908823, // 初始纬度
  longitude: 116.397470, // 初始经度
  success: (res) => {
    console.log('选择位置:', res.name);
    console.log('地址:', res.address);
    console.log('纬度:', res.latitude);
    console.log('经度:', res.longitude);
  },
  fail: (err) => console.error(err)
});

人脸核身

// 人脸核身（小程序/APP）
qsh.faceVerify({
  verifyType: 'idcard', // 核身类型：idcard, bankcard, driver
  idCard: '身份证号',
  name: '姓名',
  success: (res) => {
    console.log('核身结果:', res.verifyResult);
    console.log('核身分数:', res.score);
  },
  fail: (err) => console.error(err)
});

打印服务（仅 APP）

// 打印文本
qsh.printText({
  content: '打印内容',
  printerName: '打印机名称',
  success: () => console.log('打印成功'),
  fail: (err) => console.error('打印失败:', err)
});

// 打印图片
qsh.printImage({
  imagePath: '/path/to/image.jpg',
  printerName: '打印机名称',
  success: () => console.log('打印成功'),
  fail: (err) => console.error('打印失败:', err)
});

兼容性

微信小程序 WebView
UniApp APP 端 (Android/iOS)
H5+ 环境
NVUE 页面
UVUE 页面 (UniApp X)

License

MIT

CommonJS/Require 使用

// 安装：npm install qsh-webview-sdk
const qsh = require('qsh-webview-sdk');

qsh.ready().then(() => {
  qsh.postMessage({ data: { action: 'init' } });
});

在框架中使用

以下示例均利用 qsh.ready() 确保就绪；注意 SDK 自带自动等待，直接调用 API 也可正常执行。

Vue 3

<script setup>
import { onMounted } from 'vue';
import qsh from 'qsh-webview-sdk';

onMounted(async () => {
  await qsh.ready();
  qsh.navigateTo({ url: '/pages/demo/index' });
});
</script>

React

import { useEffect } from 'react';
import qsh from 'qsh-webview-sdk';

export default function App() {
  useEffect(() => {
    let cancelled = false;
    qsh.ready().then(() => {
      if (!cancelled) {
        qsh.postMessage({ data: { action: 'mounted' } });
      }
    });
    return () => { cancelled = true; };
  }, []);
  return null;
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

QSH WebView SDK

特性

安装

NPM 安装

CDN 引入

使用方法

在 HTML 中引入

NPM 安装与使用（ESM）

初始化

基础使用

导航功能

消息通信

环境检测

API 文档

导航 API

消息 API

图片 API

扫码 API

位置 API

实现原理

返回结果差异

使用示例

环境属性

开发

安装依赖

开发模式

构建

本地调试

Vue3 演示系统（推荐）

其他命令

项目结构

开发计划（Roadmap）

小程序（web-view）

APP（UniApp/Plus/NVUE/UVUE）

扫码功能

基础使用

参数说明

扫码类型

平台差异

位置功能

获取当前位置

查看位置（打开地图）

坐标类型

平台差异

持续定位（仅 APP）

相机功能

蓝牙功能（仅 APP）

WiFi 功能（仅 APP）

微信分享（仅 APP）

文件选择（仅 APP）

地图选择位置

人脸核身

打印服务（仅 APP）

兼容性

License

CommonJS/Require 使用

在框架中使用