# ecp_file_view

**Repository Path**: kitman/ecp_file_view

## Basic Information

- **Project Name**: ecp_file_view
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ecp_file_view

[![pub package](https://img.shields.io/pub/v/ecp_file_view)](https://pub.dev/packages/ecp_file_view)

Language: 中文 | [English](README.md)

> 此库专为内部项目需求设计，若不符合您的使用场景，敬请谅解。

> 目前该插件仅限于 Android，iOS 使用

* 可使用 [LocalFileViewer](lib/src/view/local_file_viewer.dart) 实现本地文件预览。
* 可使用 [NetworkFileViewer](lib/src/view/network_file_viewer.dart) 实现网络链接下载，结合 `LocalFileViewer` 实现预览。

### 第三方使用

* 使用 `dio` 进行网络请求。
* 推荐使用 `getTemporaryDirectory()` 作为目标路径（使用[path_provider](https://pub.dev/packages/path_provider)插件可实现）。

## 准备工作

### 版本限制

```yaml
    sdk: ">=2.14.0 <4.0.0"
  flutter: ">=2.5.0"
```

### 添加依赖

1. 将 `ecp_file_view` 添加至 `pubspec.yaml` 引用

```yaml
dependencies:
  ecp_file_view: ^latest_version
```

2. 执行flutter命令获取包

```
flutter pub get
```

3. 引入

```dart
import 'package:ecp_file_view/ecp_file_view.dart';
```

### 本地化配置

在 `MaterialApp` 添加

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      ...
      localizationsDelegates: const <LocalizationsDelegate<dynamic>>[
        ...
        ViewerLocalizationsDelegate.delegate,
      ],
      ...
    );
  }
}
```

### iOS

请确保将以下键添加到 `Info.plist`

```
<key>io.flutter.embedded_views_preview</key><true/>
```

### Android

Android P 无法下载内核解决方案

在文件 `AndroidManifst.xml` 的标签 `application` 中添加代码

```
android:networkSecurityConfig="@xml/network_security_config"
android:usesCleartextTraffic="true"
```

在 `res/xml` 目录中添加一个名为 `network_security_config.xml` 的文件, 文件内容为

```xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true" />
</network-security-config>
```

在根目录 `build.gradle` 中添加 JitPack 仓库，否则 Gradle 无法解析 `com.github.Victor2018:DocViewer` 依赖：

```groovy
allprojects {
    repositories {
        // 国内推荐使用阿里云镜像
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://www.jitpack.io' }
    }
}
```

## 本地文件预览 - LocalFileViewer

> Android 由 [AndroidDocViewer](https://github.com/Victor2018/DocViewer)（`com.github.Victor2018:DocViewer`）实现，其 `DocView` 以 PlatformView 形式嵌入 Flutter Widget 树，行为与 iOS 一致

> iOS 由 [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview) 实现

### Android 宿主侧改造（AppCompatActivity 要求）

> AndroidDocViewer 的 `DocView` 构造时依赖 `(context as AppCompatActivity).lifecycleScope`，因此宿主 `Activity` **必须是 `AppCompatActivity`**，不能直接继承 `FlutterActivity`。若宿主当前使用 `FlutterActivity`，请按以下步骤改造：

**1. 添加 appcompat 依赖**（`android/app/build.gradle`）

```groovy
dependencies {
    implementation 'androidx.appcompat:appcompat:1.4.1'
}
```

**2. 修改主题**（`android/app/src/main/res/values/styles.xml`）

```xml
<!-- 注意：appcompat 1.3.0+ 已移除 NoTitleBar 主题，必须使用 NoActionBar -->
<style name="LaunchTheme" parent="Theme.AppCompat.Light.NoActionBar">
    <!-- ... -->
</style>

<style name="NormalTheme" parent="Theme.AppCompat.Light.NoActionBar">
    <!-- ... -->
</style>
```

**3. 改造 MainActivity**：改为 `AppCompatActivity` + `FlutterFragment`，并实现 `FlutterEngineConfigurator` 手动注册插件（`FlutterFragment` 不会像 `FlutterActivity` 那样自动注册插件，自 Flutter 3.22 起自动注册是 `FlutterActivity.configureFlutterEngine` 的职责，否则所有插件的 channel 无法连接）

```kotlin
package com.file.view.example

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import io.flutter.embedding.android.FlutterEngineConfigurator
import io.flutter.embedding.android.FlutterFragment
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugins.GeneratedPluginRegistrant

class MainActivity : AppCompatActivity(), FlutterEngineConfigurator {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        supportFragmentManager.beginTransaction()
            .replace(
                android.R.id.content,
                FlutterFragment.withNewEngine()
                    // 必须 attach 到 Activity，ActivityAware 插件（含本插件 PlatformView）才可用
                    .shouldAttachEngineToActivity(true)
                    // 新版 Flutter 默认支持 PlatformView，无需 usesPlatformView
                    .shouldDelayFirstAndroidViewDraw(true)
                    .build()
            )
            .commit()
    }

    /**
     * FlutterFragment 不会自动注册插件，必须手动注册，
     * 否则所有插件的 channel 都无法连接。
     */
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        GeneratedPluginRegistrant.registerWith(flutterEngine)
    }

    override fun cleanUpFlutterEngine(flutterEngine: FlutterEngine) {
        // 无需清理，保持默认空实现
    }
}
```

> 完整示例见 [MainActivity.kt](example/android/app/src/main/kotlin/com/file/view/example/MainActivity.kt)（插件内部已处理 PlatformView context 问题，宿主侧无需关心）

### 所支持的文件类型

* Android `docx,doc,xlsx,xls,pptx,ppt,pdf,txt`
* iOS `docx,doc,xlsx,xls,pptx,ppt,pdf,txt`

### 使用方法

| 参数名                       | 类型        | 描述                                                | 默认值                                                                           |
|---------------------------|-----------|---------------------------------------------------|-------------------------------------------------------------------------------|
| filePath                  | `String`  | 本地文件路径                                            | 必填项                                                                           |
| placeholder               | `Widget?` | 加载状态的部件                                           | `CupertinoActivityIndicator(radius: 14.0)`                                    |
| unsupportedPlatformWidget | `Widget?` | 在不支持的平台上显示的部件                                     | `Center(child: Text(ViewerLocalizations.of(context).unsupportedPlatformTip))` |
| nonExistentWidget         | `Widget?` | 当文件不存在时显示的部件                                      | `Center(child: Text(ViewerLocalizations.of(context).nonExistentTip))`         |
| unsupportedTypeWidget     | `Widget`  | 当文件为不支持的类型时显示的部件                                  | `Center(child: Text(ViewerLocalizations.of(context).unsupportedType))`        |
| isBarShow                 | `bool`    | 兼容保留，当前引擎未使用                                    | `false`                                                                       |
| intoDownloading           | `bool`    | 兼容保留，当前引擎未使用                                    | `false`                                                                       |
| isBarAnimating            | `bool`    | 兼容保留，当前引擎未使用                                    | `false`                                                                       |

## 网络链接视图 - NetworkFileViewer

基于微信 UI 的 **网络链接视图**，带有下载功能以及查看的点击效果

### 使用方法

| 参数名                     | 类型                      | 描述                                                  | 默认值                                                                           |
|-------------------------|-------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|
| downloadUrl             | `String`                | 下载文件链接                                              | 必填项                                                                           |
| downloadPath            | `String`                | 下载文件存储地址                                            | 必填项                                                                           |
| onViewPressed           | `VoidCallback`          | 文件查看功能                                              | 必填项                                                                           |
| placeholder             | `Widget?`               | 加载状态的部件                                             | `CupertinoActivityIndicator(radius: 14.0)`                                    |
| fileSizeData            | `dynamic`               | `FlutterFileView.getFileSize` 参数 `data`             | `null`                                                                        |
| fileSizeQueryParameters | `Map<String, dynamic>?` | `FlutterFileView.getFileSize` 参数 `queryParameters`  | `null`                                                                        |
| fileSizeOptions         | `Options?`              | `FlutterFileView.getFileSize` 参数 `options`          | `null`                                                                        |
| fileSizeTip             | `String?`               | `FlutterFileView.getFileSize` 参数 `fileSizeTip`      | `ViewerLocalizations.of(context).fileSizeTip`                                 |
| fileSizeFailTip         | `String?`               | `FlutterFileView.getFileSize` 参数 `fileSizeFailTip`  | `ViewerLocalizations.of(context).fileSizeFailTip`                             |
| fileSizeErrorTip        | `String?`               | `FlutterFileView.getFileSize` 参数 `fileSizeErrorTip` | `ViewerLocalizations.of(context).fileSizeErrorTip`                            |
| downloadQueryParameters | `Map<String, dynamic>?` | `FlutterFileView.downloadFile` 参数 `queryParameters` | `null`                                                                        |
| downloadDeleteOnError   | `bool?`                 | `FlutterFileView.downloadFile` 参数 `deleteOnError`   | `true`                                                                        |
| downloadLengthHeader    | `String?`               | `FlutterFileView.downloadFile` 参数 `lengthHeader`    | `Headers.contentLengthHeader`                                                 |
| downloadData            | `dynamic`               | `FlutterFileView.downloadFile` 参数 `data`            | `null`                                                                        |
| downloadOptions         | `Options?`              | `FlutterFileView.downloadFile` 参数 `options`         | `null`                                                                        |
| fileNameStyle           | `TextStyle?`            | 文件名称的样式                                             | `Theme.of(context).textTheme.bodyText1?.copyWith(fontWeight:FontWeight.bold)` |
| fileSizeStyle           | `TextStyle?`            | 文件资源大小的文字的样式                                        | `Theme.of(context).textTheme.bodyText2`                                       |
| downloadTitle           | `String?`               | 可下载时的按钮标题                                           | `ViewerLocalizations.of(context).downloadTitle`                               |
| viewTitle               | `String?`               | 可查看时的按钮标题                                           | `ViewerLocalizations.of(context).viewTitle`                                   |
| buttonStyle             | `ButtonStyle?`          | 按钮样式                                                | 见源文件                                                                          |
| btnTitleColor           | `Color？`                | 按钮文字颜色                                              | `Colors.white`                                                                |
| btnBgColor              | `Color？`                | 按钮背景颜色                                              | `Theme.of(context).primaryColor`                                              |
| progressSize            | `double?`               | `CircularProgressIndicator` 尺寸                      | `60.0`                                                                        |
| progressStrokeWidth     | `double?`               | `CircularProgressIndicator` 的 `strokeWidth`         | `6.0`                                                                         |
| progressBackgroundColor | `Color？`                | `CircularProgressIndicator` 背景色                     | `Theme.of(context).primaryColor`                                              |
| progressValueColor      | `Color？`                | `CircularProgressIndicator` 当前值颜色                   | `Colors.tealAccent`                                                           |

## 未来计划

- 实现网络链接的在线查看，当前可使用 `NetworkFileViewer` 实现下载后查看
- 考虑将去除 `NetworkFileViewer` 的 `onViewPressed` 功能，将额外提供事件用于打开无法预览的文件

## 其他Api

- `fileSize()` 用于换算文件大小
- `downloadFile()` 用于下载网络文件
- `getFileSize()` 用于获取网络文件大小

> 如果你喜欢我的项目，请在项目右上角 "Star" 一下。你的支持是我最大的鼓励！ ^_^