ecp_file_view 4.0.0

A file viewer plugin for Flutter, support local file and network link of Android, iOS.

ecp_file_view

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

2. Get the package by executing the flutter command.

flutter pub get

3. 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! ^_^