Flutter for OpenHarmony PDF 预览功能落地实现指南

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

结合你当前的代码骨架和鸿蒙社区适配现状，我帮你把这个 PDF 预览功能从「骨架」补全为「可验证的工程方案」，同时对齐你的征文规范和鸿蒙适配要求。
一、当前方案适配性梳理 ✅
已完成的正确改动
架构分层清晰：将 PDF 相关逻辑全部封装在 lib/pdf_feature.dart，与首页 UI 解耦，便于后续替换底层库
依赖精简：移除了鸿蒙端未适配的 pdfx/native_pdf_renderer，仅保留 flutter_pdfview（有社区鸿蒙适配版）、path_provider（鸿蒙已适配）
错误修复：
补充 path_provider 导入，确保 getTemporaryDirectory() 可用
删除了残留的 _controller 清理代码，避免无定义字段报错
核心能力骨架完整：本地选择 / 网络下载 / 分页浏览 / 文本提取的逻辑框架已保留，后续只需替换底层实现
二、鸿蒙适配关键补充（必做）⚠️

1. 依赖替换：使用鸿蒙适配版 flutter_pdfview
   你当前的 pubspec.yaml 依赖需要替换为社区适配的鸿蒙版本，否则会出现构建失败：

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  # 替换为鸿蒙适配版 flutter_pdfview
  flutter_pdfview_ohos:
    git:
      url: https://gitcode.com/openharmony-sig/fluttertpc_flutter_pdfview.git
      path: ohos
  path_provider: ^2.1.0 # 鸿蒙已适配
  dio: ^5.4.0 # 用于网络 PDF 下载（鸿蒙兼容）
  file_picker: ^6.1.1 # 鸿蒙端文件选择器，替代原生选择逻辑

注：flutter_pdfview_ohos 是 OpenHarmony SIG 社区维护的适配版本，支持鸿蒙 4.0+ 设备，是目前最稳定的 PDF 预览方案。
2. 权限与沙箱适配（鸿蒙特有）
在 module.json5 中补充以下权限，否则无法读取本地文件和网络下载：

{
  "module": {
    "reqPermissions": [
      {
        "name": "ohos.permission.READ_MEDIA"
      },
      {
        "name": "ohos.permission.WRITE_MEDIA"
      },
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

同时，在文件读取逻辑中，必须使用鸿蒙沙箱路径映射，避免直接访问 /storage 路径：

// lib/pdf_feature.dart 中路径处理逻辑示例
import 'package:path_provider/path_provider.dart';
import 'package:file_picker/file_picker.dart';

Future<String?> pickLocalPdf() async {
  // 使用 file_picker 选择文件，自动适配鸿蒙沙箱
  final result = await FilePicker.platform.pickFiles(
    type: FileType.custom,
    allowedExtensions: ['pdf'],
  );
  if (result != null && result.files.single.path != null) {
    return result.files.single.path;
  }
  return null;
}

三、核心功能实现补全（适配鸿蒙）

1. 网络 PDF 下载与缓存

// lib/pdf_feature.dart
import 'package:dio/dio.dart';
import 'package:path_provider/path_provider.dart';
import 'dart:io';

Future<String> downloadAndCachePdf(String url) async {
  final tempDir = await getTemporaryDirectory();
  final filePath = '${tempDir.path}/cached_${DateTime.now().millisecondsSinceEpoch}.pdf';
  
  await Dio().download(url, filePath);
  return filePath;
}

2.首页集成 PdfPreviewCard

// lib/main.dart
import 'package:flutter/material.dart';
import 'pdf_feature.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Flutter 鸿蒙 PDF 预览')),
        body: const PdfPreviewCard(),
      ),
    );
  }
}

class PdfPreviewCard extends StatefulWidget {
  const PdfPreviewCard({super.key});

  @override
  State<PdfPreviewCard> createState() => _PdfPreviewCardState();
}

class _PdfPreviewCardState extends State<PdfPreviewCard> {
  String? _pdfPath;
  int _currentPage = 0;
  String? _pageText;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Row(
          mainAxisAlignment: MainAxisAlignment.spaceEvenly,
          children: [
            ElevatedButton(
              onPressed: () async {
                final path = await pickLocalPdf();
                if (path != null) setState(() => _pdfPath = path);
              },
              child: const Text('选择本地 PDF'),
            ),
            ElevatedButton(
              onPressed: () async {
                // 替换为你的示例 PDF 链接
                const exampleUrl = 'https://example.com/sample.pdf';
                final path = await downloadAndCachePdf(exampleUrl);
                setState(() => _pdfPath = path);
              },
              child: const Text('加载示例网络 PDF'),
            ),
          ],
        ),
        if (_pdfPath != null) ...[
          Expanded(
            child: PdfView(
              path: _pdfPath!,
              onPageChanged: (page, total) async {
                setState(() => _currentPage = page);
                // 提取当前页文本
                final text = await extractPdfText(_pdfPath!, pageIndex: page);
                setState(() => _pageText = text);
              },
            ),
          ),
          if (_pageText != null)
            Padding(
              padding: const EdgeInsets.all(8.0),
              child: Text(
                '第${_currentPage + 1}页文本：\n$_pageText',
                maxLines: 5,
                overflow: TextOverflow.ellipsis,
              ),
            ),
        ],
      ],
    );
  }
}

四、鸿蒙真机验证步骤（按顺序执行）
构建前检查：
执行 hvigor clean 清理缓存
运行 flutter pub get 确保依赖下载完成
确认 flutter_pdfview_ohos 依赖已拉取成功
真机部署验证：
启动应用，确认首页 PdfPreviewCard 正常渲染，无白屏 / 崩溃
点击「选择本地 PDF」，测试沙箱文件读取，确认文件选择器正常唤起
点击「加载示例网络 PDF」，观察下载进度和缓存文件生成，确认加载成功
左右滑动翻页，检查 PdfView 分页控制是否流畅
查看文本区域，确认当前页文本能正常提取并展示
边界场景测试：
拒绝文件 / 网络权限，检查报错提示是否友好
加载超大 PDF（10MB+），测试内存占用和加载性能
加载损坏的 PDF 文件，确认应用不会崩溃