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 通过事件总线机制处理图形验证码交互。
工作流程
- 触发验证码 - 当云开发检测到需要图形验证码时,自动调用适配器的图形验证码处理函数
- 解析数据 - 适配器解析图形验证码 URL,提取图片数据、token 和状态信息
- 前端展示 - 通过事件通知前端页面显示图形验证码
- 用户输入 - 用户查看验证码图片并输入答案
- 结果回传 - 前端将用户输入结果通过事件发送回适配器
- 完成验证 - 适配器接收结果并继续后续流程
适配器内部图形验证码处理实现
在适配器内部,可以访问到传入的 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: 支持云开发的所有核心功能,包括:
- 身份验证(匿名登录、自定义登录等)
- 数据库(增删改查、实时数据库等)
- 文件存储(文件上传、下载、删除等)
- 云函数
- 云托管