插件介绍

fluttertpc_flutter_document_picker 是一个为鸿蒙平台适配的 Flutter 文档选择器插件，基于开源的 flutter_document_picker 项目进行自定义修改。该插件允许开发者在鸿蒙应用中轻松实现文档选择功能，支持选择单个或多个文档，并可以根据文件扩展名、MIME 类型等条件进行过滤。

主要功能特点：

• 支持选择单个或多个文档文件
• 可根据文件扩展名进行过滤
• 可根据 MIME 类型进行过滤
• 提供文件名符号清理功能
• 完全适配鸿蒙平台

如何在鸿蒙应用中使用该插件

1. 包的引入

由于这是一个自定义修改版本的三方库，需要以 git 形式引入。在项目的 pubspec.yaml 文件中，添加以下依赖配置：

dependencies:
  fluttertpc_flutter_document_picker:
    git:
      url: "https://atomgit.com/openharmony-sig/fluttertpc_flutter_document_picker.git"

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

flutter pub get

2. API 的调用

基本使用方法

首先，在需要使用该插件的文件中导入包：

import 'package:flutter_document_picker/flutter_document_picker.dart';

选择单个文档

Future<void> pickSingleDocument() async {
  try {
    String? result = await FlutterDocumentPicker.openDocument();
    if (result != null) {
      // 处理选择的文档路径
      print('选择的文档路径: $result');
    }
  } catch (e) {
    // 处理错误
    print('选择文档时出错: $e');
  }
}

选择多个文档

Future<void> pickMultipleDocuments() async {
  try {
    List<String?>? results = await FlutterDocumentPicker.openDocuments();
    if (results != null && results.isNotEmpty) {
      // 处理选择的多个文档路径
      for (String? path in results) {
        if (path != null) {
          print('选择的文档路径: $path');
        }
      }
    }
  } catch (e) {
    // 处理错误
    print('选择文档时出错: $e');
  }
}

高级配置选项

可以使用 FlutterDocumentPickerParams 类来配置文档选择器的行为：

Future<void> pickDocumentWithFilters() async {
  try {
    FlutterDocumentPickerParams params = FlutterDocumentPickerParams(
      // 只允许选择 PDF 和 PNG 文件
      allowedFileExtensions: ['pdf', 'png'],
      // 只允许选择特定 MIME 类型的文件
      allowedMimeTypes: ['application/pdf', 'image/png'],
      // 指定在文件名中需要替换为 '_' 的符号
      invalidFileNameSymbols: ['/', '\\', ':', '*', '?', '"', '<', '>', '|'],
    );

    String? result = await FlutterDocumentPicker.openDocument(params: params);
    if (result != null) {
      print('选择的文档路径: $result');
    }
  } catch (e) {
    print('选择文档时出错: $e');
  }
}

3. 在实际应用中的完整示例

以下是一个完整的示例，展示如何在鸿蒙应用中集成并使用该插件：

import 'package:flutter/material.dart';
import 'package:flutter_document_picker/flutter_document_picker.dart';

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

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  String _result = 'No file selected';
  bool _isMultipleSelection = false;
  bool _isLoading = false;

  Future<void> _pickDocument() async {
    try {
      setState(() {
        _result = 'Loading...';
        _isLoading = true;
      });

      FlutterDocumentPickerParams params = FlutterDocumentPickerParams(
        allowedFileExtensions: ['pdf', 'docx', 'txt', 'png', 'jpg'],
        allowedMimeTypes: [
          'application/pdf',
          'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
          'text/plain',
          'image/png',
          'image/jpeg'
        ],
      );

      dynamic result;
      if (_isMultipleSelection) {
        result = await FlutterDocumentPicker.openDocuments(params: params);
      } else {
        result = await FlutterDocumentPicker.openDocument(params: params);
      }

      String resultText;
      if (result == null) {
        resultText = 'No file selected';
      } else if (result is List<String?>) {
        resultText = 'Selected files:\n' + result.where((x) => x != null).join('\n');
      } else {
        resultText = 'Selected file:\n$result';
      }

      setState(() {
        _result = resultText;
        _isLoading = false;
      });
    } catch (e) {
      setState(() {
        _result = 'Error: $e';
        _isLoading = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('Document Picker Example'),
        ),
        body: Padding(
          padding: const EdgeInsets.all(16.0),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Text(
                'Document Picker Demo',
                style: Theme.of(context).textTheme.headlineMedium,
              ),
              SizedBox(height: 20),
              Row(
                children: [
                  Text('允许多选:'),
                  Checkbox(
                    value: _isMultipleSelection,
                    onChanged: (value) {
                      setState(() {
                        _isMultipleSelection = value ?? false;
                      });
                    },
                  ),
                ],
              ),
              SizedBox(height: 20),
              ElevatedButton(
                onPressed: _isLoading ? null : _pickDocument,
                child: Text('选择文档'),
              ),
              SizedBox(height: 20),
              Text('结果:'),
              SizedBox(height: 10),
              Expanded(
                child: Container(
                  padding: EdgeInsets.all(10),
                  decoration: BoxDecoration(
                    border: Border.all(color: Colors.grey),
                    borderRadius: BorderRadius.circular(5),
                  ),
                  child: SingleChildScrollView(
                    child: _isLoading
                        ? Center(child: CircularProgressIndicator())
                        : Text(_result),
                  ),
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

参数说明

FlutterDocumentPickerParams

参数名	描述	类型	鸿蒙平台支持
allowedUtiTypes	iOS 平台使用的 Uniform Type Identifiers（仅限 iOS）	List?	no
allowedFileExtensions	允许选择的文件扩展名列表	List?	yes
allowedMimeTypes	允许选择的 MIME 类型列表	List?	yes
invalidFileNameSymbols	在选定文档名称中会被替换为 “_” 的符号列表	List	yes

兼容性

该插件已在以下环境中测试通过：

1. Flutter: 3.7.12-ohos-1.1.3; SDK: 5.0.0(12); IDE: DevEco Studio: 5.1.0.828; ROM: 5.1.0.130 SP8;
2. Flutter: 3.22.1-ohos-1.0.3; SDK: 5.0.0(12); IDE: DevEco Studio: 5.1.0.828; ROM: 5.1.0.130 SP8;

总结

fluttertpc_flutter_document_picker 是一个功能强大且易于使用的文档选择器插件，专为鸿蒙平台进行了适配。它提供了灵活的配置选项，可以满足不同场景下的文档选择需求。通过简单的 API 调用，开发者可以在鸿蒙应用中快速实现文档选择功能，提升应用的用户体验。

该插件的主要优势在于：

• 完全适配鸿蒙平台
• 支持多种过滤条件
• 提供简洁易用的 API
• 支持单文档和多文档选择

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