@capacitor/file-viewer

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/file-viewer 是 capacitor 生态系统中的插件，用于提供打开文件和预览媒体的功能，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台，本文档主要说明在 OpenHarmony 系统中的使用。

该插件支持从本地文件系统、应用资源、远程 URL 打开和预览各种类型的文件，满足应用中文件查看、媒体预览等场景需求。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/file-viewer

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/file-viewer

手动引入安装

根据插件源码中 plugin.xml 配置在项目中添加/修改相关配置：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置：

{
    "pkg": "@capacitor/file-viewer",
    "classpath": "FileViewer"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，找到 capacitor 模块，路径为 target 字段的文件 CMakeLists.txt，添加 add_subdirectory，同时添加 target_link_libraries：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(FileViewer)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  FileViewer
  // ...
  "-Wl,--no-whole-archive"
);

3. 复制源码文件

根据 plugin.xml 的 source-file 项，将 src 字段的路径代码复制到 capacitor 模块中 target-dir 字段的目录中：

将源码中 src/main/cpp/FileViewer 目录下的 FileViewer.h、FileViewer.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/FileViewer 目录下。

将源码中 src/main/ets/components/FileViewer 目录下的 FileViewer.ets 文件引入到 capacitor 模块中 src/main/ets/components/FileViewer 目录下。

4. 添加 ArkTS 配置

在 capacitor 模块的 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

"buildOption": {
  // ...
   "arkOptions": {
      "runtimeOnly":[
      // ...
          "./src/main/ets/components/FileViewer/FileViewer.ets"
      // ...
      ]
   }
}

卸载

# 卸载 file-viewer 插件
hionic plugin remove @capacitor/file-viewer

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

使用示例

示例：打开本地文件 / 预览远程 URL 文件

import { FileViewer } from "@capacitor/file-viewer";

// can use a plugin like @capacitor/filesystem to get the full path to the file
const openDocument = async () => {
  await FileViewer.openDocumentFromLocalPath({
    path: "path/to/file.pdf"
  });
};

// Preview media from URL
const previewMedia = async () => {
  await FileViewer.previewMediaContentFromUrl({
    url: "https://url_hosting_media/file.mp4"
  });
};

使用说明

接口方法

| 方法名 | 返回类型 | 描述 | | ---- | ---- | ---- | | openDocumentFromLocalPath(options: OpenFromLocalPathOptions) | Promise<void> | 打开存储在本地文件系统中的文件 | | openDocumentFromResources(options: OpenFromResourcesOptions) | Promise<void> | 打开应用程序资源文件 | | openDocumentFromUrl(options: OpenFromUrlOptions) | Promise<void> | 从远程 URL 打开文件 | | previewMediaContentFromLocalPath(options: PreviewMediaFromLocalPathOptions) | Promise<void> | 预览存储在本地文件系统中的媒体文件，OpenHarmony 默认使用 openDocumentFromLocalPath | | previewMediaContentFromResources(options: PreviewMediaFromResourcesOptions) | Promise<void> | 预览应用资源中的媒体文件，OpenHarmony 默认使用 openDocumentFromResources | | previewMediaContentFromUrl(options: PreviewMediaFromUrlOptions) | Promise<void> | 预览来自远程 URL 的媒体文件，OpenHarmony 默认使用 openDocumentFromUrl |

数据结构

OpenFromLocalPathOptions/PreviewMediaFromLocalPathOptions

打开本地文件选项：

| 属性名 | 类型 | 描述 | | ---------- | ------ | --------------------------- | | path | string | 要打开的文件的完整路径 |

OpenFromResourcesOptions/PreviewMediaFromResourcesOptions

打开应用资源文件选项：

| 属性名 | 类型 | 描述 | | ---------- | ------ | -------------------------- | | path | string | 要打开的资源文件的相对路径 |

OpenFromUrlOptions/PreviewMediaFromUrlOptions

打开远程文件选项：

| 属性名 | 类型 | 描述 | | --------- | ------ | -------------------------- | | url | string | 指向要打开的文件的远程 URL |

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- FileViewer   # 插件核心 C++ 实现
|                             |---- FileViewer.cpp
|                             |---- FileViewer.h
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- FileViewer   # ArkTS 组件实现
|                                   |---- FileViewer.ets
|     |---- README.md              # 说明文档
|     |---- package.json           # npm 配置文件
|     |---- plugin.xml            # capacitor 插件配置
|     |---- LICENSE               # 许可证文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。