@cloudbase/adapter-rn

CloudBase React Native Adapter

概述

CloudBase React Native Adapter 是专为 React Native / Expo 开发框架设计的腾讯云开发适配器。它让开发者能够在 React Native 项目中无缝集成腾讯云开发的核心能力，包括数据库、云存储、云函数、数据模型等。

安装

npm install @cloudbase/adapter-rn @cloudbase/js-sdk

react-native-mmkv 已作为依赖自动安装，iOS 需要安装原生依赖：

cd ios && pod install && cd ..

快速开始

在 React Native 项目中引入并初始化适配器：

import cloudbase from '@cloudbase/js-sdk';
import adapter from '@cloudbase/adapter-rn';

// 使用 React Native 适配器
cloudbase.useAdapters(adapter);

// 初始化 CloudBase 应用实例
const app = cloudbase.init({
  env: 'your-env-id',           // 替换为您的云开发环境 ID
  region: 'ap-shanghai',         // 地域
  accessKey: 'your-access-key',  // 替换为您的 Access Key
});

export const auth = app.auth;
export default app;

@cloudbase/js-sdk 使用方法请参考：JS SDK(V3)

图形验证码

在某些安全敏感的操作场景下（如用户登录），腾讯云开发会要求进行图形验证码验证。适配器内部已集成验证码处理流程：

captchaOptions: {
  openURIWithCallback: async (url: string): Promise<CaptchaToken> => {
    const urlObj = new URL(url);
    const captchaData = urlObj.searchParams.get("captcha_data") || "";
    const state = urlObj.searchParams.get("state") || "";
    const token = urlObj.searchParams.get("token") || "";

    return new Promise((resolve) => {
      if (captchaHandler) {
        captchaHandler({ captchaData, state, token, resolve });
      } else {
        console.warn("No captcha handler registered");
        resolve({ error: "no_handler" } as any);
      }
    });
  },
}

开发者需注册验证码处理器，参考 图形验证码处理流程：

import { setCaptchaHandler } from '@cloudbase/adapter-rn';

setCaptchaHandler(async ({ captchaData, state, token, resolve }) => {
  // 显示 captchaData (Base64编码的验证码图片) 给用户
  // 用户输入验证码后调用 verifyCaptchaData 校验
  const captchaToken = await auth.verifyCaptchaData({ token, key: "user-input-captcha-key" });
  resolve(captchaToken);
});

注意事项

• Headers 格式：RN fetch 返回的 headers 格式与标准不同，适配器已自动处理转换
• 持久化存储：使用 MMKV 替代 AsyncStorage，提供同步 API 和更好的性能

版本要求

依赖	版本
@cloudbase/js-sdk	>=2.24.9
react-native-mmkv	v3.x（v4.x 需要 NitroModules）
React Native	0.70+
Expo SDK	48+

示例展示

CloudBase React Native示例请参考 示例代码

相关资源

• CloudBase JavaScript SDK
• 适配器开发指引
• CloudBase React Native 模版
• Changelog