@wisdomgarden/cloak-plugin-file-preview

v0.0.1

Published

5 days ago

A File preview Plugin of Cloak framework(A Hybrid Development Framework for HarmonyOS)

Downloads

FilePreview 插件

用于预览沙箱中已有的文档（pdf/office/图片/音视频/txt 等），底层调用 HarmonyOS 系统的 Preview Kit。插件不下载、不落盘、不读文件内容，也不自己渲染；canPreview 的结果如实上报，不做静默降级。

安装

ohpm install @wisdomgarden/cloak-plugin-file-preview

# 可选，用于 TypeScript 类型
npm install @wisdomgarden/cloak-plugin-file-preview

不需要声明任何权限：预览的是应用自己沙箱里的文件，系统靠 uri 临时授权。

在 EntryAbility.ets 中注册：

import { CloakPluginFilePreview } from '@wisdomgarden/cloak-plugin-file-preview';

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  new Cloak(this, [
    // ... 其他插件
    new CloakPluginFilePreview(),
  ]);
}

使用方法

const preview = Cloak.plugins.FilePreview;

// 典型链路：先用 FileTransfer 下载到沙箱，再交给 FilePreview
const { path } = await Cloak.plugins.FileTransfer.downloadFile({ url, path: 'downloads/a.pdf', directory: 'DATA' });

// mimeType 建议从下载响应头的 Content-Type 传进来，比按扩展名猜准
const { canPreview, mimeType } = await preview.canPreview({ path, mimeType: 'application/pdf' });

if (canPreview) {
  await preview.preview({ path, title: 'a.pdf' });
} else {
  // canPreview 为 false 时插件不会替你降级，由 H5 决定走 openWith 还是提示用户
  const opened = await preview.openWith({ path, mimeType });
  if (!opened) {
    console.log('没有能打开这个文件的应用');
  }
}

// 预览窗没有关闭回调，只能主动查询
const displayed = await preview.isDisplayed();

// H5 自己要收起预览时才用，比如路由跳走
await preview.close();

// 失败时 reject 一个带 code 的错误
try {
  await preview.preview({ path, mimeType });
} catch (e) {
  console.error(e.code, e.uri); // OS-PLUG-PRVW-0007 file://...
}

API

方法失败时 reject 的错误见错误码。

canPreview

canPreview(options: PreviewTargetOptions): Promise<CanPreviewResult>;

询问系统能否预览这个文件，不会打开任何界面。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | PreviewTargetOptions | 是 | 目标文件 |

返回值：Promise<CanPreviewResult>

preview

preview(options: PreviewOptions): Promise<void>;

打开系统预览窗。内部会先做一次 canPreview，结果为 false 时以 OS-PLUG-PRVW-0007 拒绝，不会弹出空白窗。

1 秒内重复调用会被系统去抖：不会开出第二个窗，但这次调用本身不算失败，Promise 正常 resolve。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | PreviewOptions | 是 | 预览参数 |

返回值：Promise<void>

close

close(): Promise<void>;

关闭当前预览窗。仅用于 H5 主动收起预览（比如路由跳走）——系统没有"用户关闭了预览窗"的回调，插件也就没法主动通知 H5。

返回值：Promise<void>

isDisplayed

isDisplayed(): Promise<boolean>;

查询当前是否有预览窗正开着。想知道预览窗有没有被用户关掉，只能靠轮询这个方法。

返回值：Promise<boolean>

openWith

openWith(options: PreviewTargetOptions): Promise<boolean>;

canPreview 为 false 的格式（zip、apk、冷门后缀……）的兜底方案：通过隐式 Intent 交给系统里的第三方应用打开。找不到能打开该文件的应用时以 OS-PLUG-PRVW-0009 拒绝。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | PreviewTargetOptions | 是 | 目标文件 |

返回值：Promise<boolean>

接口

PreviewTargetOptions

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | path | string | 是 | 沙箱绝对路径，或 file:// uri（比如 Filesystem.getUri 的返回值），两种都收 | | mimeType | string | 否 | 不给则按扩展名猜；下载时从响应头 Content-Type 拿到的更准，建议优先传 |

不给 path 会以 OS-PLUG-PRVW-0004 拒绝。

PreviewOptions

在 PreviewTargetOptions 基础上增加：

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | title | string | 否 | 预览窗标题，不给则系统取文件名 | | display | DisplayInfo | 否 | 预览窗位置/尺寸，平板和 2in1 上有用，手机上一般不传 |

DisplayInfo

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | x | number | 是 | 预览窗 X 坐标，单位 px | | y | number | 是 | 预览窗 Y 坐标，单位 px | | width | number | 否 | 预览窗宽度，单位 px | | height | number | 否 | 预览窗高度，单位 px |

CanPreviewResult

| 字段 | 类型 | 说明 | |---|---|---| | canPreview | boolean | 能否预览，如实上报，插件内部不做静默 fallback | | uri | string | 归一化后的 file:// uri，可以直接作为 path 传给后续的 preview/openWith | | mimeType | string | 最终采用的 mimeType：传入的，或按扩展名猜的 |

FilePreviewError

所有方法失败时 reject 的对象。

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | code | string | 是 | 见错误码 | | message | string | 是 | 可读的失败原因 | | uri | string | 否 | 涉及的文件 uri，能定位到具体文件时才有 | | mimeType | string | 否 | 涉及的 mimeType，比如"格式不支持预览"时会带出来 | | exception | string | 否 | 鸿蒙侧的原始错误信息 |

错误码

| code | 说明 | |---|---| | OS-PLUG-PRVW-0004 | 入参非法：path 没给 | | OS-PLUG-PRVW-0005 | 路径非法：解析不出有效的沙箱绝对路径 | | OS-PLUG-PRVW-0006 | 文件不存在 | | OS-PLUG-PRVW-0007 | 该格式不支持预览（canPreview 为 false 时仍调用了 preview） | | OS-PLUG-PRVW-0008 | 系统不具备预览能力（非华为设备/裁剪过的系统缺少对应 syscap） | | OS-PLUG-PRVW-0009 | 没有应用能打开该文件（openWith 找不到匹配的 ability） | | OS-PLUG-PRVW-0010 | 其它错误，exception 里带鸿蒙原始错误 |

不支持的能力

loadData（预览窗已开时原地换一个文件）没有暴露：手机上 preview 打开的是系统全屏模态窗， H5 没有交互入口能在预览开着的时候触发它；平板分屏这种非模态场景也验证过，直接再调一次 preview 即可正常切换文件，没有找到 loadData 能解决而 preview 解决不了的场景。
多文件预览（openPreview(context, files, index)）没有实现：该形态是 API 12+ 且仅手机有效，版本与形态兼容性都还没铺开验证。
预览窗关闭事件：Preview Kit 本身不提供关闭回调，用户手动关掉预览窗时插件收不到通知，只能靠 isDisplayed() 轮询。

关于 Cloak

Cloak 是专为 HarmonyOS 设计的混合开发框架，类似 Cordova 和 Capacitor，但具备 更轻量、更高性能 的特性。

该框架可将 Web 应用快速转换为原生应用，同时通过插件机制访问 HarmonyOS 原生能力。

核心特性

快速打包：将 H5 应用快速编译为 HarmonyOS 应用。
原生能力访问：通过插件机制调用原生接口。
WebView 支持：提供高性能 WebView 容器，确保 H5 应用流畅运行。
插件开发：支持开发者自定义插件以扩展原生功能。

更多关于 Cloak 框架信息，请查看: https://github.com/WisdomGardenInc/Cloak