本教程旨在解决 ionic capacitor 应用中打开 pdf 文件的常见问题，特别是当开发者错误地使用了基于 cordova 的 `@ionic-native` 插件时。文章将详细指导如何采用 capacitor 原生文件打开插件（如 capawesome file opener），并结合 capacitor 文件系统插件处理应用资产，实现从插件安装、资产文件复制到最终在移动设备上成功预览 pdf 的完整流程，确保开发者能够构建稳定高效的解决方案。
1. 理解问题根源：为何 Cordova 插件在 Capacitor 中失效？
在 Ionic Capacitor 项目中，尝试使用 @ionic-native/file-opener/ngx 和 @ionic-native/file/ngx 等插件来打开 PDF 文件时，经常会遇到类似 "Cordova is not available" 的错误信息。这通常是因为 @ionic-native 插件本质上是针对 Cordova 插件的 Angular 包装器。虽然 Capacitor 提供了兼容层来支持部分 Cordova 插件，但在许多情况下，尤其是在没有正确配置 Cordova 环境或直接在 Capacitor 原生运行时，这些插件无法正常工作。Capacitor 推荐使用其官方或社区维护的 Capacitor 原生插件，它们直接与平台的原生 API 交互，提供更好的兼容性和性能。
2. 选择合适的 Capacitor 原生文件打开插件
为了在 Ionic Capacitor 应用中可靠地打开 PDF 文件，我们应转向使用专为 Capacitor 设计的原生插件。这里推荐使用 Capawesome File Opener 或 Capacitor Community File Opener。本教程将以 Capawesome File Opener 为例进行讲解。
2.1 插件安装
首先，我们需要安装 Capawesome File Opener 插件。
npm install @capawesome-plugins/file-opener npx cap sync
2.2 安装文件系统插件 (用于处理资产文件)
直接访问打包在 assets 目录中的文件在移动设备上是不可行的，因为这些文件在设备上并没有一个可直接通过文件系统路径访问的独立位置。我们需要将这些资产文件（如 PDF）复制到设备上的一个临时目录（例如数据目录或缓存目录），然后才能使用文件打开插件进行访问。为此，我们需要安装 Capacitor 的文件系统插件：
npm install @capacitor/filesystem npx cap sync
3. 实现 PDF 文件预览功能
在安装完必要的插件后，我们现在可以着手实现 PDF 文件的预览功能。
3.1 导入所需模块
在您的组件中，导入 Filesystem 和 FileOpener 模块。
import { Component } from '@angular/core';
import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';
import { FileOpener } from '@capawesome-plugins/file-opener';
import { Platform } from '@ionic/angular'; // 用于判断平台3.2 将 PDF 资产文件复制到设备可访问目录
以下是实现将 assets 目录中的 PDF 文件复制到设备数据目录的步骤和代码示例。
@Component({
selector: 'app-open-pdf',
templateUrl: './open-pdf.page.html',
styleUrls: ['./open-pdf.page.scss'],
})
export class OpenPdfPage {
constructor(private platform: Platform) {}
async openPdf() {
if (this.platform.is('hybrid')) { // 确保只在原生平台运行
const pdfAssetPath = 'assets/documents/mizzica.pdf'; // 您的 PDF 文件路径
try {
// 1. 从 assets 目录读取 PDF 文件内容
// 注意：在 Capacitor 中，直接通过文件路径读取 assets 目录下的文件需要特殊处理
// 最常见的方法是通过 fetch API 读取，因为 assets 文件在打包后可通过 HTTP 路径访问
const response = await fetch(pdfAssetPath);
const blob = await response.blob();
// 2. 将 Blob 转换为 Base64 字符串（Filesystem.writeFile 需要）
const reader = new FileReader();
reader.readAsDataURL(blob);
reader.onloadend = async () => {
const base64data = reader.result as string;
// 移除 Data URL 前缀，只保留 Base64 数据
const base64Content = base64data.split(',')[1];
// 3. 将 Base64 内容写入到设备的数据目录
const fileName = 'mizzica.pdf';
const filePath = `${Directory.Data}/${fileName}`;
await Filesystem.writeFile({
path: fileName,
data: base64Content,
directory: Directory.Data,
encoding: Encoding.Base64,
recursive: true // 确保父目录存在
});
// 4. 使用 FileOpener 插件打开复制的文件
await FileOpener.open({
path: filePath,
mimeType: 'application/pdf',
});
console.log('PDF 文件已成功打开');
};
reader.onerror = (e) => {
console.error('读取 Blob 失败', e);
};
} catch (error) {
console.error('打开 PDF 失败:', error);
}
} else {
console.warn('此功能仅在原生设备上可用。');
// 可以在此处为 Web 平台提供替代方案，例如使用 iframe 或第三方 PDF 查看器
}
}
}3.3 HTML 触发按钮
在您的 open-pdf.page.html 文件中添加一个按钮来触发 openPdf 方法：
<ion-header [translucent]="true">
<ion-toolbar>
<ion-title>PDF 预览</ion-title>
</ion-toolbar>
</ion-header>
<ion-content [fullscreen]="true">
<ion-header collapse="condense">
<ion-toolbar>
<ion-title size="large">PDF 预览</ion-title>
</ion-toolbar>
</ion-header>
<ion-button (click)="openPdf()">打开 PDF</ion-button>
</ion-content>4. 注意事项与最佳实践
- 平台判断： 使用 Platform 服务判断当前运行环境是否为原生平台 (this.platform.is('hybrid'))，因为文件操作插件通常只在 iOS 和 Android 等原生环境有效。
- 文件路径： 强调 assets 路径在 Web 和原生环境中的差异。在 Web 环境下，assets 可以通过相对 URL 访问；但在原生环境中，它们是打包到应用内部的资源，不能直接通过文件系统路径访问。因此，将它们复制到设备可访问的目录是关键一步。
- 权限管理： Filesystem 插件通常会自动处理 Android 上的存储权限（尤其是针对应用私有目录 Directory.Data 或 Directory.Cache）。对于公共存储，可能需要额外的权限请求。FileOpener 插件通常不需要额外权限，因为它只是调用系统默认的打开方式。
- 错误处理： 在实际应用中，务必使用 try-catch 块来捕获可能发生的错误，例如文件不存在、权限不足或文件打开失败等。
- 临时文件清理： 如果将文件复制到 Directory.Cache 目录，可以考虑在不再需要时清理这些临时文件，以节省存储空间。Directory.Data 目录下的文件通常是应用数据，可以长期保留。
- MIME 类型： 确保 FileOpener.open 方法中的 mimeType 参数正确。对于 PDF 文件，应为 application/pdf。
- Web 平台替代方案： 对于 Web 浏览器环境，您可能需要提供不同的 PDF 预览方案，例如使用 <iframe> 标签加载 PDF，或者集成一个 JavaScript PDF 查看器库（如 PDF.js）。
5. 总结
在 Ionic Capacitor 应用中打开 PDF 文件，关键在于避免使用过时的 Cordova 插件，转而采用 Capacitor 原生插件。通过结合 Capacitor Filesystem 插件将 assets 目录中的 PDF 文件复制到设备可访问的临时位置，然后使用 Capawesome File Opener 等插件来调用系统默认的 PDF 查看器，可以构建一个稳定且兼容性强的解决方案。始终记住处理好文件路径、平台差异和错误，以提供良好的用户体验。
