错误处理

错误对象结构

所有 woo.* 调用失败时，Promise 会 reject 一个错误对象：

interface BridgeError {
  code: number     // 错误码（见下表）
  message: string  // 错误描述
}

基础用法

import { BridgeErrorCode } from 'mini-sdk'

try {
  await woo.chooseImage({ count: 1 })
} catch (err: any) {
  switch (err.code) {
    case BridgeErrorCode.UserCancelled:
      // 用户关闭了文件选择框，不需要提示
      break
    case BridgeErrorCode.PermissionDenied:
      woo.showToast({ title: '请在系统设置中允许访问相册', icon: 'error' })
      break
    case BridgeErrorCode.Timeout:
      woo.showToast({ title: '请求超时，请重试', icon: 'error' })
      break
    default:
      console.error('未知错误', err.code, err.message)
  }
}

错误码速查

枚举	值	说明
UnhandledApi	10001	API 未注册
Timeout	40800	请求超时
PermissionDenied	20001	权限被拒绝
AuthFailed	20002	鉴权失败
BiometricCancelled	20003	生物识别取消
InvalidParam	40001	参数错误
NotSupported	40002	功能不支持
UserCancelled	40003	用户取消操作
NetworkUnavailable	40004	网络不可用
InternalError	50000	Native 内部错误

全局错误处理

推荐在应用入口统一捕获未处理的 Bridge 错误：

// main.ts
import { BridgeErrorCode } from 'mini-sdk'

// Vue 错误边界
app.config.errorHandler = (err: any) => {
  if (err?.code === BridgeErrorCode.NetworkUnavailable) {
    woo.showToast({ title: '网络不可用', icon: 'error' })
    return
  }
  if (err?.code === BridgeErrorCode.UserCancelled) {
    // 用户取消不需要上报
    return
  }
  // 上报到错误监控
  woo.recordEvent({ event: 'bridge_error', properties: { code: err.code, message: err.message } })
}

最佳实践

忽略用户取消

UserCancelled（40003）是正常用户行为，不需要显示错误提示，也不需要上报。

超时处理

网络请求默认超时 30 秒，文件选择类 API 默认 120 秒。超时后 SDK 会 reject BridgeErrorCode.Timeout，建议在业务层做重试逻辑。

权限拒绝

PermissionDenied（20001）通常是用户拒绝了系统权限弹窗。需要引导用户前往系统设置手动开启，无法通过代码再次获取。