ecp_file_view

pub package

Language: 中文 | English

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

At present, the plugin is only used by Android, iOS

  • You can use LocalFileViewer to preview local files.
  • You can use NetworkFileViewer to download the network link and preview the file in combination with LocalFileViewer.

Use of third-party plugins

  • Use dio to make network requests.
  • It is recommended to use getTemporaryDirectory() as the target path, which can be implemented using the path_provider plugin.

Preparing for use

Version constraints

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

Rely

  1. Add ecp_file_view to pubspec.yaml dependencies.
dependencies:
  ecp_file_view: ^latest_version
  1. Get the package by executing the flutter command.
flutter pub get
  1. Introduce
import 'package:ecp_file_view/ecp_file_view.dart';

Localized configuration

Add in MaterialApp.

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

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

iOS

Make sure you add the following key to Info.plist for iOS

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

Android

Android P Unable to download kernel Solution

Add a piece of code in label application on AndroidManifst.xml file

android:networkSecurityConfig="@xml/network_security_config"

Add a file named network_security_config.xml in res/xml directory, The content of the file is

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

Add the JitPack repository to your root build.gradle, otherwise Gradle cannot resolve the com.github.Victor2018:DocViewer dependency:

allprojects {
    repositories {
        // Aliyun mirrors are recommended in China
        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' }
    }
}

Local File Preview - LocalFileViewer

  • Android is implemented by AndroidDocViewer (com.github.Victor2018:DocViewer). Its DocView is embedded into the Flutter widget tree as a PlatformView, which behaves the same as iOS.
  • iOS is implemented by WKWebView

Android host migration (AppCompatActivity requirement)

AndroidDocViewer's DocView depends on (context as AppCompatActivity).lifecycleScope in its constructor, so the host Activity must extend AppCompatActivity and cannot directly extend FlutterActivity. If your host currently uses FlutterActivity, follow the steps below:

1. Add the appcompat dependency (android/app/build.gradle)

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

2. Update themes (android/app/src/main/res/values/styles.xml)

<!-- Note: appcompat 1.3.0+ removed the NoTitleBar theme, use NoActionBar instead -->
<style name="LaunchTheme" parent="Theme.AppCompat.Light.NoActionBar">
    <!-- ... -->
</style>

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

3. Migrate MainActivity: switch to AppCompatActivity + FlutterFragment, and implement FlutterEngineConfigurator to register plugins manually (FlutterFragment does not automatically register plugins like FlutterActivity does — since Flutter 3.22, automatic registration is the responsibility of FlutterActivity.configureFlutterEngine, otherwise no plugin channel can connect)

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()
                    // Must attach to the Activity so ActivityAware plugins (including this plugin's PlatformView) work
                    .shouldAttachEngineToActivity(true)
                    // Newer Flutter supports PlatformView by default, no usesPlatformView needed
                    .shouldDelayFirstAndroidViewDraw(true)
                    .build()
            )
            .commit()
    }

    /**
     * FlutterFragment does not register plugins automatically,
     * so we must do it manually, otherwise no plugin channel can connect.
     */
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        GeneratedPluginRegistrant.registerWith(flutterEngine)
    }

    override fun cleanUpFlutterEngine(flutterEngine: FlutterEngine) {
        // Nothing to clean up
    }
}

Full example: MainActivity.kt (the plugin handles the PlatformView context internally, no host-side changes needed)

Supported file type

  • Android docx,doc,xlsx,xls,pptx,ppt,pdf,txt
  • iOS docx,doc,xlsx,xls,pptx,ppt,pdf,txt

Usage

Name Type Description Default
filePath String Path to local file Required
placeholder Widget? Widget displayed while the target filePath is loading. CupertinoActivityIndicator(radius: 14.0)
unsupportedPlatformWidget Widget? Widget displayed on unsupported platforms Center(child: Text(ViewerLocalizations.of(context).unsupportedPlatformTip))
nonExistentWidget Widget? Widget displayed while the file with path filePath does not exist Center(child: Text(ViewerLocalizations.of(context).nonExistentTip))
unsupportedTypeWidget Widget Widget displayed while the file is of an unsupported file types Center(child: Text(ViewerLocalizations.of(context).unsupportedType))
isBarShow bool Reserved for compatibility, not used by the current engine false
intoDownloading bool Reserved for compatibility, not used by the current engine false
isBarAnimating bool Reserved for compatibility, not used by the current engine false

Network Link Preview - NetworkFileViewer

A network link view which based on the WeChat’s UI, with download function and view click effect.

Usage

Name Type Description Default
downloadUrl String Download link for file Required
downloadPath String The file storage address is used to determine whether the file can be downloaded Required
onViewPressed VoidCallback File viewing function Required
placeholder Widget? Widget displayed while the target downloadUrl is loading. CupertinoActivityIndicator(radius: 14.0)
fileSizeData dynamic Parameter data of FlutterFileView.getFileSize null
fileSizeQueryParameters Map<String, dynamic>? Parameter queryParameters of FlutterFileView.getFileSize null
fileSizeOptions Options? Parameter options of FlutterFileView.getFileSize null
fileSizeTip String? Parameter fileSizeTip of FlutterFileView.getFileSize ViewerLocalizations.of(context).fileSizeTip
fileSizeFailTip String? Parameter fileSizeFailTip of FlutterFileView.getFileSize ViewerLocalizations.of(context).fileSizeFailTip
fileSizeErrorTip String? Parameter fileSizeErrorTip of FlutterFileView.getFileSize ViewerLocalizations.of(context).fileSizeErrorTip
downloadQueryParameters Map<String, dynamic>? Parameter queryParameters of FlutterFileView.downloadFile null
downloadDeleteOnError bool? Parameter deleteOnError of FlutterFileView.downloadFile true
downloadLengthHeader String? Parameter lengthHeader of FlutterFileView.downloadFile Headers.contentLengthHeader
downloadData dynamic Parameter data of FlutterFileView.downloadFile null
downloadOptions Options? Parameter options of FlutterFileView.downloadFile null
fileNameStyle TextStyle? The style of the displayed file name Theme.of(context).textTheme.bodyText1?.copyWith(fontWeight:FontWeight.bold)
fileSizeStyle TextStyle? The style of the displayed file size Theme.of(context).textTheme.bodyText2
downloadTitle String? Button title when downloadable ViewerLocalizations.of(context).downloadTitle
viewTitle String? Button title when viewable ViewerLocalizations.of(context).viewTitle
buttonStyle ButtonStyle? Button style See source file
btnTitleColor Color？ The color of the text of the button Colors.white
btnBgColor Color？ The color of the button's background Theme.of(context).primaryColor
progressSize double? Size of CircularProgressIndicator 60.0
progressStrokeWidth double? strokeWidth of CircularProgressIndicator 6.0
progressBackgroundColor Color？ Background color of CircularProgressIndicator Theme.of(context).primaryColor
progressValueColor Color？ The value color of CircularProgressIndicator Colors.tealAccent

Future Plans

  • Realize online viewing of network links. At present, NetworkFileViewer can be used to view after downloading.
  • Consider removing the onViewPressed function of NetworkFileViewer and providing additional events for opening files that cannot be previewed.

Other Api

  • Convert file size through fileSize().
  • Download network files through downloadFile().
  • Get the network file size through getFileSize().

If you like my project, please in the upper right corner of the project "Star". Your support is my biggest encouragement! ^_^

Libraries

ecp_file_view