UniApp 适配器

概览

UniApp 适配器是云开发为 UniApp 框架提供的专用适配器，让开发者能够在 UniApp 项目中无缝使用云开发的完整功能。通过该适配器，您可以轻松实现跨平台的云端数据存储、用户认证、文件管理和云函数调用等。

支持平台

目前已适配以下平台：

• H5 端
• 微信小程序
• 支付宝小程序
• 抖音小程序
• iOS
• Android

各平台展示效果

完整示例项目请参考：CloudBase UniApp 模板

各平台展示如下：

H5 端	微信小程序

支付宝小程序	抖音小程序

Android 和 iOS

安装

使用 npm 安装：

npm install @cloudbase/adapter-uni-app

快速开始

适配器配置

如果需要使用登录功能或自定义配置，需要传入 options 参数：

注意

options 传入后可以在适配器内部的 genAdapter 中接收和使用。详细说明请参考 跨端开发指南。

• uni 对象是必需的，用于处理图形验证码功能。

import cloudbase from '@cloudbase/js-sdk'
import adapter from '@cloudbase/adapter-uni-app'

// 传入配置选项
const options = {
    uni: uni, // 传入 uni 对象，用于图形验证码功能
}

cloudbase.useAdapters(adapter, options)

const app = cloudbase.init({
    env: 'your-env-id', // 替换为您的环境 ID

    // 仅在App端需要配置
    appSign: 'your-app-sign',
    appSecret: {
        appAccessKeyId: 1,
        appAccessKey: 'your-app-access-key'
    }
})

export default app

重要提示

• adapter 必须在 cloudbase.init() 之前调用
• 如果需要实现登录相关功能，必须传入 UniApp 的 uni 对象
• App端需要额外配置应用标识和凭证信息

安全域名配置

云开发 SDK 在使用过程中，向云开发服务发送的请求都需要验证请求来源的合法性。以下是不同平台的域名配置方法：

H5 端

开发环境域名：

http://localhost:本地端口号

生产环境需要配置您的实际域名。

微信小程序

在微信小程序管理后台的【开发】→【开发管理】→【开发设置】→【服务器域名】中配置：

request 合法域名：

https://tcb-api.tencentcloudapi.com
https://your-env-id.service.tcloudbase.com

uploadFile 合法域名：

https://cos.ap-shanghai.myqcloud.com

downloadFile 合法域名：

https://your-env-id.tcb.qcloud.la
https://cos.ap-shanghai.myqcloud.com

提示

请将 your-env-id 替换为您的实际环境 ID，地域根据您的云开发环境所在地域调整。

支付宝小程序

开发环境域名：

devappid.hybrid.alipay-eco.com

抖音小程序

开发环境域名：

tmaservice.developer.toutiao.com

App 端配置

在云开发控制台的【环境配置】→【安全来源】→【移动应用安全来源】中添加应用：

• 应用标识：your-app-sign
• 应用凭证：your-app-access-key

const appConfig = {
    env: 'your-env-id',
    appSign: 'your-app-sign', // 应用标识
    appSecret: {
        appAccessKeyId: 1, // 凭证版本
        appAccessKey: 'your-app-access-key' // 应用凭证
    }
}

开发环境启动

# H5 开发
npm run dev:h5

# 微信小程序开发
npm run dev:mp-weixin

# 抖音小程序开发
npm run dev:mp-toutiao

# 支付宝小程序开发
npm run dev:mp-alipay

# App (iOS/Android) 开发
# 1. 使用 HBuilderX 打开项目
# 2. 在顶部菜单栏选择【运行】->【运行到手机或模拟器】-> 选择您的设备

平台支持说明

目前稳定支持 APP、H5、微信小程序、抖音小程序和支付宝小程序平台，其他平台适配正在开发中。

图形验证码机制说明

在某些安全敏感的操作场景下（如用户登录），腾讯云开发会要求进行图形验证码验证。UniApp Adapter 通过事件总线机制处理图形验证码交互。

工作流程

1. 触发验证码 - 当云开发检测到需要图形验证码时，自动调用适配器的图形验证码处理函数
2. 解析数据 - 适配器解析图形验证码 URL，提取图片数据、token 和状态信息
3. 前端展示 - 通过事件通知前端页面显示图形验证码
4. 用户输入 - 用户查看验证码图片并输入答案
5. 结果回传 - 前端将用户输入结果通过事件发送回适配器
6. 完成验证 - 适配器接收结果并继续后续流程

适配器内部图形验证码处理实现

在适配器内部，可以访问到传入的 uni 对象，通过事件总线发送图形验证码数据：

function genAdapter(options) {
  const adapter: SDKAdapterInterface = {
    // 其他适配器配置...

    captchaOptions: {
      // 当检测到需要验证码时，自动触发此函数
      // _url 为包含验证码图片、token、state等参数的字符串
      openURIWithCallback: (_url: string) => {
        // 在适配器内部使用传入的 uni 对象
        const uni = options.uni

        // 解析URL中的验证码参数
        const { captchaData, state, token } = cloudbase.parseCaptcha(_url)

        return new Promise((resolve) => {
          console.log('等待验证码输入...')

          // 发送验证码数据到前端
          uni.$emit('CAPTCHA_DATA_CHANGE', { 
            state,      // 验证码状态标识
            token,      // 验证码token  
            captchaData // Base64编码的验证码图片
          })

          // 监听验证码验证结果
          uni.$once('RESOLVE_CAPTCHA_DATA', (res: { 
            captcha_token: string
            expires_in: number 
          }) => {
            resolve(res)
          })
        })
      }
    }
  }
  
  return adapter
}

前端验证码处理

在您的 UniApp 页面中，需要监听验证码事件并处理用户输入：

// 在页面中监听验证码事件
uni.$on('CAPTCHA_DATA_CHANGE', ({ state, token, captchaData }) => {
  console.log("收到验证码数据", { state, token, captchaData });

  // 更新本地验证码状态
  captchaState = { state, token, captchaData };

  // 在页面中显示验证码图片...
});

常见问题

Q: 为什么要在 init 之前调用 useAdapters？

A: 适配器需要在 SDK 初始化之前注册，以确保 SDK 能够正确识别当前运行环境并使用相应的适配器。

Q: 如何处理不同平台的差异？

A: UniApp Adapter 会自动检测当前运行平台并使用相应的适配逻辑，开发者无需手动处理平台差异。

Q: 图形验证码功能如何自定义样式？

A: 图形验证码的显示和交互完全由开发者控制，您可以根据需要自定义图形验证码弹窗的样式和交互逻辑。

Q: 支持哪些云开发功能？

A: 支持云开发的所有核心功能，包括：

• 身份验证（匿名登录、自定义登录等）
• 数据库（增删改查、实时数据库等）
• 文件存储（文件上传、下载、删除等）
• 云函数
• 云托管