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.<your-env-region>.app.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: 支持云开发的所有核心功能，包括：
- 身份验证（匿名登录、自定义登录等）
- 数据库（增删改查、实时数据库等）
- 文件存储（文件上传、下载、删除等）
- 云函数
- 云托管