qsh-webview-sdk 2.0.4 → 2.0.6

package/README.md

@@ -1,6 +1,6 @@
-# UniApp WebView SDK
+# QSH WebView SDK
 
-一个重构后的 UniApp WebView SDK，支持微信小程序和 APP 端的 WebView 与原生端通信。
+一个重构后的 QSH WebView SDK，支持微信小程序和 APP 端的 WebView 与原生端通信。
 
 ## 特性
 
@@ -22,7 +22,7 @@ npm install qsh-webview-sdk
 ### CDN 引入
 
 ```html
-<script src="path/to/uni-webview.umd.js"></script>
+<script src="path/to/qsh-webview-sdk.umd.js"></script>
 ```
 
 ## 使用方法
@@ -30,26 +30,43 @@ npm install qsh-webview-sdk
 ### 在 HTML 中引入
 
 ```html
-<!-- 微信小程序环境（可选）-->
-<script type="text/javascript">
-  if (/miniProgram/i.test(navigator.userAgent) && /micromessenger/i.test(navigator.userAgent)) {
-    document.write('<script src="https://res.wx.qq.com/open/js/jweixin-1.6.0.js"><\/script>');
-  }
-</script>
+<!-- 引入 QSH WebView SDK（内部会在微信内的小程序 web-view 环境自动注入 jweixin） -->
+<script type="text/javascript" src="path/to/qsh-webview-sdk.umd.js"></script>
+```
+
+> 说明：通过 UMD 方式引入后，默认在全局暴露 `window.qsh`。
 
-<!-- 引入 UniApp WebView SDK -->
-<script type="text/javascript" src="path/to/uni-webview.umd.js"></script>
+### NPM 安装与使用（ESM）
+
+```bash
+npm install qsh-webview-sdk
+```
+
+```javascript
+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 将跳过自动注入。
+
 ### 基础使用
 
 ```javascript
-// 等待 SDK 准备就绪
-document.addEventListener('UniAppJSBridgeReady', function() {
-  console.log('SDK 已准备就绪');
-});
+// 直接调用，无需等待（内部会自动等待就绪）
+qsh.navigateTo({ url: '/pages/detail/detail?id=1' });
 
-// 或使用 Promise
+// 如需在 UI 上显示“就绪状态”，可以使用 ready()
 qsh.ready().then(() => {
   console.log('SDK 已准备就绪');
 });
@@ -110,49 +127,12 @@ qsh.getEnv(function(result) {
 // 获取当前环境信息
 const env = qsh.environment;
 
-console.log('环境类型:', env.type); // 'weixin' | 'plus' | 'nvue' | 'uvue' | 'h5'
+console.log('环境类型:', env.type); // 'weixin' | 'plus' | 'nvue' | 'uvue' | 'UniApp' | 'h5'
 console.log('是否微信小程序:', env.isWeixinMiniProgram);
 console.log('是否 APP:', env.isAppPlus);
 ```
 
-### 加密能力（SM2/SM3/SM4）
-
-- 已内置并通过 `qsh.crypto` 暴露以下能力：`sm2`（密钥对/加解密/签名验签）、`sm3`（杂凑/HMAC）、`sm4`（对称加解密）。
-- 参考实现来源：[miniprogram-sm-crypto（GitHub）](https://github.com/wechat-miniprogram/sm-crypto)。
-
-#### ESM 使用
-
-```javascript
-import qsh from 'qsh-webview-sdk';
-
-// SM3 杂凑
-const hash = qsh.crypto.sm3Hash('abc');
-
-// SM2：生成密钥对 + 签名 + 验签（示例使用 DER 编码）
-const { publicKey, privateKey } = qsh.crypto.sm2GenerateKeyPair();
-const sig = qsh.crypto.sm2Sign('hello sm2', privateKey, { der: true });
-const ok = qsh.crypto.sm2Verify('hello sm2', sig, publicKey, { der: true });
-
-// SM4：默认 ECB + pkcs#7 填充
-const key = '0123456789abcdeffedcba9876543210';
-const cipher = qsh.crypto.sm4Encrypt('hello', key);
-const plain = qsh.crypto.sm4Decrypt(cipher, key);
-```
-
-#### UMD 使用
-
-```html
-<script src="path/to/uni-webview.umd.js"></script>
-<script>
-  // 直接通过全局 qsh 访问
-  const hash = window.qsh.crypto.sm3Hash('abc');
-</script>
-```
-
-提示：
-- SM2 默认使用 C1C3C2（cipherMode=1）。与其他工具互通时请确保模式一致。
-- SM4 支持 ECB/CBC 等模式；CBC 需提供 `iv`。
-- 如需数组输入/输出，可通过 `options.output = 'array'` 控制（与上游库一致）。
+<!-- 加密能力（SM2/SM3/SM4）已在 v2.1.0 起移除，如需相关能力请在业务侧引入专用加密库。 -->
 
 ## API 文档
 
@@ -173,6 +153,87 @@ const plain = qsh.crypto.sm4Decrypt(cipher, key);
 | `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 }` |
+
+#### 实现原理
+
+- 微信小程序侧
+  - 自动按需加载并配置 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 }>`
+
+#### 使用示例
+
+1) 回调版
+
+```javascript
+qsh.chooseImage({
+  count: 1,
+  sizeType: ['compressed'],
+  sourceType: ['album', 'camera'],
+  success(res) {
+    // 微信：res.localIds
+    // UniApp：res.tempFilePaths / res.tempFiles
+  },
+  fail(err) {
+    console.error(err);
+  }
+});
+```
+
+2) Promise 版
+
+```javascript
+try {
+  const res = await qsh.chooseImageAsync({ count: 1 });
+  // 处理 res
+} catch (e) {
+  console.error(e);
+}
+```
+
+3) 常量辅助
+
+```javascript
+qsh.chooseImage({
+  sizeType: [qsh.ImageSizeTypes.COMPRESSED],
+  sourceType: [qsh.ImageSourceTypes.ALBUM]
+});
+```
+
+<!-- 加密 API 已移除 -->
+
 ### 环境属性
 
 | 属性 | 类型 | 说明 |
@@ -183,6 +244,7 @@ const plain = qsh.crypto.sm4Decrypt(cipher, key);
 | `environment.isNvue` | `boolean` | 是否 NVUE |
 | `environment.isUvue` | `boolean` | 是否 UVUE |
 | `environment.isUniApp` | `boolean` | 是否 UniApp |
+| `environment.isHtml5Plus` | `boolean` | 是否 Html5Plus |
 
 ## 开发
 
@@ -204,32 +266,402 @@ npm run dev
 npm run build
 ```
 
-## 示例文件
+## 本地调试
+
+### Vue3 演示系统（推荐）
+
+使用完整的 Vue3 演示系统进行调试和测试：
+
+```bash
+npm run play
+# 或
+npm run play:vue3
+```
+
+访问：http://localhost:5173
+
+**功能**：
+- 11 个功能演示页面
+- 完整的交互界面
+- 实时日志记录
+- 移动端适配
+
+说明：`vue3-playground/vite.config.js` 已将包名 `qsh-webview-sdk` 定位到仓库 `src/index.js`，用于直接联调当前源码。
+
+### 其他命令
 
-项目包含以下示例文件：
+```bash
+# 生产构建
+npm run build:vue3
 
-- `example/test.html` - 完整的测试页面，包含所有功能演示
-- `example/simple.html` - 简单示例，展示基础用法
-- `example/npm-usage.html` - 以 ESModule 方式演示，包括加密能力示例
-- `test.html` - 快速测试页面
+# 预览构建
+npm run preview:vue3
+```
 
 ## 项目结构
 
 ```
 src/
-├── core/               # 核心模块
-│   ├── environment.js  # 环境检测
-│   ├── messenger.js    # 消息通信
-│   └── bridge.js       # 桥接初始化
-├── platforms/          # 平台适配
-│   ├── weixin.js       # 微信小程序
-│   └── app.js          # APP 端
-├── api/                # API 接口
-│   ├── navigation.js   # 导航 API
-│   └── message.js      # 消息 API
- │   └── crypto.js       # 加密 API（SM2/SM3/SM4）
-├── index.js            # 主入口
-└── index.d.ts          # 类型定义
+├── 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] 照片选择 ✅
+- [ ] 持续定位
+- [ ] 相机
+- [ ] 蓝牙
+- [ ] WiFi
+- [ ] 微信分享
+- [x] 照片选择 ✅
+- [ ] 文件选择
+- [ ] 打开地图选择位置
+- [ ] 人脸核身
+- [ ] 打印服务
+
+### 扫码功能
+
+#### 基础使用
+
+```javascript
+// 回调方式
+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);
+}
+```
+
+#### 参数说明
+
+```javascript
+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](https://uniapp.dcloud.net.cn/api/system/barcode.html#scancode)
+
+### 位置功能
+
+#### 获取当前位置
+
+```javascript
+// 回调方式
+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);
+}
+```
+
+#### 查看位置（打开地图）
+
+```javascript
+// 打开地图查看指定位置
+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](https://uniapp.dcloud.net.cn/api/location/location.html)
+
+#### 持续定位（仅 APP）
+```javascript
+// 开始持续定位
+qsh.startLocationUpdate({
+  type: 'wgs84',
+  altitude: false,
+  success: (res) => {
+    console.log('位置更新:', res);
+  }
+});
+
+// 停止持续定位
+qsh.stopLocationUpdate();
+```
+
+### 相机功能
+
+```javascript
+// 相机拍照（小程序/APP）
+qsh.takePhoto({
+  quality: 'high', // 图片质量：low, normal, high
+  sizeType: 'compressed', // 图片尺寸：original, compressed
+  success: (res) => {
+    console.log('照片路径:', res.tempImagePath);
+  },
+  fail: (err) => console.error(err)
+});
+```
+
+### 蓝牙功能（仅 APP）
+
+```javascript
+// 初始化蓝牙
+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）
+
+```javascript
+// 获取 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）
+
+```javascript
+// 分享到微信
+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）
+
+```javascript
+// 选择文件
+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)
+});
+```
+
+### 地图选择位置
+
+```javascript
+// 打开地图选择位置（小程序/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)
+});
+```
+
+### 人脸核身
+
+```javascript
+// 人脸核身（小程序/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）
+
+```javascript
+// 打印文本
+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)
+});
 ```
 
 ## 兼容性
@@ -244,25 +676,51 @@ src/
 
 MIT
 
-### NPM/ES Module 使用
+### CommonJS/Require 使用
 
 ```javascript
-// 安装
-npm install qsh-webview-sdk
-
-// 在项目中导入
-import qsh from 'qsh-webview-sdk';
+// 安装：npm install qsh-webview-sdk
+const qsh = require('qsh-webview-sdk');
 
-// 等待初始化完成
 qsh.ready().then(() => {
-  // 使用 SDK
-  qsh.navigateTo({
-    url: '/pages/test/test'
-  });
+  qsh.postMessage({ data: { action: 'init' } });
 });
+```
 
-// 或者手动初始化（如果需要控制初始化时机）
+### 在框架中使用
+
+以下示例均利用 `qsh.ready()` 确保就绪；注意 SDK 自带自动等待，直接调用 API 也可正常执行。
+
+1) Vue 3
+
+```javascript
+<script setup>
+import { onMounted } from 'vue';
 import qsh from 'qsh-webview-sdk';
-qsh.init(); // 手动初始化
+
+onMounted(async () => {
+  await qsh.ready();
+  qsh.navigateTo({ url: '/pages/demo/index' });
+});
+</script>
 ```
+
+2) React
+
+```javascript
+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;
+}
 ```