@ohmi/react-native-fs

模板版本：v0.2.2

@ohmi/react-native-fs

1. 安装与使用

进入到工程目录并输入以下命令：

npm

npm install @ohmi/react-native-fs

yarn

yarn add @ohmi/react-native-fs

下面的代码展示了这个库的基本使用场景：

[!WARNING] 使用时 import 的库名不变。

import React, { useState } from "react";
import { SafeAreaView, StyleSheet, ScrollView, View, Text, StatusBar, TextInput, Button } from "react-native";
import FS from "react-native-fs";
import { Colors } from "react-native/Libraries/NewAppScreen";

function App(): React.JSX.Element {
  const [mkdirParam, setMkdirParam] = useState("");
  const mkdirExample = () => {
    FS.mkdir(FS.DocumentDirectoryPath + "/" + mkdirParam).then(
      (result) => {
        console.log("file mkdirParam： " + mkdirParam);
        console.log("file Successfully created directory.");
      },
      (err) => {
        console.error("file mkdir: " + err.message);
      }
    );
  };

  return (
    <>
      <StatusBar barStyle="dark-content" />
      <SafeAreaView>
        <ScrollView contentInsetAdjustmentBehavior="automatic" style={styles.scrollView}>
          <Text style={styles.sectionTitle}>{"React Native File Harmony Demo App"}</Text>
          <View style={styles.body}>
            <View style={styles.sectionContainer}>
              <Text style={styles.sectionTitle}>{"mkdir"}</Text>
              <View style={styles.sectionDescription}>
                <TextInput
                  style={styles.input}
                  placeholder="Folder Path"
                  onChangeText={(mkdirParam) => setMkdirParam(mkdirParam)}
                  placeholderTextColor="#9a73ef"
                  autoCapitalize="none"
                />
              </View>
              <Button title="Create Directory" color="#9a73ef" onPress={mkdirExample} />
            </View>
          </View>
        </ScrollView>
      </SafeAreaView>
    </>
  );
}

const styles = StyleSheet.create({
  scrollView: {
    backgroundColor: Colors.black,
  },
  engine: {
    position: "absolute",
    right: 0,
  },
  body: {
    backgroundColor: Colors.dark,
  },
  sectionContainer: {
    marginTop: 32,
    paddingHorizontal: 24,
  },
  sectionTitle: {
    fontSize: 24,
    fontWeight: "600",
    color: Colors.white,
  },
  sectionDescription: {
    marginTop: 8,
    fontSize: 18,
    fontWeight: "400",
    color: Colors.dark,
  },
  input: {
    marginTop: 12,
  },
});

export default App;

2. Manual Link

此步骤为手动配置原生依赖项的指导。

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。

2.1. Overrides RN SDK

为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 oh-package.json5 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。

关于该字段的作用请阅读官方说明

{
  "overrides": {
    "@rnoh/react-native-openharmony": "^0.72.38" // ohpm 在线版本
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
  }
}

2.2. 引入原生端代码

目前有两种方法：

• 通过 har 包引入；
• 直接链接源码。

方法一：通过 har 包引入（推荐）

[!TIP] har 包位于三方库安装路径的 harmony 文件夹下。

打开 entry/oh-package.json5，添加以下依赖

"dependencies": {
    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
    "@ohmi/react-native-fs": "file:../../node_modules/@ohmi/react-native-fs/harmony/fs.har"
  }

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

方法二：直接链接源码

[!TIP] 如需使用直接链接源码，请参考直接链接源码说明

2.3. 配置 CMakeLists 和引入 RNFSPackage

[!TIP] 版本 v2.20.1 及以上需要

打开 entry/src/main/cpp/CMakeLists.txt，添加：

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

# RNOH_BEGIN: manual_package_linking_1
add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+ add_subdirectory("${OH_MODULES}/@ohmi/react-native-fs/src/main/cpp" ./fs)
# RNOH_END: manual_package_linking_1

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)

target_link_libraries(rnoh_app PUBLIC rnoh)

# RNOH_BEGIN: manual_package_linking_2
target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
+ target_link_libraries(rnoh_app PUBLIC rnoh_fs)
# RNOH_END: manual_package_linking_2

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "RNOH/PackageProvider.h"
#include "SamplePackage.h"
+ #include "RNFSPackage.h"

using namespace rnoh;

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

2.4. 在 ArkTs 侧引入 FsPackage

打开 entry/src/main/ets/RNPackagesFactory.ts，添加：

import type { RNPackageContext, RNPackage } from 'rnoh/ts';
  ...
+ import { FsPackage } from '@ohmi/react-native-fs/ts';

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

2.5. 运行

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

然后编译、运行即可。

3. 约束与限制

3.1. 兼容性

请到三方库相应的 Releases 发布地址查看 Release 配套的版本信息：@ohmi/react-native-fs Releases

4. 静态方法

[!TIP] "Platform"列表示该属性在原三方库上支持的平台。

[!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

Name	Description	Type	Required	Platform	HarmonyOS Support	Remark
DocumentDirectoryPath	System Path	string	No	iOS/Android	yes
CachesDirectoryPath	System Path	string	No	iOS/Android	yes
MainBundlePath	System Path	string	No	iOS	yes
ExternalCachesDirectoryPath	System Path	string	No	Android	No	Android only
DownloadDirectoryPath	System Path	string	No	Android/Windows	No	not available on Harmony
TemporaryDirectoryPath	System Path	string	No	iOS/Android	yes
LibraryDirectoryPath	System Path	string	No	iOS	yes
ExternalDirectoryPath	System Path	string	No	Android	No	Android only
ExternalStorageDirectoryPath	System Path	string	No	Android	No	Android only
PicturesDirectoryPath	System Path	string	No	Windows	No	Windows only
RoamingDirectoryPath	System Path	string	No	Windows	No	Windows only

5. API

[!TIP] "Platform"列表示该属性在原三方库上支持的平台。

[!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

Name	Description	Type	Platform	Required	HarmonyOS Support	Remark
mkdir	Create a directory at filepath.	function	Android	No	yes
exists	Check if the item exists at filepath.	function	iOS/Android	No	yes
readFile	Reads the file at path and return contents.	function	iOS/Android	No	yes
readFileAssets	Reads the file at path in the harmony app's assets folder and return contents.	function	Android	No	yes
writeFile	Write the contents to filepath.	function	iOS/Android	No	yes
appendFile	Append the contents to filepath.	function	iOS/Android	No	yes
copyFile	Copies the file located at filepath to destPath.	function	iOS	No	yes
unlink	Unlinks the item at filepath.	function	iOS/Android	No	yes
hash	Reads the file at path and returns its checksum as determined by algorithm, which can be one of md5, sha1, sha256.	function	iOS/Android	No	partially
moveFile	Moves the file located at filepath to destPath.	function	iOS/Android	No	yes
read	Reads length bytes from the given position of the file at path and returns contents.	function	iOS/Android	No	yes
write	Write the contents to filepath at the given random access position.	function	iOS/Android	No	yes
touch	Sets the modification timestamp mtimeof the file at filepath.	function	iOS/Android	No	yes
stat	Stats an item at filepath.	function	iOS/Android	No	yes
readDir	Reads the contents of path.	function	iOS/Android	No	yes
readDirAssets	Reads the contents of dirpath in the Android app's assets folder.	function	Android	No	No	Android only
readdir	Node.js style version of readDir that returns only the names.	function	iOS/Android	No	No	No API on Harmony
readFileRes	Reads the file named filename in the Android app's res folder and return contents.	function	Android	No	No	Android only
copyFolder	Copies the contents located at srcFolderPath to destFolderPath.	function	Windows	No	No	Windows only
copyFileAssets	Copies the file at filepath in the Android app's assets folder and copies it to the given destPath path.	function	Android	No	No	Android only
copyFileRes	Copies the file named filename in the Android app's res folder and copies it to the given destPath path.	function	Android	No	No	Android only
copyAssetsFileIOS	Reads an image file from Camera Roll and writes to destPath.	function	iOS	No	No	iOS only
copyAssetsVideoIOS	Copies a video from assets-library, that is prefixed with 'assets-library://asset/asset.MOV?...' to a specific destination.	function	iOS	No	No	iOS only
existsAssets	Check in the Android assets folder if the item exists.	function	Android	No	yes
existsRes	Check in the Android res folder if the item named filename exists.	function	Android	No	No	Android only
downloadFile	Abort the current download job with this ID.	function	iOS/Android	No	yes
stopDownload	Abort the current download job with this ID.	function	iOS/Android	No	No	No API on Harmony
resumeDownload	Resume the current download job with this ID.	function	iOS	No	No	iOS only
isResumable	Check if the the download job with this ID is resumable with resumeDownload().	function	iOS	No	No	iOS only
completeHandlerIOS	For use when using background downloads, tell iOS you are done handling a completed download.	function	iOS	No	No	iOS only
uploadFiles	Percentage can be computed easily by dividing totalBytesSent by totalBytesExpectedToSend.	function	iOS/Android	No	No	No API on Harmony
stopUpload	Abort the current upload job with this ID.	function	iOS	No	No	iOS only
getFSInfo	Returns an object with the following properties.	function	iOS/Android	No	No	No API on Harmony
scanFile	Scan the file using Media Scanner.	function	Android	No	No	Android only
getAllExternalFilesDirs	Returns an array with the absolute paths to application-specific directories on all shared/external storage devices where the application can place persistent files it owns.	function	Android	No	No	Android only
pathForGroup	Returns the absolute path to the directory shared for all applications with the same security group identifier.	function	iOS	No	No	iOS only

6. 遗留问题

• HarmonyOS 的 hash 哈希 API 中关于算法参数 algorithm 目前仅支持"md5"、"sha1"、 "sha256"，其他相关算法参数目前不支持，问题: issue#1
• 原库部分接口在 HarmonyOS 中没有对应文件路径常量及接口处理相关逻辑，问题: issue#2

7. 其他

8. 开源协议

本项目基于 The MIT License (MIT) ，请自由地享受和参与开源。