跳到主要内容

React Native 适配器

概览​

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

支持平台​

目前已适配以下平台：

  • iOS 13+
  • Android 6+

环境要求​

  • Node.js >= 18
  • React Native 0.76+
  • Expo SDK 52+

效果展示​

完整示例项目请参考：CloudBase React Native Demo

安装​

使用 npm 安装：

npm install @cloudbase/js-sdk @cloudbase/adapter-rn react-native-mmkv
注意

react-native-mmkv 用于高性能持久化存储，建议使用 v3.x 版本，v4.x 需要 NitroModules 配置较复杂。

iOS 原生依赖​

cd ios && pod install && cd ..

快速开始​

适配器配置​

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

// 注册适配器
cloudbase.useAdapters(adapter);

const app = cloudbase.init({
  env: "your-env-id", // 替换为您的环境 ID
  region: "ap-shanghai", // 地域
  accekey: "your-app-access-key", // Publishable Key
});

export default app;
重要提示
  • adapter 必须在 cloudbase.init() 之前调用

图形验证码机制说明​

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

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);
});

项目结构​

主要依赖​

依赖版本说明
@cloudbase/js-sdk^2.24.9腾讯云开发 SDK
@cloudbase/adapter-rn^1.0.0React Native 适配器
react-native-mmkv^3.3.3高性能持久化存储

常见问题​

Q: 为什么要在 init 之前调用 useAdapters？​

A: 适配器需要在 SDK 初始化之前注册，以确保 SDK 能够正确识别当前运行环境并使用相应的适配器。

Q: 为什么推荐使用 react-native-mmkv v3.x？​

A: v4.x 版本需要 NitroModules 配置，配置较为复杂。v3.x 版本配置简单，性能稳定。

Q: 文件上传为什么需要使用 base64 编码？​

A: React Native 环境下，文件系统访问与 Web 环境不同，使用 base64 编码是最兼容的方式。上传时需设置 contentEncoding: 'base64'。

相关资源​