一、插件介绍

fluttertpc_file_preview 是一款基于 Flutter 开发的跨平台文件预览插件，专门为 HarmonyOS 平台进行了适配。该插件支持预览多种文件格式，包括 PDF、DOCX、TXT 等常见文档类型，为开发者提供了便捷的文件预览解决方案。

核心功能

• 多格式支持：支持 PDF、DOCX、TXT 等多种常见文档格式的预览
• 跨平台兼容：已适配 Android、iOS 和 HarmonyOS 平台
• 控制器支持：提供控制器用于动态切换文件
• 回调监听：支持监听文件预览的各种状态（显示、下载进度、失败等）
• 网络与本地文件：同时支持网络文件（HTTP/HTTPS）和本地文件预览

二、安装与配置

2.1 环境要求

• Flutter: 3.7.12-ohos-1.1.3 或 3.22.1-ohos-1.0.3
• HarmonyOS SDK: 5.0.0(12)
• DevEco Studio: 5.1.0.828

2.2 依赖配置

在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  fluttertpc_file_preview:
    git:
      url: "https://atomgit.com/openharmony-sig/fluttertpc_file_preview.git"
      path: "ohos"

然后执行以下命令获取依赖：

flutter pub get

三、API 使用指南

3.1 导入包

import 'package:fluttertpc_file_preview/file_preview.dart';

3.2 基本使用 - FilePreviewWidget

FilePreviewWidget 是主要的文件预览组件，用于在界面上显示文件内容。

FilePreviewWidget(
  width: MediaQuery.of(context).size.width,
  height: MediaQuery.of(context).size.height - kToolbarHeight,
  path: 'https://example.com/sample.pdf',
  callBack: FilePreviewCallBack(
    onShow: () {
      print('文件开始显示');
    },
    onDownload: (progress) {
      print('文件下载进度: $progress%');
    },
    onFail: (code, message) {
      print('文件预览失败: $code - $message');
    },
  ),
)

3.3 使用控制器 - FilePreviewController

FilePreviewController 用于控制文件预览组件，例如切换显示的文件。

// 创建控制器
final FilePreviewController _controller = FilePreviewController();

// 在组件中使用控制器
FilePreviewWidget(
  width: MediaQuery.of(context).size.width,
  height: MediaQuery.of(context).size.height - kToolbarHeight,
  path: 'https://example.com/sample1.pdf',
  controller: _controller,
  callBack: FilePreviewCallBack(
    onShow: () {
      print('文件开始显示');
    },
  ),
)

// 切换文件
_controller.showFile('https://example.com/sample2.pdf');

3.4 监听预览事件 - FilePreviewCallBack

FilePreviewCallBack 用于监听文件预览过程中的各种事件：

FilePreviewCallBack(
  // 文件开始显示时触发
  onShow: () {
    print('文件预览已显示');
  },
  // 文件下载进度更新时触发
  onDownload: (progress) {
    print('下载进度: $progress%');
    // 可以在这里更新UI显示下载进度
  },
  // 文件预览失败时触发
  onFail: (code, message) {
    print('预览失败: $code - $message');
    // 可以在这里处理失败情况，例如显示错误提示
  },
)

3.5 支持的文件路径格式

插件支持两种格式的文件路径：

1. 网络文件：以 HTTP/HTTPS 开头的远程文件地址

   path: 'https://example.com/sample.pdf'
   

2. 本地文件：设备本地的绝对文件路径

   path: '/storage/emulated/0/Download/sample.pdf'
   

四、HarmonyOS 平台注意事项

4.1 权限配置

在 HarmonyOS 平台上，需要在 module.json5 文件中配置必要的权限：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

4.2 不支持的功能

以下功能在 HarmonyOS 平台上暂不支持：

• TBS 相关功能（initTBS、tbsHasInit、tbsVersion）

五、完整示例

以下是一个完整的 HarmonyOS 平台使用示例：

import 'package:flutter/material.dart';
import 'package:fluttertpc_file_preview/file_preview.dart';

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'File Preview Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const FilePreviewPage(),
    );
  }
}

class FilePreviewPage extends StatefulWidget {
  const FilePreviewPage({Key? key}) : super(key: key);

  @override
  State<FilePreviewPage> createState() => _FilePreviewPageState();
}

class _FilePreviewPageState extends State<FilePreviewPage> {
  final FilePreviewController _controller = FilePreviewController();
  String _currentFile = 'https://example.com/file_test.pdf';

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('文件预览'),
        actions: [
          PopupMenuButton(
            itemBuilder: (context) => [
              const PopupMenuItem(
                value: 'pdf',
                child: Text('PDF文件'),
              ),
              const PopupMenuItem(
                value: 'txt',
                child: Text('TXT文件'),
              ),
            ],
            onSelected: (value) {
              if (value == 'pdf') {
                _currentFile = 'https://example.com/file_test.pdf';
              } else if (value == 'txt') {
                _currentFile = 'https://example.com/file_test.txt';
              }
              _controller.showFile(_currentFile);
            },
          ),
        ],
      ),
      body: Center(
        child: FilePreviewWidget(
          width: MediaQuery.of(context).size.width,
          height: MediaQuery.of(context).size.height - kToolbarHeight,
          path: _currentFile,
          controller: _controller,
          callBack: FilePreviewCallBack(
            onShow: () {
              print('文件开始显示');
            },
            onDownload: (progress) {
              print('文件下载进度: $progress%');
            },
            onFail: (code, message) {
              print('文件预览失败: $code - $message');
            },
          ),
        ),
      ),
    );
  }
}

六、总结

fluttertpc_file_preview 是一款功能强大的跨平台文件预览插件，为 HarmonyOS 平台提供了便捷的文件预览解决方案。其主要优势包括：

1. 简单易用：提供简洁的 API 接口，易于集成和使用
2. 多格式支持：支持多种常见文档格式的预览
3. 跨平台兼容：同时支持 Android、iOS 和 HarmonyOS 平台
4. 动态控制：通过控制器可以动态切换文件
5. 事件监听：提供完整的回调机制，便于处理预览状态

该插件可以帮助开发者快速实现文件预览功能，提高应用的用户体验。

---

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