rn-fetch-blob

本项目基于 rn-fetch-blob开发。如果在使用过程中有任何问题，欢迎在AtomGit提交Issue，会及时跟进。

项目介绍

@hxa-rn/rn-fetch-blob 是 rn-fetch-blob 的 React Native 鸿蒙（OpenHarmony）适配包，提供上传、下载与文件系统访问能力，支持文件流读写以处理大文件。当前版本 0.12.4。

集成指南

npm install @hxa-rn/rn-fetch-blob

peerDependencies：react-native >= 0.72。

import 时使用原库名 'rn-fetch-blob'，而非鸿蒙适配包名 '@hxa-rn/rn-fetch-blob'（harmony.alias 已配置为 rn-fetch-blob）。

当前版本支持 Autolink；若工程已接入 Autolink，可跳过手动配置。

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

"dependencies": {
  "@hxa-rn/rn-fetch-blob": "file:../../node_modules/@hxa-rn/rn-fetch-blob/harmony/fetch_blob.har"
}

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@hxa-rn/rn-fetch-blob/src/main/cpp" ./fetch_blob)

target_link_libraries(rnoh_app PUBLIC fetch_blob)

#include "FetchBlobPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<FetchBlobPackage>(ctx),
    };
}

import { FetchBlobPackage } from '@hxa-rn/rn-fetch-blob';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new FetchBlobPackage(ctx),
  ];
}

使用说明

import RNFetchBlob from 'rn-fetch-blob';

async function run() {
  // 1. HTTP 文件下载
  const resp = await RNFetchBlob.config({
    fileCache: true,
    appendExt: 'png',
    path: `${RNFetchBlob.fs.dirs.DocumentDir}/sample.png`,
    timeout: 30000,
  }).fetch('GET', 'https://picsum.photos/200/300');

  const filePath = resp.path();
  const info = resp.respInfo;
  console.log('saved to:', filePath, 'status:', info.status);

  // 2. 下载进度
  await RNFetchBlob.config({ fileCache: true })
    .fetch('GET', 'https://picsum.photos/200/300')
    .progress({ count: 1, interval: 100 }, (received, total) => {
      console.log(`received ${received} / ${total}`);
    });

  // 3. POST JSON
  await RNFetchBlob.config({})
    .fetch(
      'POST',
      'https://httpbin.org/post',
      { 'Content-Type': 'application/json' },
      JSON.stringify({ name: 'test' }),
    );

  // 4. 文件系统
  await RNFetchBlob.fs.createFile(
    `${RNFetchBlob.fs.dirs.DocumentDir}/a.txt`,
    'Hello',
    'utf8',
  );
  const content = await RNFetchBlob.fs.readFile(
    `${RNFetchBlob.fs.dirs.DocumentDir}/a.txt`,
    'utf8',
  );
  console.log('file content:', content);
  await RNFetchBlob.fs.unlink(`${RNFetchBlob.fs.dirs.DocumentDir}/a.txt`);
}

run();

平台差异：

• 目录常量：DocumentDir / CacheDir / PictureDir / MusicDir / MovieDir / DownloadDir 映射鸿蒙应用沙箱绝对路径；DCIMDir / SDCardDir / SDCardApplicationDir / LibraryDir 鸿蒙无对应外部存储概念，降级返回 '' 或应用沙箱路径
• 不支持 API：fs.scanFile、android.addCompleteDownload、ios.previewDocument / openDocument / excludeFromBackupKey、fs.pathForAppGroup —— 调用时 reject / callback 返回 … is not supported on HarmonyOS，业务需 try-catch（详解见下方「遗留问题」）
• syncPathAppGroup 返回 ''；emitExpiredEvent 为空实现（不列入「不支持」报告，见下方约束）
• actionViewIntent 使用 @kit.PreviewKit 预览文件；getContentIntent 使用 @ohos.file.picker DocumentViewPicker
• wifiOnly / trusty / followRedirect 等配置项已按鸿蒙 @ohos.net.http 语义实现

接口文档

✅ = 鸿蒙原生实现；⚠️ = 降级/沙箱替代实现（不列入不支持报告）；❌ = 鸿蒙不支持，返回 … is not supported on HarmonyOS（编号见下方「遗留问题」）。 目录常量获取方式：RNFetchBlob.fs.dirs.DocumentDir 等（getConstants() 映射）。

快速验证（运行 Example）

前置条件

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/rn-fetch-blob.git
cd rn-fetch-blob
git checkout main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/rn-fetch-blob@0.12.4，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 进入 example 目录，安装依赖

cd example          # 或 example_auto
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony（或 example_auto/harmony）目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。Example 已声明 ohos.permission.INTERNET（HTTP 请求必需）。

约束与限制

兼容性

• 鸿蒙 SDK：API 12+
• 上游 RN 库：rn-fetch-blob 0.12.0
• React Native / RNOH：0.72+
• DevEco Studio：5.0+

权限

• ohos.permission.INTERNET（HTTP 请求必需，需在 entry/src/main/module.json5 的 requestPermissions 中声明）

平台能力差异

• 大文件（GB 级）响应体按 path/fileCache 落盘，避免读入内存导致 OOM
• wifiOnly 仅对蜂窝数据网络生效（与 Android SDK21+ 语义一致）
• trusty 信任自签名证书场景受鸿蒙系统 CA 策略限制
• getSDCardDir / getSDCardApplicationDir 无外部 SD 概念，返回应用 filesDir
• syncPathAppGroup 返回空串；emitExpiredEvent 为空实现（iOS AppState 过期网络事件，鸿蒙无对等触发）

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

使用问题请在 AtomGit 提交 Issue。也可在 GitCode 仓库反馈：

https://gitcode.com/hxa-rn/rn-fetch-blob

https://gitcode.com/hxa-rn/rn-fetch-blob/issues