fluttertpc_pdf_viewer_plugin 在鸿蒙系统上的使用指南

摘要：fluttertpc_pdf_viewer_plugin 是一款专为鸿蒙系统适配的 Flutter PDF 查看器插件，支持本地 PDF 文件浏览、缩放滚动等基础功能。通过 Git 依赖方式集成，兼容 Flutter 3.7+ 和 DevEco Studio 5.1。核心组件 PdfView 提供文件路径和手势识别配置，需注意仅支持本地文件访问，网络文件需先下载。该插件以轻量易用为特点，适合

Luff773

397人浏览 · 2025-12-19 22:27:04

Luff773 · 2025-12-19 22:27:04 发布

1. 插件介绍

fluttertpc_pdf_viewer_plugin 是一个基于 pdf_viewer_plugin 开发的 Flutter PDF 查看器插件，专门针对鸿蒙（HarmonyOS）系统进行了定制和适配。该插件提供了一种简单直观的方式，让开发者能够在 Flutter 应用中轻松集成 PDF 文档查看功能。

主要功能特点

支持在鸿蒙系统上显示本地 PDF 文件
提供基本的 PDF 文档浏览功能（缩放、滚动等）
支持自定义手势识别
轻量级设计，易于集成

2. 安装与配置

2.1 添加依赖

由于这是一个自定义修改版本的插件，需要通过 Git 形式引入。在项目的 pubspec.yaml 文件中添加以下配置：

dependencies:
  pdf_viewer_plugin:
    git:
      url: "https://gitcode.com/openharmony-sig/fluttertpc_pdf_viewer_plugin.git"

然后执行命令：

flutter pub get

2.2 兼容性要求

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

Flutter: 3.7.12-ohos-1.1.3; SDK: 5.0.0(12)
Flutter: 3.22.1-ohos-1.0.3; SDK: 5.0.0(12)
IDE: DevEco Studio: 5.1.0.828; ROM: 5.1.0.130 SP8

3. API 使用

3.1 主要组件

PdfView 是插件提供的核心组件，用于在 Flutter 应用中显示 PDF 文档。

3.2 组件属性

属性名称	类型	描述	鸿蒙支持情况
path	String	PDF 文件路径	yes
gestureRecognizers	Set<Factory>?	手势集合，为空时仅处理未被其他手势识别器声明的指针事件	yes
gestureNavigationEnabled	double?	水平滑动手势是否触发前后列表导航（仅 iOS 支持）	no

3.3 基本用法

import 'package:flutter/material.dart';
import 'package:pdf_viewer_plugin/pdf_viewer_plugin.dart';

class PdfApp extends StatelessWidget {
  const PdfApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('PDF Viewer')),
        body: PdfView(path: 'pdf_file_path'),
      ),
    );
  }
}

4. 完整示例

下面是一个完整的示例，展示了如何在鸿蒙系统上使用 fluttertpc_pdf_viewer_plugin 插件下载并显示网络上的 PDF 文件：

import 'dart:async';
import 'dart:io';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:path_provider/path_provider.dart';
import 'package:pdf_viewer_plugin/pdf_viewer_plugin.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  // 示例 PDF 文件 URL
  final sampleUrl = 'https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf';

  String? pdfFilePath;

  // 下载并保存 PDF 文件
  Future<String> downloadAndSavePdf() async {
    final directory = await getApplicationDocumentsDirectory();
    final file = File('${directory.path}/sample.pdf');

    // 如果文件已存在，直接返回路径
    if (await file.exists()) {
      return file.path;
    }

    // 下载文件
    final response = await http.get(Uri.parse(sampleUrl));

    // 保存文件到应用文档目录
    await file.writeAsBytes(response.bodyBytes);
    return file.path;
  }

  // 加载 PDF 文件
  void loadPdf() async {
    pdfFilePath = await downloadAndSavePdf();
    setState(() {});
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Builder(builder: (context) {
        return Scaffold(
          backgroundColor: Colors.black,
          appBar: AppBar(
            title: Text('PDF Viewer 示例'),
          ),
          body: Center(
            child: Column(
              children: <Widget>[
                // 加载 PDF 按钮
                ElevatedButton(
                  child: Text("加载 PDF"),
                  onPressed: loadPdf,
                ),

                // PDF 查看区域
                if (pdfFilePath != null)
                  Expanded(
                    child: Container(
                      child: PdfView(path: pdfFilePath!),
                    ),
                  )
                else
                  Text("PDF 文件未加载"),
              ],
            ),
          ),
        );
      }),
    );
  }
}

5. 注意事项

文件路径要求：path 参数必须指向设备本地的 PDF 文件，不支持直接加载网络 PDF 文件。如需加载网络 PDF，需先下载到本地存储。
权限配置：
- 如果需要从网络下载 PDF 文件，需确保应用已获取网络权限
- 如果需要访问外部存储的 PDF 文件，需确保应用已获取存储权限
性能考量：
- 对于大型 PDF 文件，可能会占用较多内存，建议根据实际需求进行优化
- 建议在使用完成后及时释放资源
平台差异：
- 部分属性（如 gestureNavigationEnabled）仅支持特定平台，鸿蒙系统上不支持
- 手势处理逻辑可能与其他平台存在细微差异