@gzbapp/sdk

GZB 客户端 Web 容器内的 JavaScript SDK，提供 Bridge 与 GZBIX-JSSDK（JSON-RPC） 层封装。业务侧最常用的是 src/jmrpc/index.ts 导出的 jmCallHandler 系列 与 JmRpc。

安装

yarn add @gzbapp/sdk

模块定位：jmrpc/index.ts

该文件实现 标准 GZBIX-JSSDK：在 getBridge() 之上走 JSON-RPC 2.0，由客户端统一入口处理（内部 METHOD_NAME 为 rpc）。

• GZB 主版本 ≥ 9：走 JmRpc.shared 的 JSON-RPC 调用。
• GZB 主版本低于 9：走 gzb8Callhandler 兼容分支（部分 jm.* 方法映射到 legacy / rpc()，少数方法在 8 上不可用，实现中会打日志并返回 null）。

从包根导入即可（src/sdk.ts 已 export * from './jmrpc'）：

import {
  JmRpc,
  jmCallHandler,
  jmCallHandlerCallback,
  jmCallHandlerLoop,
  jmAddListener,
  jmRemoveListener,
} from '@gzbapp/sdk'

JmRpc 单例

需要直接使用底层能力（自定义 method 字符串、或与非导出的 RPC 方法交互）时，可使用单例：

const rpc = JmRpc.shared

// 判断响应是否为 JSON-RPC error 形态
const res = await rpc.jmCallHandler<{ foo: string }, { bar: number }>('custom.method', { foo: 'x' })

类上主要成员：

| 成员 | 说明 | |------|------| | jmCallHandler(method, params?) | Promise 化的一次性调用，错误时 reject 携带 error | | jmCallHandlerCallback(method, params, cb) | 成功后在 cb 中拿到 result，仍用 Promise 表示完成/失败 | | jmCallHandlerLoop(method, params, cb) | 递归注册：适合模拟「多次回调」场景（非固定方法名的 listener） | | jmAddListener(method, cb) | 注册原生侧推送；返回 () => void 用于取消 | | jmRemoveListener(method, cb) | 按回调引用移除（需与注册时同一函数引用） | | isError(res) | 类型守卫：判断 JSONRPCResponse 是否为 error |

jmCallHandler（推荐业务入口）

与类方法行为一致，但内置 GZB8/GZB9 分支（见源码中 checkMainGZBVersion(9)），一般业务应使用导出的 jmCallHandler，而不是直接 new JmRpc。

设置标题

import { jmCallHandler } from '@gzbapp/sdk'

await jmCallHandler('jm.setTitle', {
  title: '设置标题',
  hide: false,
  backgroundColor: '#ffffff',
})

打开链接（内嵌 / 外开）

await jmCallHandler('jm.openUrl', {
  url: 'https://example.com/path',
  showMode: 'inner', // 或 'outer'
})

获取外观（语言、主题等）

const appearance = await jmCallHandler('jm.getAppearance')
// appearance.language / appearance.theme 等

获取定位

const loc = await jmCallHandler('jm.getLocation', {
  enableHighAccuracy: true,
  timeout: 15000,
})
// loc.longitude, loc.latitude, loc.address, ...

选人（需完整必填参数，类型见 JmSelectSessionParams）

import {
  jmCallHandler,
  JmSelectSessionContactsSupportEnum,
  JmSelectSessionRecentContactFilterEnum,
  JmSelectSessionSearchFilterEnum,
} from '@gzbapp/sdk'

const selected = await jmCallHandler('jm.selectSession', {
  multiple: true,
  limit: 10,
  enableSearch: true,
  title: '选择接收人',
  recentContactFilter: JmSelectSessionRecentContactFilterEnum.All,
  searchFilter: JmSelectSessionSearchFilterEnum.All,
  contactsSupport: JmSelectSessionContactsSupportEnum.All,
})

权限检测（1 有权限，0 无）

const { status } = await jmCallHandler('jm.checkPermission', { type: 'camera' })

退出当前 Web 容器

await jmCallHandler('jm.exitWebApp')

通用调用（带类型参数）

对尚未在 overload 中声明的方法，可使用泛型：

const data = await jmCallHandler<MyParams, MyResult>('jm.someMethod', { id: '1' })

错误处理

jmCallHandler 在 JSON-RPC 返回 error 时会 reject，可用 try/catch；错误对象与 rpc-type 中的 RPCError 一致（类方法 jmCallHandlerLoop / listener 路径在出错时可能 throw RPCError，注意区分 Promise reject 与同步 throw）。

jmCallHandlerCallback

由业务在回调里处理 result，适合不想链式 async/await 的写法：

import { jmCallHandlerCallback } from '@gzbapp/sdk'

await jmCallHandlerCallback('jm.setTitle', { title: '标题' }, () => {
  // 客户端已返回 result（此处为 void）
})

jmCallHandlerLoop

典型用途：右侧菜单 jm.addMenuItem（客户端会多次触发同一逻辑）。类型声明中为 jm.addMenuItem 提供了专门 overload。

import { jmCallHandlerLoop } from '@gzbapp/sdk'

await jmCallHandlerLoop(
  'jm.addMenuItem',
  { title: '分享' /* 其他字段见 JmAddMenuParams */ },
  () => {
    // 每次菜单点击都会进入；内部会递归再次注册
  },
)

jmAddListener / jmRemoveListener

监听客户端推送，例如外观变更、文件下载进度（overload 见源码）：

import { jmAddListener } from '@gzbapp/sdk'

const unsubscribe = await jmAddListener('jm.appearanceUpdate', appearance => {
  document.documentElement.dataset.theme = appearance.theme
})

// 在适当时机取消
unsubscribe()

已声明的 jm.* 方法名（便于检索）

jmCallHandler 对下列 method 提供了更严格的 TypeScript 签名（其余仍可用字符串 + 泛型）：

jm.checkPermission、jm.openUrl、jm.selectSession、jm.setTitle、jm.pushUrl、jm.getLocation、jm.exitWebApp、jm.openVCard、jm.previewImage（deprecated）、jm.previewImageVideo、jm.getAppearance、jm.openFile、jm.showTextMessage、jm.getFileUrl、jm.deleteMenuItem、jm.openScanner、jm.openChatView、jm.makeGsmCall、jm.makeCall、jm.setOrientation、jm.login、jm.openApp。

其他导出

同包还导出 RPCClient、Bridge、addListener、legacy 等，详见 src/sdk.ts。若只做 GZBIX 标准 jm.* 能力，优先使用本文 jmCallHandler 系列。

变更备忘（历史）

• GZB9 全面使用 jmrpc 标准 JSON-RPC；GZB8 仍通过兼容层映射部分接口。
• Bridge 在 8/9 上对 PC 方法名等行为有差异，以 bridge 实现为准。