运行时与双端 SDK

小程序 JS 通过随运行包提供的运行时调用宿主能力。前端使用下面的 JS 入口；将原生运行时嵌入新 Android/iOS App 的材料见原生 SDK 分发。

JS 入口与运行时

项目类型	使用入口	加载方式
微信原生项目	App、Page、wx 及转换后的页面事件	工具转换 WXML/WXSS 并生成适配层，随运行包加载
Community 项目	Community、CommunityMini 及组件 API	模板从 /vendor/community-mini.esm.js 导入，工具随包提供
uni-app / 外部 H5	H5 编译结果及已适配的运行时接口	先生成 H5 产物，再由工具打包

无需为微信原生项目另加 CDN 或 npm 包。不同入口的参数与回调形状分别使用各自文档；Community 示例见第一个小程序。

修改 JS 运行时后重新构建并上传新包；原生能力升级需要对应的宿主安装版本。API 版本、工具版本、包内 sdkVersion 和宿主应用版本各自独立。

登录与网络

wx.login

使用 success 接收一次性 code，使用 fail 处理登录失败。code 交给业务后端兑换，不能自行生成或复用：

wx.login({
  success({ code }) {
    if (code) {
      // 将 code 发到自己的业务登录接口。
    }
  },
  fail(error) {
    // 展示失败提示；重新登录时取得新的 code。
  }
})

完整调用链、后端请求和错误码见身份与登录。桌面浏览器中的模拟 code 不可用于真实登录兑换。

wx.request

url 指向配置允许的业务 HTTPS 地址，method 指定方法，data 是业务请求内容，header 只携带业务需要的凭据：

wx.request({
  url: 'https://api.example.com/catalog',
  method: 'GET',
  success({ statusCode, data }) {
    if (statusCode !== 200) return
    // 继续检查自己的业务结果，再更新页面。
  },
  fail(error) {
    // 网络失败；提示用户稍后重试。
  }
})

success 表示收到响应，HTTP 状态和业务结果须分别判断。fail 表示请求链路失败；complete 在调用结束时执行。配置方法见服务器域名。AppSecret 和平台接口 token 不放入这里。

提示、存储与页面导航

方法	参数或返回	使用说明
wx.showToast(options)	title 为提示文本；可传 success、complete	当前适配层通过运行时展示文本，不承诺全部微信样式参数
wx.setStorageSync(key, value)	字符串 key、可序列化值	保存非敏感业务偏好；存储可能抛错
wx.getStorageSync(key)	返回保存值，无值时为 ''	当前适配层会尝试 JSON 解析字符串，按实际业务核对类型
wx.removeStorageSync(key)	字符串 key	移除单项数据
wx.navigateTo({ url })	目标页面路径	页面须在项目内存在；当前适配层不提供完整成功/失败回调语义
wx.navigateBack({ delta })	返回层数	由页面栈和宿主处理返回
wx.getSystemInfoSync()	窗口、屏幕、像素比等	部分字段来自浏览器；当前 platform 为 web，不能据此判定手机系统版本

存储示例：

try {
  wx.setStorageSync('displayPreference', { compact: true })
  const preference = wx.getStorageSync('displayPreference')
  // 按业务使用 preference；退出时按需清理。
} catch (error) {
  // 存储不可用时使用默认显示设置。
}

功能调用入口

场景	入口	参数、回调与条件
手机号	open-type="getPhoneNumber"	按钮事件返回 detail.errMsg 和 detail.code；示例
余额支付	wx.requestPayment	使用业务后端返回的 request_payment；以服务端查单确认结果，支付流程
定位与选点	wx.getLocation、wx.chooseLocation	指引、平台准入、用户与系统权限；配置流程
图片选择	wx.chooseImage	参数及结果见下节；按实际来源声明信息与系统权限
保存相册与扫码	wx.saveImageToPhotosAlbum、wx.scanCode	当前提供的双端宿主未实现，返回 unsupported；见方法差异

定位与图片参数

下列方法通过 success(result) 接收结果，通过 fail(error) 接收拒绝、取消或其他失败；回调结束后调用 complete(result)。使用前按隐私与功能准备实际用途和权限。

方法	当前参数	成功结果与限制
wx.getLocation(options)	success、fail、complete	返回 latitude、longitude、speed、accuracy、altitude、verticalAccuracy、horizontalAccuracy；双端目前不按 type、isHighAccuracy 等选项切换定位配置
wx.chooseLocation(options)	success、fail、complete	选中后返回 name、address、latitude、longitude；当前取消流程缺少可靠的完成回调，页面需提供返回后的恢复入口
wx.chooseImage(options)	count、sourceType、sizeType 和三个回调	返回 tempFilePaths、tempFiles；文件项包含 path、filePath、size，取消进入 fail

图片选择示例：

wx.chooseImage({
  count: 1,
  sourceType: ['album'],
  sizeType: ['compressed'],
  success({ tempFilePaths, tempFiles }) {
    // tempFilePaths 用于本地预览。
    // 需要上传时使用 tempFiles 中的 filePath，不能把展示路径当作原生文件路径。
  },
  fail(error) {
    // 用户取消或选择失败时返回页面；不要自动再次打开选择器。
  },
  complete() {
    // 结束本次图片选择的页面忙碌状态。
  }
})

Android 的 count 缺省为 9，iOS 为 1；显式传值后都限制在 1–9。Android 根据 sourceType 决定是否允许相机，当前未使用 sizeType 控制压缩。iOS 支持相册、相机或来源选择，拍照返回单张图片；相册读取按 sizeType 选择是否压缩。两端的临时展示地址格式不同，不解析或长期保存这些地址。

定位失败需分别处理系统拒绝、定位服务关闭和并发请求。精度字段来自实际设备，Android 当前 verticalAccuracy 为 0；不要据此假定定位成功或坐标制式已切换。

当前方法差异

下面列出影响业务接入的实际方法差异。Android 和 iOS 都要使用与包匹配的宿主版本。

入口	Android	iOS	处理方式
wx.login、wx.request	有桥接入口	有桥接入口	在宿主体验版验证业务登录与网络
wx.checkSession	宿主有处理入口，工具未导出 JS 方法	同左	当前不可直接调用；后端需要时用会话校验
wx.getSetting、wx.authorize	工具未导出，当前桥无对应入口	宿主有入口，工具未导出	当前不能按标准方法接入设置查询与主动授权
wx.openSetting	JS 返回占位结果，未调用宿主	同左	空 authSetting 不代表真实授权状态
手机号、支付、定位与图片选择	有处理入口	有处理入口	在实际安装版本中测试正常、拒绝及取消分支
wx.scanCode、wx.saveImageToPhotosAlbum	有 JS 转发入口，宿主未实现	同左	当前返回 :fail unsupported，不能按已支持能力接入
wx.chooseMedia、wx.downloadFile、wx.openLocation、wx.openDocument	宿主未实现	同左	有 JS 方法不代表可用；当前返回 unsupported
wx.canvasToTempFilePath、wx.compressImage、wx.getVideoInfo、wx.showShareImageMenu	宿主未实现	同左	当前不能依赖这些原生处理入口
wx.chooseAddress	不支持	不支持	自行设计业务地址表单，并声明实际收集信息

能力检测与占位返回（canIUse）

当前 wx.canIUse 固定返回 true；wx.createSelectorQuery().exec 返回 [null]；wx.createVideoContext() 的播放、暂停等方法为空实现。这些入口不能用于判断真实能力、元素尺寸或视频播放结果。

先检查方法是否存在，再核对本页差异和实际调用结果：

const runtime = typeof wx === 'undefined' ? {} : wx
const missing = ['login', 'request', 'checkSession']
  .filter(name => typeof runtime[name] !== 'function')
// 空数组只说明函数存在，仍需验证其行为。

Android 与 iOS 联调准备

1. 安装团队提供的 Android APK 或 iOS 签名联调版本，记录版本号、构建号及摘要。
2. 使用有体验资格的真实账号，进入指定 AppID 和体验版本。
3. 验证首屏、资源、前进、返回、关闭和再次打开。
4. 验证业务登录、域名限制，以及所用功能的同意、拒绝、取消和系统权限失败。
5. 涉及支付时，通过后端查单核对结果；补测切换后台和迟到回调。

预期结果： 两端都能运行目标包，各业务场景有明确结果。桌面预览和模拟器结果只覆盖其对应环境。

常见失败

现象	处理
wx.xxx is not a function	检查本页方法差异和生成运行时，确认所用版本
回调只返回错误文本	保存场景、时间、应用和版本；按错误诊断取得平台请求 ID
桌面正常、手机失败	检查宿主版本、系统权限、域名快照和包签名
需要独立 AAR、Pod 或初始化示例	查看分发材料说明，当前没有可据此编写的完整独立集成契约

运行时日志可能包含原始回调和网络材料，反馈问题时先脱敏，不提交凭据或完整用户数据。

下一步

接入身份与登录或所需功能；完成后按体验、审核与发布交付版本。