@spopc/wechat-miniprogram 0.1.1 → 0.2.0

package/README.md

@@ -8,19 +8,19 @@ H5 调用微信小程序原生能力的 TypeScript SDK。使用 URL 协议和一
 npm install @spopc/wechat-miniprogram
 ```
 
-包提供 ESM 和 TypeScript 类型声明，供浏览器 H5 项目使用；在客户端创建实例，SSR 项目需放在挂载后的客户端代码中。普通浏览器可直接使用 mock，真实微信能力还需要小程序宿主实现本文的 URL 协议。仅安装 H5 SDK 不会自动添加原生小程序页面。
+包提供 ESM 和 TypeScript 类型声明，供浏览器 H5 项目使用；在客户端创建实例，SSR 项目需放在挂载后的客户端代码中。普通浏览器使用真实 Web 能力；微信能力需要小程序宿主实现本文的 URL 协议。仅安装 H5 SDK 不会自动添加原生小程序页面。
 
 源码仓库内使用 npm workspace 开发，无需先发布到 npm。
 
 ## 快速接入
 
-默认自动识别环境：小程序 WebView 使用原生桥接，普通浏览器使用 mock。真实小程序调用需要网页加载微信 JSSDK：`https://res.wx.qq.com/open/js/jweixin-1.6.0.js`；浏览器 mock 无需加载它。每个页面创建一个 SDK 实例。
+从 0.2.0 起，默认自动识别环境：小程序 WebView 使用原生桥接，普通浏览器使用真实浏览器 API，不再自动 mock。需要旧的模拟行为时显式设置 `mode: 'mock'`。真实小程序调用需要网页加载微信 JSSDK：`https://res.wx.qq.com/open/js/jweixin-1.6.0.js`；浏览器模式不需要它。每个页面创建一个 SDK 实例。
 
 ```ts
 import { createWechatBridge } from '@spopc/wechat-miniprogram'
 
 const bridge = createWechatBridge({
-  mode: 'auto', // 默认值；也可强制 'native' 或 'mock'
+  mode: 'auto', // 默认值；也可强制 'native'、'browser' 或 'mock'
   onResult({ result, delivery, source }) {
     // 唯一业务结果入口：live 与文档重建后的 recovered 都经过这里。
     // 若同时消费 Promise，请避免对同一调用重复执行业务副作用。
@@ -30,25 +30,63 @@ const bridge = createWechatBridge({
 
 // 由 H5 上的用户操作触发；原生页自动执行，无需再点“执行”和“返回”。
 const scan = await bridge.scanCode({ scanType: ['qrCode', 'barCode'] })
-const position = await bridge.getLocation({ type: 'gcj02' })
-const { code } = await bridge.login()
-// 将 code 提交给自己的业务后端，换取业务登录态；不要把 AppSecret 放在 H5。
+const position = await bridge.getLocation()
+// position.type 明确标识坐标系：浏览器默认 WGS84，小程序默认 GCJ-02。
+if (await bridge.ready() === 'native') {
+  const { code } = await bridge.login()
+  // 将 code 提交给业务后端；不要把 AppSecret 放在 H5。
+}
 ```
 
 上述调用是顺序示例；根据实际按钮分别触发。页面卸载 / 组件卸载时调用 `bridge.dispose()`。它移除监听并拒绝当前 Promise，原生模式保留请求记录以支持文档重建。
 
-## 自动识别与 Mock
+## 自动识别
 
 ```ts
 const bridge = createWechatBridge() // 等同于 { mode: 'auto' }
-const environment = await bridge.ready() // 'native' | 'mock'
+const environment = await bridge.ready() // 'native' | 'browser' | 'mock'
 console.log(bridge.environment, bridge.isMock)
 const location = await bridge.getLocation() // 调用本身也会等待识别，无需手动 ready
 ```
 
-`auto` 结合小程序标记、User-Agent、`wx.miniProgram.getEnv` 和 `WeixinJSBridgeReady` 识别。普通浏览器直接使用 mock，即使网页加载了微信 JSSDK 也不会被误判为小程序。微信容器仍在初始化时，默认最多等待 2000 ms；可用 `environmentTimeoutMs` 调整为 100–30000 ms。无法确认时抛出 `ENVIRONMENT_TIMEOUT`，加载完成后可重试 `ready()` / 调用，不把未知环境当成模拟成功。
+`auto` 结合小程序标记、User-Agent、`wx.miniProgram.getEnv` 和 `WeixinJSBridgeReady` 识别。普通浏览器使用 browser，即使网页加载了微信 JSSDK 也不会被误判为小程序。微信容器仍在初始化时，默认最多等待 2000 ms；可用 `environmentTimeoutMs` 调整为 100–30000 ms。无法确认时抛出 `ENVIRONMENT_TIMEOUT`，加载完成后可重试 `ready()` / 调用，不把未知环境当成模拟成功。
+
+自动识别完成后，本实例固定使用选定模式。真实调用的权限拒绝、导航失败、超时等不会退回 mock。已识别为小程序但缺少 JSSDK 时抛出 `JSSDK_NOT_READY`。`mode: 'native'` 强制小程序调用，在普通浏览器报 `NOT_IN_MINIPROGRAM`；`mode: 'browser'` 强制 Web API；`mode: 'mock'` 强制模拟。`isInMiniProgram()` 检测实际环境，不会因强制模式返回假值。检测未完成时 `environment` 为 undefined，应等待 `ready()`。
+
+## 浏览器真实能力
+
+| 能力 | 默认浏览器实现 |
+| --- | --- |
+| getLocation | 请求定位权限，使用 Geolocation 获取 WGS84 真实坐标；成功、超时或销毁时停止监听 |
+| scanCode | 弹出扫码窗口，摄像头或本地图片识别；`onlyFromCamera` 隐藏选图；支持二维码、常见条码、Data Matrix、PDF417 |
+| openLocation | 在新窗口打开高德地图网页，支持显式 type: wgs84 / gcj02，默认 gcj02 |
+| makePhoneCall | 发起 tel: 系统拨号请求 |
+| login / checkSession / chooseAddress / requestPayment | 返回 UNSUPPORTED；可以接入自己的业务处理器 |
+
+定位和扫码要求 HTTPS 或 localhost。浏览器地理坐标采用 [WGS84](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates)，默认 `getLocation()` 返回 `type: 'wgs84'`；显式要求 gcj02 会返回 `UNSUPPORTED_COORDINATE_SYSTEM`，不会把 WGS84 假标成 GCJ-02。需要转换时通过业务适配器接入地图服务。小程序定位默认值保持 gcj02。
+
+地图使用[高德 URI API](https://lbs.amap.com/api/uri-api/gettingstarted)。把浏览器定位用于地图时传入 `type: position.type`，地图会处理对应坐标；微信地图仅接受 GCJ-02。浏览器地图暂不使用 scale，地图和 tel: 的 `{ ok: true }` 仅代表已发起打开请求，不代表地图已加载或电话已接通。应由用户点击触发；无用户操作或窗口被拦截时返回 `USER_GESTURE_REQUIRED` / `POPUP_BLOCKED`。
+
+扫码使用本地 canvas 与按需加载的 `@zxing/library` 解码，不上传摄像头画面或图片。图片上限 20 MB。用户可点击取消或按 Escape；成功、取消、超时、销毁后会停止摄像头并移除窗口，即使权限响应迟到也会释放媒体流。浏览器模式的 `source` / `trigger` 为 browser、`delivery` 为 live，不消费 URL 或原生 pending 记录，也不模拟 Query 重载。
+
+业务适配器具有类型关联，并收到可响应超时/销毁的 signal。例如选择业务收货地址：
+
+```ts
+const bridge = createWechatBridge({
+  browser: {
+    handlers: {
+      chooseAddress: async (_params, { signal }) => {
+        // 应用实现此函数，返回 AddressData；取消可抛 BridgeError('CANCELLED', '用户取消')。
+        return await openYourAddressPicker({ signal })
+      }
+    }
+  }
+})
+```
+
+仅配置 mock.handlers 不会启用模拟。浏览器登录处理器不能凭空产生有效的微信小程序 code；H5 登录与支付需接入业务后端和相应平台流程。自定义处理器仍遵守现有参数与结果类型，不能用业务 token 冒充微信 code。
 
-自动识别完成后，本实例固定使用选定模式。真实调用的权限拒绝、导航失败、超时等不会退回 mock。已识别为小程序但缺少 JSSDK 时抛出 `JSSDK_NOT_READY`。`mode: 'native'` 可以强制真实调用，浏览器中会报 `NOT_IN_MINIPROGRAM`；`mode: 'mock'` 可以在任何环境强制模拟。`isInMiniProgram()` 检测实际环境，不会因强制 mock 返回假值。检测未完成时 `environment` 为 undefined，应等待 `ready()` 再读取 `isMock`。
+## 显式 Mock
 
 8 项能力均内置成功数据：固定模拟坐标、门店码、无效的 MOCK 登录 code、虚构地址及成功标记。可覆盖任意方法，其余保持默认：
 
@@ -56,7 +94,7 @@ const location = await bridge.getLocation() // 调用本身也会等待识别，
 import { createWechatBridge, BridgeError } from '@spopc/wechat-miniprogram'
 
 const bridge = createWechatBridge({
-  mode: 'auto',
+  mode: 'mock',
   mock: {
     delayMs: 500, // 默认 300；0–600000 ms，计入调用超时
     handlers: {
@@ -79,7 +117,7 @@ mock 与真实调用共用参数/结果校验、Promise 类型、单次并发限
 
 mock 的 `onResult.source`、`trigger` 均为 `mock`，`delivery` 固定为 `live`；只在当前内存中返回数据，不跳页面、不读写原生 pending 记录、不消费或修改 URL。即使传入调用参数 `mode: 'query'`，也不模拟重载，因此不能用来验证 WebView 的 Hash / Query 传输和文档重建。模拟登录 code 不能交给微信换登录态，模拟支付不会产生订单或真实支付；业务后端联调需配套测试数据。
 
-测试页直接打开 `http://127.0.0.1:13334/` 即自动进入 mock，可选成功/取消/失败。`?mode=native`、`?mode=mock` 强制模式，旧 `?mock=1` 也可用。这些 URL 开关只属于测试页面，SDK 本身不读取它们。
+测试页直接打开 `http://127.0.0.1:13334/` 自动使用浏览器能力。`?mode=browser`、`?mode=native`、`?mode=mock` 强制模式，mock 下可选成功/取消/失败，旧 `?mock=1` 仍可用。这些 URL 开关只属于测试页面，SDK 本身不读取它们。
 
 ## 方法与参数
 
@@ -87,11 +125,11 @@ mock 的 `onResult.source`、`trigger` 均为 `mock`，`delivery` 固定为 `liv
 
 | 方法 | 原生参数 | 成功结果 |
 | --- | --- | --- |
-| `getLocation(options?)` | type: gcj02（默认）或 wgs84 | latitude、longitude、accuracy、type |
+| `getLocation(options?)` | type: 小程序/mock 默认 gcj02；browser 默认且仅内置支持 wgs84 | latitude、longitude、accuracy、type |
 | `scanCode(options?)` | onlyFromCamera?: boolean；scanType?: qrCode / barCode / datamatrix / pdf417 数组 | result、scanType；可选 charSet、path、rawData |
 | `login(options?)` | timeout?: 1000–60000，微信接口自身超时 | code |
 | `checkSession(options?)` | 无 | valid: true |
-| `openLocation(options)` | GCJ-02 latitude、longitude；可选 name、address、scale（5–18） | ok: true |
+| `openLocation(options)` | latitude、longitude；type 默认 gcj02，浏览器也支持 wgs84；可选 name、address、scale（5–18） | ok: true |
 | `chooseAddress(options?)` | 无 | userName、telNumber、provinceName、cityName、countyName、detailInfo，以及平台返回的可选地址字段 |
 | `makePhoneCall(options)` | phoneNumber | ok: true |
 | `requestPayment(options)` | timeStamp、nonceStr、package、signType、paySign | ok: true |
@@ -118,8 +156,8 @@ await bridge.openLocation({ latitude: 31.2, longitude: 121.4, name: '门店', sc
     status: 'success', data // 或 status: 'cancel' | 'error', error: { code, message }
   },
   delivery: 'live', // 或 'recovered'
-  source: 'native', // 或 'mock'
-  trigger: 'hashchange' // 或 startup / pageshow / visible / mock
+  source: 'native', // 或 'browser' / 'mock'
+  trigger: 'hashchange' // 或 startup / pageshow / visible / browser / mock
 }
 ```
 
@@ -127,6 +165,8 @@ await bridge.openLocation({ latitude: 31.2, longitude: 121.4, name: '门店', sc
 
 常见错误：`CANCELLED`、`PERMISSION_DENIED`、`NATIVE_FAILED`、`SESSION_EXPIRED`、`UNSUPPORTED`、`TIMEOUT`、`RESULT_TOO_LARGE`、`INVALID_NATIVE_RESULT`。H5 侧还会产生 `BUSY`、`NOT_IN_MINIPROGRAM`、`ENVIRONMENT_TIMEOUT`、`JSSDK_NOT_READY`、`INVALID_PARAMS`、`STORAGE_UNAVAILABLE`、`NAVIGATE_FAILED`、`DISPOSED`、`MOCK_FAILED`、`INVALID_MOCK_RESULT`。微信错误原文保留在 message，不依赖它处理分支。H5 本地校验、环境识别、导航失败和本地等待超时通过 Promise 拒绝；它们没有原生回传，因此不产生 `onResult`。
 
+浏览器另外可能返回 `SECURE_CONTEXT_REQUIRED`、`UNSUPPORTED_COORDINATE_SYSTEM`、`POSITION_UNAVAILABLE`、`CAMERA_UNAVAILABLE`、`CODE_NOT_FOUND`、`SCAN_FAILED`、`USER_GESTURE_REQUIRED`、`POPUP_BLOCKED`、`BROWSER_FAILED`、`INVALID_BROWSER_RESULT`。权限被拒绝会保留为 `PERMISSION_DENIED`，不会自动降级到模拟。
+
 `checkSession` 仅检查微信 session_key，不验证业务服务自己的 token。`login` 不获取手机号、头像或昵称；手机号授权需要原生按钮交互，不属于本版静默桥接范围。
 
 ## 宿主契约与扩展
@@ -145,4 +185,4 @@ await bridge.openLocation({ latitude: 31.2, longitude: 121.4, name: '门店', sc
 
 2026-10-13，Windows 微信开发者工具 Stable 2.02.2608070 / 基础库 3.17.4：自动 login、getLocation、checkSession、scanCode 成功及扫码取消均完成往返，通过 Hash 在同一页面收到 live 结果。扫码使用开发者工具选择测试二维码图片，不代表真机相机扫描已测试。初版定位页另验证过 Query 重载与 recovered 恢复。iOS / Android 真机、真实支付、拨号、地图、个人地址尚未实测。
 
-构建：`npm run build`。打包检查：`npm pack --dry-run`。包只包含 dist、README 和 package.json。
+在源码仓库根目录构建：`npm run build:sdk`；打包检查：`npm run pack:sdk -- --dry-run`。这些命令会从 `sdks/wechat-miniprogram/VERSION` 同步版本，包只包含 dist、README 和 package.json。发布新版本时修改 VERSION 并推送到 main，CI 会检查、发布 npm 并同步 npmmirror。

package/dist/barcode.d.ts

@@ -0,0 +1,3 @@
+import type { ScanCodeParams, ScanCodeData } from './protocol.js';
+/** Loaded only when scanning starts; decoding is local and never uploads images. */
+export declare function createBarcodeDecoder(params: ScanCodeParams): Promise<(rgba: Uint8ClampedArray, width: number, height: number) => ScanCodeData | undefined>;

package/dist/barcode.js

@@ -0,0 +1,29 @@
+/** Loaded only when scanning starts; decoding is local and never uploads images. */
+export async function createBarcodeDecoder(params) {
+    const zxing = await import('@zxing/library');
+    const { BarcodeFormat: F, DecodeHintType, MultiFormatReader, RGBLuminanceSource, BinaryBitmap, HybridBinarizer } = zxing;
+    const groups = {
+        qrCode: [F.QR_CODE], datamatrix: [F.DATA_MATRIX], pdf417: [F.PDF_417],
+        barCode: [F.CODABAR, F.CODE_39, F.CODE_93, F.CODE_128, F.EAN_8, F.EAN_13, F.ITF, F.RSS_14, F.UPC_A, F.UPC_E],
+    };
+    const formats = (params.scanType ?? ['qrCode', 'barCode']).flatMap(type => groups[type]);
+    const reader = new MultiFormatReader();
+    reader.setHints(new Map([[DecodeHintType.POSSIBLE_FORMATS, formats]]));
+    return (rgba, width, height) => {
+        const pixels = new Int32Array(width * height);
+        for (let i = 0; i < pixels.length; i++)
+            pixels[i] = (rgba[i * 4] << 16) | (rgba[i * 4 + 1] << 8) | rgba[i * 4 + 2];
+        try {
+            const result = reader.decodeWithState(new BinaryBitmap(new HybridBinarizer(new RGBLuminanceSource(pixels, width, height))));
+            return { result: result.getText(), scanType: F[result.getBarcodeFormat()] };
+        }
+        catch (error) {
+            if (error instanceof zxing.NotFoundException || error instanceof zxing.ChecksumException || error instanceof zxing.FormatException)
+                return;
+            throw error;
+        }
+        finally {
+            reader.reset();
+        }
+    };
+}

package/dist/browser.d.ts

@@ -0,0 +1,16 @@
+import { type BridgeMethod, type BridgeRequest, type BridgeResult, type ParamsOf, type DataOf } from './protocol.js';
+export interface BrowserContext {
+    requestId: string;
+    /** Aborted on timeout, disposal, or completion. */
+    signal: AbortSignal;
+    expiresAt: number;
+}
+export type BrowserHandler<M extends BridgeMethod> = (params: ParamsOf<M>, context: BrowserContext) => DataOf<M> | Promise<DataOf<M>>;
+export type BrowserHandlers = {
+    [M in BridgeMethod]?: BrowserHandler<M>;
+};
+export interface BrowserOptions {
+    /** Explicit application integrations; no successful fixtures are supplied. */
+    handlers?: BrowserHandlers;
+}
+export declare function createBrowserTransport(browser: Window, options: BrowserOptions): (request: BridgeRequest, complete: (result: BridgeResult) => void) => (() => void);

package/dist/browser.js

@@ -0,0 +1,117 @@
+import { BridgeError } from './errors.js';
+import { scanInBrowser } from './scanner.js';
+import { BRIDGE_METHODS, parseResult } from './protocol.js';
+function location(browser, params, context) {
+    if (!browser.isSecureContext)
+        throw new BridgeError('SECURE_CONTEXT_REQUIRED', '浏览器定位需要 HTTPS 或 localhost');
+    if (!browser.navigator.geolocation)
+        throw new BridgeError('UNSUPPORTED', '此浏览器不支持定位');
+    if (params.type !== 'wgs84')
+        throw new BridgeError('UNSUPPORTED_COORDINATE_SYSTEM', '浏览器定位返回 WGS84，请使用 type: wgs84 或提供坐标转换适配器');
+    return new Promise((resolve, reject) => {
+        let watch;
+        let finished = false;
+        const cleanup = () => {
+            finished = true;
+            if (watch !== undefined)
+                browser.navigator.geolocation.clearWatch(watch);
+            context.signal.removeEventListener('abort', abort);
+        };
+        const abort = () => { cleanup(); reject(new BridgeError('CANCELLED', '定位已结束')); };
+        context.signal.addEventListener('abort', abort, { once: true });
+        if (context.signal.aborted) {
+            abort();
+            return;
+        }
+        try {
+            watch = browser.navigator.geolocation.watchPosition(position => {
+                if (finished)
+                    return;
+                cleanup();
+                resolve({ latitude: position.coords.latitude, longitude: position.coords.longitude, accuracy: position.coords.accuracy, type: 'wgs84' });
+            }, error => {
+                if (finished)
+                    return;
+                cleanup();
+                const code = error.code === 1 ? 'PERMISSION_DENIED' : error.code === 3 ? 'TIMEOUT' : 'POSITION_UNAVAILABLE';
+                reject(new BridgeError(code, error.message || '无法获取当前位置'));
+            }, { enableHighAccuracy: true, maximumAge: 0, timeout: Math.max(1, context.expiresAt - Date.now()) });
+            if (finished)
+                browser.navigator.geolocation.clearWatch(watch);
+        }
+        catch (error) {
+            cleanup();
+            reject(error);
+        }
+    });
+}
+function requireGesture(browser) {
+    if (browser.navigator.userActivation?.isActive === false)
+        throw new BridgeError('USER_GESTURE_REQUIRED', '请点击页面按钮后发起此操作');
+}
+export function createBrowserTransport(browser, options) {
+    const handlers = { ...options.handlers };
+    for (const [method, handler] of Object.entries(handlers)) {
+        if (!BRIDGE_METHODS.includes(method) || typeof handler !== 'function')
+            throw new BridgeError('INVALID_PARAMS', `Invalid browser handler: ${method}`);
+    }
+    const defaults = {
+        getLocation: (params, context) => location(browser, params, context),
+        scanCode: (params, context) => scanInBrowser(browser, params, context.signal),
+        openLocation: params => {
+            requireGesture(browser);
+            const url = new URL('https://uri.amap.com/marker');
+            url.search = new URLSearchParams({ position: `${params.longitude},${params.latitude}`, name: params.name ?? params.address ?? '门店位置', coordinate: params.type === 'wgs84' ? 'wgs84' : 'gaode', callnative: '0', src: 'wechat-miniprogram-sdk' }).toString();
+            const tab = browser.open('about:blank', '_blank');
+            if (!tab)
+                throw new BridgeError('POPUP_BLOCKED', '地图窗口被浏览器拦截，请允许弹出窗口后重试');
+            try {
+                tab.opener = null;
+                tab.location.replace(url.href);
+            }
+            catch (error) {
+                tab.close();
+                throw error;
+            }
+            return { ok: true }; // The map was handed off, not verified as loaded.
+        },
+        makePhoneCall: params => {
+            requireGesture(browser);
+            browser.location.assign(`tel:${params.phoneNumber.replace(/[ -]/g, '')}`);
+            return { ok: true }; // A tel: request is not evidence of a connected call.
+        },
+    };
+    return (request, complete) => {
+        const controller = new AbortController();
+        const envelope = { v: 1, id: request.id, method: request.method, mode: request.mode };
+        const failure = (code, message) => parseResult(JSON.stringify({ ...envelope, completedAt: Date.now(), status: code === 'CANCELLED' ? 'cancel' : 'error', error: { code: code.slice(0, 128), message: message.slice(0, 1024) } }));
+        // Defer only a microtask, preserving a button's transient user activation.
+        void Promise.resolve().then(async () => {
+            if (controller.signal.aborted)
+                return;
+            let result;
+            try {
+                const handler = (handlers[request.method] ?? defaults[request.method]);
+                if (!handler)
+                    throw new BridgeError('UNSUPPORTED', `浏览器不支持微信 ${request.method}，请通过 browser.handlers 接入业务实现`);
+                const data = await handler(request.params, { requestId: request.id, signal: controller.signal, expiresAt: request.expiresAt });
+                if (controller.signal.aborted)
+                    return;
+                try {
+                    result = parseResult(JSON.stringify({ ...envelope, completedAt: Date.now(), status: 'success', data }));
+                }
+                catch {
+                    result = failure('INVALID_BROWSER_RESULT', `Invalid browser result for ${request.method}`);
+                }
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    return;
+                result = failure(error instanceof BridgeError ? error.code : 'BROWSER_FAILED', error instanceof Error ? error.message : String(error));
+            }
+            if (!controller.signal.aborted)
+                complete(result);
+        });
+        return () => controller.abort();
+    };
+}

package/dist/index.d.ts

@@ -1,20 +1,23 @@
 import { type BridgeResult, type BridgeMethod, type ParamsOf, type DataOf, type ReturnMode } from './protocol.js';
 import { type MockOptions } from './mock.js';
+import { type BrowserOptions } from './browser.js';
 export * from './protocol.js';
 export { BridgeError } from './errors.js';
 export { defaultMockHandlers, type MockOptions, type MockHandlers, type MockHandler, type MockContext } from './mock.js';
-export type BridgeMode = 'auto' | 'native' | 'mock';
-export type BridgeEnvironment = 'native' | 'mock';
+export type { BrowserOptions, BrowserHandlers, BrowserHandler, BrowserContext } from './browser.js';
+export type BridgeMode = 'auto' | 'native' | 'browser' | 'mock';
+export type BridgeEnvironment = 'native' | 'browser' | 'mock';
 export interface ResultEvent {
     result: BridgeResult;
-    source: 'native' | 'mock';
+    source: BridgeEnvironment;
     delivery: 'live' | 'recovered';
     trigger: string;
 }
 export interface BridgeOptions {
-    /** Default: auto. WeChat mini-programs use native APIs; other browsers use mock. */
+    /** Default: auto. WeChat mini-programs use the native bridge; other browsers use Web APIs. */
     mode?: BridgeMode;
     mock?: MockOptions;
+    browser?: BrowserOptions;
     /** Maximum wait for an unfinished WeChat environment. Default: 2000 ms. */
     environmentTimeoutMs?: number;
     timeoutMs?: number;

package/dist/index.js

@@ -2,6 +2,7 @@ import { buildNativeUrl, readReturnUrl, normalizeParams, parseRequest, DEFAULT_T
 import { BridgeError } from './errors.js';
 import { createMockTransport } from './mock.js';
 import { detectMiniProgram } from './environment.js';
+import { createBrowserTransport } from './browser.js';
 export * from './protocol.js';
 export { BridgeError } from './errors.js';
 export { defaultMockHandlers } from './mock.js';
@@ -11,13 +12,14 @@ export function createWechatBridge(options = {}) {
     const browser = window;
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const mode = options.mode ?? 'auto';
-    if (!['auto', 'native', 'mock'].includes(mode))
+    if (!['auto', 'native', 'browser', 'mock'].includes(mode))
         throw new BridgeError('INVALID_PARAMS', 'Invalid SDK mode');
     const environmentTimeoutMs = options.environmentTimeoutMs ?? 2000;
     if (!Number.isFinite(environmentTimeoutMs) || environmentTimeoutMs < 100 || environmentTimeoutMs > 30000)
         throw new BridgeError('INVALID_PARAMS', 'environmentTimeoutMs must be between 100 and 30000');
     const simulate = createMockTransport(options.mock ?? {});
-    let mockTransport = mode === 'mock' ? simulate : undefined;
+    const web = createBrowserTransport(browser, options.browser ?? {});
+    let localTransport = mode === 'mock' ? simulate : mode === 'browser' ? web : undefined;
     let environment = mode === 'auto' ? undefined : mode;
     let readiness;
     let listening = false;
@@ -30,7 +32,7 @@ export function createWechatBridge(options = {}) {
     }
     catch { /* Consumer logging cannot break transport. */ } };
     function loadPending() {
-        if (mockTransport)
+        if (environment !== 'native')
             return;
         try {
             const value = JSON.parse(browser.sessionStorage.getItem(STORAGE_KEY) || 'null');
@@ -42,7 +44,7 @@ export function createWechatBridge(options = {}) {
             return undefined;
         }
     }
-    function removePending() { if (!mockTransport) {
+    function removePending() { if (environment === 'native') {
         try {
             browser.sessionStorage.removeItem(STORAGE_KEY);
         }
@@ -60,7 +62,7 @@ export function createWechatBridge(options = {}) {
     }
     function publish(result, delivery, trigger) {
         try {
-            options.onResult?.({ result, delivery, trigger, source: mockTransport ? 'mock' : 'native' });
+            options.onResult?.({ result, delivery, trigger, source: environment });
         }
         catch {
             diagnostic('onResult 回调抛出异常，SDK 已完成结果交付');
@@ -132,8 +134,8 @@ export function createWechatBridge(options = {}) {
             readiness = isInMiniProgram().then(inside => {
                 if (disposed)
                     throw new BridgeError('DISPOSED', 'SDK 已销毁');
-                environment = inside ? 'native' : 'mock';
-                mockTransport = inside ? undefined : simulate;
+                environment = inside ? 'native' : 'browser';
+                localTransport = inside ? undefined : web;
                 listen();
                 diagnostic(`运行环境：${environment}（自动识别）`);
                 return environment;
@@ -163,7 +165,7 @@ export function createWechatBridge(options = {}) {
         const duration = callOptions.timeoutMs ?? timeoutMs;
         const mode = callOptions.mode ?? 'hash';
         try {
-            nativeParams = normalizeParams(method, params);
+            nativeParams = normalizeParams(method, environment === 'browser' && method === 'getLocation' ? { ...params, type: params.type ?? 'wgs84' } : params);
             if (!Number.isFinite(duration) || duration < 1000 || duration > 600000)
                 throw new Error('timeoutMs must be between 1000 and 600000');
             if (mode !== 'hash' && mode !== 'query')
@@ -175,7 +177,7 @@ export function createWechatBridge(options = {}) {
         catch (error) {
             throw new BridgeError('INVALID_PARAMS', error instanceof Error ? error.message : String(error));
         }
-        if (!mockTransport) {
+        if (!localTransport) {
             launching = true;
             let inside = false;
             try {
@@ -194,12 +196,12 @@ export function createWechatBridge(options = {}) {
         const createdAt = Date.now();
         const request = parseRequest(JSON.stringify({
             v: 1, id: browser.crypto.randomUUID(), method, mode,
-            returnUrl: mockTransport ? browser.location.href : readReturnUrl(browser.location.href).cleanUrl, createdAt,
+            returnUrl: localTransport ? browser.location.href : readReturnUrl(browser.location.href).cleanUrl, createdAt,
             expiresAt: createdAt + duration, params: nativeParams
         }));
         // Validate the route before reserving storage, so invalid configuration cannot leave a BUSY slot.
-        const url = mockTransport ? undefined : buildNativeUrl(request, options.nativePath);
-        if (!mockTransport) {
+        const url = localTransport ? undefined : buildNativeUrl(request, options.nativePath);
+        if (!localTransport) {
             try {
                 browser.sessionStorage.setItem(STORAGE_KEY, JSON.stringify({ request, deadline: request.expiresAt }));
             }
@@ -208,10 +210,10 @@ export function createWechatBridge(options = {}) {
             }
         }
         return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => fail('TIMEOUT', mockTransport ? '等待模拟结果超时' : '等待原生页面回传超时'), duration);
+            const timer = setTimeout(() => fail('TIMEOUT', environment === 'mock' ? '等待模拟结果超时' : environment === 'browser' ? '等待浏览器能力结果超时' : '等待原生页面回传超时'), duration);
             active = { request, resolve, reject, timer };
-            if (mockTransport) {
-                active.cleanup = mockTransport(request, result => {
+            if (localTransport) {
+                active.cleanup = localTransport(request, result => {
                     const waiting = active;
                     if (!waiting || waiting.request.id !== request.id || disposed)
                         return;
@@ -222,9 +224,9 @@ export function createWechatBridge(options = {}) {
                         waiting.resolve(result.data);
                     else
                         waiting.reject(new BridgeError(result.error.code, result.error.message));
-                    publish(result, 'live', 'mock');
+                    publish(result, 'live', environment);
                 });
-                diagnostic(`模拟 ${method} · ${request.id}`);
+                diagnostic(`${environment === 'mock' ? '模拟' : '浏览器调用'} ${method} · ${request.id}`);
                 return;
             }
             diagnostic(`发起 ${method} · ${request.mode} · ${request.id}`);

package/dist/protocol.d.ts

@@ -23,6 +23,7 @@ export interface ScanCodeData {
 export interface OpenLocationParams {
     latitude: number;
     longitude: number;
+    type?: 'gcj02' | 'wgs84';
     name?: string;
     address?: string;
     scale?: number;

package/dist/protocol.js

@@ -48,7 +48,8 @@ export function normalizeParams(method, input) {
             keys(value, []);
             break;
         case 'openLocation':
-            keys(value, ['latitude', 'longitude', 'name', 'address', 'scale']);
+            keys(value, ['latitude', 'longitude', 'type', 'name', 'address', 'scale']);
+            requireValid(value.type === undefined || value.type === 'gcj02' || value.type === 'wgs84', 'Invalid coordinate type');
             requireValid(coordinate(value.latitude, 90) && coordinate(value.longitude, 180), 'Invalid coordinates');
             requireValid(['name', 'address'].every(key => value[key] === undefined || text(value[key], 512)), 'Invalid map label');
             requireValid(value.scale === undefined || (finite(value.scale) && value.scale >= 5 && value.scale <= 18), 'Invalid map scale');

package/dist/scanner.d.ts

@@ -0,0 +1,2 @@
+import type { ScanCodeParams, ScanCodeData } from './protocol.js';
+export declare function scanInBrowser(browser: Window, params: ScanCodeParams, signal: AbortSignal): Promise<ScanCodeData>;

package/dist/scanner.js

@@ -0,0 +1,175 @@
+import { BridgeError } from './errors.js';
+import { createBarcodeDecoder } from './barcode.js';
+export function scanInBrowser(browser, params, signal) {
+    if (!browser.isSecureContext)
+        throw new BridgeError('SECURE_CONTEXT_REQUIRED', '浏览器扫码需要 HTTPS 或 localhost');
+    const doc = browser.document;
+    const dialog = doc.createElement('dialog');
+    if (typeof dialog.showModal !== 'function')
+        throw new BridgeError('UNSUPPORTED', '浏览器不支持扫码窗口，请升级浏览器或提供扫码适配器');
+    return new Promise((resolve, reject) => {
+        let finished = false, busy = false;
+        let stream;
+        let timer;
+        let imageUrl;
+        let cancelImage;
+        const urls = browser.URL;
+        const previousFocus = doc.activeElement;
+        const title = doc.createElement('h2');
+        title.textContent = '扫描门店码';
+        const status = doc.createElement('p');
+        status.textContent = '选择摄像头或图片，识别过程在本机完成。';
+        status.setAttribute('role', 'status');
+        const video = doc.createElement('video');
+        video.muted = true;
+        video.playsInline = true;
+        video.hidden = true;
+        video.style.cssText = 'width:100%;max-height:45vh;object-fit:contain;background:#111;border-radius:12px';
+        const canvas = doc.createElement('canvas');
+        const camera = doc.createElement('button');
+        camera.type = 'button';
+        camera.textContent = '打开摄像头';
+        const file = doc.createElement('input');
+        file.type = 'file';
+        file.accept = 'image/*';
+        file.setAttribute('aria-label', '选择二维码或条码图片');
+        file.hidden = !!params.onlyFromCamera;
+        const cancel = doc.createElement('button');
+        cancel.type = 'button';
+        cancel.textContent = '取消扫码';
+        for (const button of [camera, cancel])
+            button.style.cssText = 'padding:12px 16px;margin:8px 8px 8px 0;border:1px solid #ccc;border-radius:8px;background:white;color:#171717;font:inherit;cursor:pointer';
+        file.style.cssText = 'display:block;max-width:100%;margin:12px 0;font:inherit';
+        // Inline display must not override the onlyFromCamera restriction.
+        if (params.onlyFromCamera)
+            file.style.display = 'none';
+        dialog.setAttribute('aria-label', '扫描门店码');
+        dialog.style.cssText = 'box-sizing:border-box;width:min(92vw,460px);max-height:90vh;overflow:auto;border:0;border-radius:16px;padding:24px;background:white;color:#171717;font:16px/1.5 system-ui;box-shadow:0 12px 80px #0006';
+        dialog.append(title, status, video, camera, file, cancel);
+        function stopStream(value) { value?.getTracks().forEach(track => track.stop()); }
+        function finish(data, error) {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            stopStream(stream);
+            video.pause();
+            video.srcObject = null;
+            cancelImage?.();
+            if (imageUrl)
+                urls.revokeObjectURL(imageUrl);
+            signal.removeEventListener('abort', aborted);
+            dialog.close();
+            dialog.remove();
+            if (previousFocus?.isConnected)
+                previousFocus.focus();
+            if (error)
+                reject(error);
+            else
+                resolve(data);
+        }
+        const aborted = () => finish(undefined, new BridgeError('CANCELLED', '扫码已取消'));
+        const failure = (error) => {
+            const name = error?.name;
+            finish(undefined, error instanceof BridgeError ? error : new BridgeError(name === 'NotAllowedError' || name === 'SecurityError' ? 'PERMISSION_DENIED' : name === 'NotFoundError' || name === 'NotReadableError' ? 'CAMERA_UNAVAILABLE' : 'SCAN_FAILED', error instanceof Error ? error.message : String(error)));
+        };
+        const setBusy = () => { busy = true; camera.disabled = true; file.disabled = true; };
+        function decodeFrame(source, width, height, decode) {
+            if (!width || !height)
+                return;
+            const ratio = Math.min(1, 1280 / Math.max(width, height));
+            canvas.width = Math.max(1, Math.round(width * ratio));
+            canvas.height = Math.max(1, Math.round(height * ratio));
+            const context = canvas.getContext('2d', { willReadFrequently: true });
+            if (!context)
+                throw new BridgeError('UNSUPPORTED', '此浏览器不支持图像解码');
+            context.drawImage(source, 0, 0, canvas.width, canvas.height);
+            return decode(context.getImageData(0, 0, canvas.width, canvas.height).data, canvas.width, canvas.height);
+        }
+        camera.addEventListener('click', () => {
+            if (busy || finished)
+                return;
+            setBusy();
+            status.textContent = '请允许摄像头权限，并将二维码或条码置于画面中。';
+            void (async () => {
+                if (!browser.navigator.mediaDevices?.getUserMedia)
+                    throw new BridgeError('UNSUPPORTED', '此浏览器不支持摄像头');
+                const decode = await createBarcodeDecoder(params);
+                if (finished)
+                    return;
+                const acquired = await browser.navigator.mediaDevices.getUserMedia({ audio: false, video: { facingMode: { ideal: 'environment' } } });
+                if (finished) {
+                    stopStream(acquired);
+                    return;
+                }
+                stream = acquired;
+                for (const track of stream.getTracks())
+                    track.addEventListener('ended', () => failure(new BridgeError('CAMERA_UNAVAILABLE', '摄像头已断开')), { once: true });
+                video.srcObject = stream;
+                video.hidden = false;
+                await video.play();
+                if (finished)
+                    return;
+                const scan = () => {
+                    if (finished)
+                        return;
+                    try {
+                        const result = decodeFrame(video, video.videoWidth, video.videoHeight, decode);
+                        if (result) {
+                            finish(result);
+                            return;
+                        }
+                        timer = setTimeout(scan, 150);
+                    }
+                    catch (error) {
+                        failure(error);
+                    }
+                };
+                scan();
+            })().catch(failure);
+        });
+        file.addEventListener('change', () => {
+            const selected = file.files?.[0];
+            if (busy || finished || !selected || params.onlyFromCamera)
+                return;
+            setBusy();
+            status.textContent = '正在识别图片…';
+            void (async () => {
+                if (selected.size > 20 * 1024 * 1024)
+                    throw new BridgeError('INVALID_PARAMS', '请选择不超过 20 MB 的图片');
+                const decode = await createBarcodeDecoder(params);
+                if (finished)
+                    return;
+                const image = doc.createElement('img');
+                await new Promise((done, failed) => {
+                    cancelImage = () => { image.onload = null; image.onerror = null; image.src = ''; failed(new BridgeError('CANCELLED', '扫码已取消')); };
+                    image.onload = () => { cancelImage = undefined; done(); };
+                    image.onerror = () => { cancelImage = undefined; failed(new BridgeError('SCAN_FAILED', '无法读取此图片')); };
+                    imageUrl = urls.createObjectURL(selected);
+                    image.src = imageUrl;
+                });
+                if (finished)
+                    return;
+                const result = decodeFrame(image, image.naturalWidth, image.naturalHeight, decode);
+                if (!result)
+                    throw new BridgeError('CODE_NOT_FOUND', '图片中未识别到指定类型的二维码或条码');
+                finish(result);
+            })().catch(failure);
+        });
+        cancel.addEventListener('click', aborted);
+        dialog.addEventListener('cancel', event => { event.preventDefault(); aborted(); });
+        signal.addEventListener('abort', aborted, { once: true });
+        if (signal.aborted) {
+            aborted();
+            return;
+        }
+        doc.body.append(dialog);
+        try {
+            dialog.showModal();
+            cancel.focus();
+        }
+        catch (error) {
+            failure(error);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spopc/wechat-miniprogram",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Web SDK for the WeChat Mini Program URL bridge",
   "repository": {
     "type": "git",
@@ -43,5 +43,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@zxing/library": "0.21.3"
   }
 }