跳到主要内容

UniApp 适配器

概览

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

支持平台

目前已适配以下平台:

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

各平台展示效果

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

各平台展示如下:

H5 端微信小程序
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: 支持云开发的所有核心功能,包括:

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