@cloudbase/adapter-rn

CloudBase React Native Adapter

📖 概述

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

🚀 安装

使用 npm：

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

安装依赖

适配器依赖 react-native-mmkv 作为持久化存储：

npm install react-native-mmkv@^3.2.0

iOS 需要安装原生依赖：

cd ios && pod install && cd ..

CloudBase React Native 模版

一个基于 React Native / Expo 和腾讯云开发的移动应用模板，提供了用户登录、图形验证码、云函数调用、数据模型操作、云存储上传等常用功能的实现。支持 iOS 和 Android。

⚡ 快速开始

配置

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

// src/config/cloudbase.ts
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;

开发环境启动

# iOS 开发
npx expo run:ios

# Android 开发
npx expo run:android

# 使用 React Native CLI
npx react-native run-ios
npx react-native run-android

📚 功能示例

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

🔐 图形验证码说明

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

React Native Adapter 内部已集成部分图形验证码处理流程，内部实现如下。

function genAdapter(): SDKAdapterInterface {
  const adapter: SDKAdapterInterface = {
    // ...
    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, // Base64编码的验证码图片
                state, // 验证码状态标识
                token, // 验证码token 
                resolve, // auth.verifyCaptchaData的校验结果
            });
          } else {
            console.warn("No captcha handler registered");
            resolve({ error: "no_handler" } as any);
          }
        });
      },
    },
    // ...
  };

  return adapter;
}

开发者只需注册验证码处理器captchaHandler，其实现可以参考图形验证码openURIWithCallback处理流程

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

// 注册验证码处理器
setCaptchaHandler(({ captchaData, state, token, resolve }) => {
  // 显示captchaData验证码 UI
  // 用户输入验证码后调用 auth.verifyCaptchaData的校验结果，完成验证后调用 resolve 返回结果
  const captchaToken = await auth.verifyCaptchaData({ token, key: "user-input-captcha-key" });
  resolve(captchaToken);
});

⚠️ 注意事项

RN 环境限制

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

版本要求

• react-native-mmkv: v3.x（v4.x 需要 NitroModules，配置较复杂）
• @cloudbase/js-sdk: >=2.24.9
• React Native: 0.70+
• Expo SDK: 48+

📚 相关资源

官方文档

• CloudBase JavaScript SDK
• 适配器开发指引

示例项目

• CloudBase React Native 模版