模板版本:v0.4.0

react-native-file-selector

本项目基于 react-native-file-selector 开发。

该第三方库的仓库已迁移至 Gitcode,且支持直接从 npm 下载,新的包名为:@react-native-ohos/react-native-file-selector 版本所属关系如下:

三方库名称 三方库版本 发布信息 支持RN版本 Autolink 编译API版本 社区基线版本 npm地址
@react-native-ohos/react-native-file-selector ~1.2.0 Gitcode Releases 0.82.* API12+ 1.0.3 Npm Address
@react-native-ohos/react-native-file-selector ~1.1.0 Gitcode Releases 0.77.* API12+ 1.0.3 Npm Address
@react-native-ohos/react-native-file-selector ~1.0.3 Gitcode Releases 0.72.* API12+ 1.0.3 Npm Address
@react-native-oh-tpl/react-native-file-selector <= 1.0.2-0.0.3@deprecated Github Releases(deprecated) 0.72.* API12+ 1.0.3 Npm Address

1. 安装与使用

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

npm

npm install @react-native-ohos/react-native-file-selector

yarn

yarn add @react-native-ohos/react-native-file-selector

对于未发布到npm的旧版本,请参考安装指南安装tgz包。

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

使用时 import 的库名不变。

import FileSelector from 'react-native-file-selector';
import React from 'react';
function App(): React.JSX.Element {
  
  return (
    <FileSelector
      onDone={(path) => {console.log("file selected: " + path);}}
      onCancel={() => {console.log("cancelled");}}
    />)
};
export default App;

使用 Codegen

本库已经适配了 Codegen ,在使用前需要主动执行生成三方库桥接代码,详细请参考 Codegen 使用文档

是否支持autolink RN框架版本
~1.2.0 Yes 0.82
~1.1.0 No 0.77
~1.0.3 Yes 0.72
<= 1.0.2-0.0.3@deprecated No 0.72

使用AutoLink的工程需要根据该文档配置,Autolink框架指导文档:https://gitcode.com/openharmony-sig/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md

如您使用的版本支持 Autolink,并且工程已接入 Autolink,可跳过ManualLink配置。

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

首先需要使用 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 包引入(推荐)

har 包位于三方库安装路径的 `harmony` 文件夹下。

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

"dependencies": {
    "@react-native-ohos/react-native-file-selector": "file:../../node_modules/@react-native-ohos/react-native-file-selector/harmony/file_selector.har"
  }

点击右上角的 sync 按钮

或者在命令行终端执行:

cd entry
ohpm install

方法二:直接链接源码

如需使用直接链接源码,请参考[直接链接源码说明](./link-source-code.md)

2.3. 配置 CMakeLists 和引入 FileSelectorPackage

打开 entry/src/main/cpp/CMakeLists.txt,添加:

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

# RNOH_BEGIN: manual_package_linking_1
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-file-selector/src/main/cpp" ./file-selector)
# RNOH_END: manual_package_linking_1

# RNOH_BEGIN: manual_package_linking_2
+ target_link_libraries(rnoh_app PUBLIC rnoh_file_selector)
# RNOH_END: manual_package_linking_2

打开 entry/src/main/cpp/PackageProvider.cpp,添加:

#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
+ #include "FileSelectorPackage.h"

using namespace rnoh;

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

2.5. 在 ArkTs 侧引入 RNFileSelectorPackage

打开 entry/src/main/ets/RNPackagesFactory.ts,添加:

  ...
+ import {RNFileSelectorPackage}  from '@react-native-ohos/react-native-file-selector/ts';

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

2.6. 运行

点击右上角的 sync 按钮

或者在命令行终端执行:

cd entry
ohpm install

然后编译、运行即可。

3. 约束与限制

3.1. 兼容性

本文档内容基于以下版本验证通过:

  1. RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
  2. RNOH: 0.72.33; SDK: HarmonyOS NEXT B1; IDE: DevEco Studio: 5.0.3.900; ROM: Next.0.0.71;
  3. RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
  4. RNOH: 0.82.7; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM:6.0.0.328 SP26;

4. 属性

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

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

FileSelector

Name Description Type Required Platform HarmonyOS Support
filter 文件过滤条件 string no All yes
path 目录路径 string no All yes
onDone 选中文件后触发的回调 func no All yes
onCancel 取消选择文件时调用的函数 func no All yes
title 工具栏标题 string no Android iOS no
closeMenu 关闭按钮的着色颜色 string no Android iOS no
hiddenFiles 如果为 true,也会显示隐藏文件 bool no Android no
filterDirectories 是否对目录应用过滤器 bool no Android no

5. API

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

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

Name Description Type Required Platform HarmonyOS Support
Show 打开文件选择器 function no All yes

Show

Show(filter?: string, path?: string, onDone?: func, onCancel?: func, title?: string, closeMenu?: string, hiddenFiles?: bool, filterDirectories?: bool);
Name Description Type Required Platform HarmonyOS Support
filter 文件过滤条件 string no All yes
path 目录路径 string no All yes
onDone 选中文件后触发的回调 func no All yes
onCancel 取消选择文件时调用的函数 func no All yes
title 工具栏标题 string no Android iOS no
closeMenu 关闭按钮的着色颜色 string no Android iOS no
hiddenFiles 如果为 true,也会显示隐藏文件 bool no Android no
filterDirectories 是否对目录应用过滤器 bool no Android no

6. 遗留问题

7. 其他

8. 开源协议

本项目基于 Apache License 2.0 ,请自由地享受和参与开源。