@react-native-ohos/react-native-file-viewer

v2.3.0-beta.3

Published

8 days ago

Native file viewer for react-native

模板版本：v0.4.0

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-file-viewer 版本所属关系如下： | 三方库名称 | 三方库版本 | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | npm地址 | | ------------ | ------------ | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- | | @react-native-ohos/react-native-file-viewer | ~2.3.0（开发中） | Gitcode Releases | 0.82.* | Yes | API12+ | 2.1.5 | Npm Address | | @react-native-ohos/react-native-file-viewer | ~2.2.0 | Gitcode Releases | 0.77.* | No | API12+ | 2.1.5 | Npm Address | | @react-native-ohos/react-native-file-viewer | ~2.1.7 | Gitcode Releases | 0.72.* | Yes | API12+ | 2.1.5 | Npm Address | | @react-native-oh-tpl/react-native-file-viewer | <= 2.1.6@deprecated | Github Releases(deprecated) | 0.72.* | No | API12+ | 2.1.5 | Npm Address |

1. 安装与使用

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

npm

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

yarn

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

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

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

import { StyleSheet, ScrollView, Text, TouchableOpacity } from "react-native";
import DocumentPicker from "react-native-document-picker";
import FileViewer from "react-native-file-viewer";

export function FlieViewerExample() {
	const FileViewerTest = async (option?: any) => {
		try {
			// 使用react-native-document-picker来选择本地文件进行打开
			const res: any = await DocumentPicker.pick({
				type: [DocumentPicker.types.allFiles]
			});
			// uri 为本地文件绝对路径
			await FileViewer?.open(res[0].uri, option);
		} catch (e) {
			// error
		}
	};

	const onDismissCb = () => {
		// do sth ...
	};

	return (
		<ScrollView style={{ backgroundColor: "skyblue" }}>
			<TouchableOpacity onPress={() => FileViewerTest()} style={styles.btn}>
				<Text style={styles.btnText}>Toogle Status Bar</Text>
			</TouchableOpacity>
			<TouchableOpacity onPress={() => FileViewerTest("show_displayName string")} style={styles.btn}>
				<Text style={styles.btnText}>Toogle Status Bar (displayName str)</Text>
			</TouchableOpacity>
			<TouchableOpacity onPress={() => FileViewerTest({ displayName: "show_displayName option" })} style={styles.btn}>
				<Text style={styles.btnText}>Toogle Status Bar (displayName opt)</Text>
			</TouchableOpacity>
			<TouchableOpacity onPress={() => FileViewerTest({ showOpenWithDialog: true, onDismiss: onDismissCb })} style={styles.btn}>
				<Text style={styles.btnText}>Toogle Status Bar (onDismiss)</Text>
			</TouchableOpacity>
			<TouchableOpacity onPress={() => FileViewerTest({ showOpenWithDialog: true })} style={styles.btn}>
				<Text style={styles.btnText}>Toogle Status Bar (showOpenWithDialog)</Text>
			</TouchableOpacity>
			<TouchableOpacity onPress={() => FileViewerTest({ showAppsSuggestions: true })} style={styles.btn}>
				<Text style={styles.btnText}>Toogle Status Bar (showAppsSuggestions)</Text>
			</TouchableOpacity>
		</ScrollView>
	);
}

const styles = StyleSheet.create({
	TextInput: {
		height: 40,
		borderColor: "#ccc",
		borderWidth: 1,
		borderRadius: 4,
		width: "90%"
	},
	btn: {
		borderRadius: 10,
		display: "flex",
		justifyContent: "center",
		alignItems: "center",
		padding: 10,
		margin: 10,
		backgroundColor: "blue"
	},
	btnText: {
		fontWeight: "bold",
		color: "#fff",
		fontSize: 20
	},
	selectBtn: {
		padding: 8,
		margin: 3,
		fontSize: 18,
		borderWidth: 1,
		borderRadius: 8,
		borderColor: "#753c13"
	},
	selectBtnActive: {
		padding: 8,
		margin: 3,
		backgroundColor: "#e2803b",
		fontSize: 18,
		borderRadius: 8,
		borderWidth: 1
	}
});

使用 Codegen

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

2. Linking

| | 是否支持autolink | RN框架版本 | |--------------------------------------|------------------|-----------| | ~2.3.0 | Yes | 0.82 | | ~2.2.0 | No | 0.77 | | ~2.1.7 | Yes | 0.72 | | <= 2.1.6@deprecated | No | 0.72 |

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

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

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

2.1. 在工程根目录的 `oh-package.json5` 添加 overrides 字段

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

2.2.引入原生端代码

目前有两种方法：

通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）；
直接链接源码。

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

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

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

"dependencies": {
    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
    "@react-native-ohos/react-native-file-viewer": "file:../../node_modules/@react-native-ohos/react-native-file-viewer/harmony/file_viewer.har"
  }

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

方法二：直接链接源码

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

2.3. 配置CMakeLists 和引入 FileViewerPackage

若使用的是 <= 2.1.6 版本，请跳过本章。

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

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
set(LOG_VERBOSITY_LEVEL 1)
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_compile_definitions(WITH_HITRACE_SYSTRACE)

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}/@react-native-ohos/react-native-file-viewer/src/main/cpp" ./file-viewer)
# RNOH_END: manual_package_linking_1

file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")

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_file_viewer)
# RNOH_END: manual_package_linking_2

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

#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
#include "SamplePackage.h"
+ #include "FileViewerPackage.h"

using namespace rnoh;

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

2.4. 在 ArkTs 侧引入 RNFileViewerTurboModule Package

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

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

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

2.5. 运行

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

然后编译、运行即可。

3. 约束与限制

3.1 兼容性

要使用此库，需要使用正确的 React-Native 和 RNOH 版本。另外，还需要使用配套的 DevEco Studio 和手机 ROM。

在以下版本验证通过：

RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
RNOH: 0.72.33; SDK: HarmonyOS NEXT B1; IDE: DevEco Studio: 5.0.3.900; ROM: Next.0.0.71;
RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
RNOH: 0.82.7; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;

4. 属性

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

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

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ---------------- | ------------ | ------ | -------- | -------- | ----------------- | | displayName (optional) | 自定义QuickLook标题 | string | no | iOS | yes | | onDismiss (optional) | 当查看器被关闭时调用的回调函数。 | function | no | All | partially | | showOpenWithDialog (optional) | 如果有多个应用可以打开文件，显示“打开方式”对话框。 | boolean | no | Android | yes | | showAppsSuggestions (optional) | 如果没有安装可以打开文件的应用，打开应用商店并显示推荐应用。 | boolean | no | Android | partially |

5. API

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

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

`open(filepath: string, options?: Object): Promise<void>`

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ---------------- | ------------ | ------ | -------- | -------- | ----------------- | | filepath | 文件存储的绝对路径。文件需要有有效的扩展名才能被成功检测。使用 react-native-fs constants 来正确确定绝对路径。 | string | yes | All | yes | | options (optional) | 用于自定义行为的一些选项。详见下文。 | Object | no | All | yes |

6. 遗留问题

[x] HarmonyOS端暂不支持关闭预览窗口的回调函数调用: issue#1
[x] HarmonyOS端无法直接跳转到应用市场的推荐应用页，目前只能跳转到应用市场首页: issue#2

7. 其他

OpenHarmony API 24 升级到 OpenHarmony API 26 后选择打开方式弹窗新增了始终和仅此一次两个按钮，实际的现象发生变更，如下：

系统检查是否有该 MIME 类型的默认应用，如果有默认应用时，直接启动默认应用（不弹框）；
系统检查是否有该 MIME 类型的默认应用，如果只有一个匹配应用时，直接启动该应用；
系统检查是否有该 MIME 类型的默认应用，如果多个匹配应用，无默认，弹出应用选择对话框。

点击"仅此一次"按钮：本次使用选中应用，不保存为默认，下次仍弹框。
点击"始终"按钮：保存为默认应用，下次直接打开该应用。
点击"取消"按钮：关闭对话框。

8. 开源协议

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