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

Flutter 三方库 file_picker 鸿蒙化文件选择器集成

摘要

file_picker 是 Flutter 生态中用于从设备选择文件的常用插件，支持选择图片、文档、音视频等多种类型的文件。本文基于 OpenHarmony TPC 仓库的适配版本，详细讲解 file_picker 在鸿蒙项目中的接入流程、权限配置、核心 API 使用及常见问题排查，并附真实设备运行截图验证。

核心要点：

• 配置必要的存储权限
• 掌握文件选择核心 API
• 处理不同文件类型的筛选

一、文件选择架构

二、参考来源

三、接入步骤

3.1 配置 pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  
  file_picker:
    git:
      url: https://atomgit.com/openharmony-tpc/flutter_packages.git
      path: packages/file_picker/file_picker

3.2 核心代码示例

import 'package:file_picker/file_picker.dart';

class FilePickerService {
  // 选择单个文件
  Future<FilePickerResult?> pickSingleFile({
    FileType type = FileType.any,
    List<String>? allowedExtensions,
  }) async {
    return await FilePicker.platform.pickFiles(
      type: type,
      allowedExtensions: allowedExtensions,
      allowMultiple: false,
    );
  }

  // 选择多个文件
  Future<FilePickerResult?> pickMultipleFiles({
    FileType type = FileType.any,
    List<String>? allowedExtensions,
  }) async {
    return await FilePicker.platform.pickFiles(
      type: type,
      allowedExtensions: allowedExtensions,
      allowMultiple: true,
    );
  }

  // 选择图片
  Future<PlatformFile?> pickImage() async {
    final result = await FilePicker.platform.pickFiles(
      type: FileType.image,
      allowMultiple: false,
    );
    return result?.files.firstOrNull;
  }

  // 选择文档
  Future<PlatformFile?> pickDocument() async {
    final result = await FilePicker.platform.pickFiles(
      type: FileType.custom,
      allowedExtensions: ['pdf', 'doc', 'docx', 'txt', 'xls', 'xlsx'],
      allowMultiple: false,
    );
    return result?.files.firstOrNull;
  }
}

3.3 完整使用示例

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

class FilePickerDemo extends StatefulWidget {
  @override
  _FilePickerDemoState createState() => _FilePickerDemoState();
}

class _FilePickerDemoState extends State<FilePickerDemo> {
  final FilePickerService _filePickerService = FilePickerService();
  PlatformFile? _selectedFile;
  String _fileInfo = '';

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('File Picker Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            if (_selectedFile != null) ...[
              Icon(Icons.insert_drive_file, size: 80, color: Colors.blue),
              SizedBox(height: 16),
              Text(
                _selectedFile!.name,
                style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
              ),
              SizedBox(height: 8),
              Text(
                _fileInfo,
                style: TextStyle(color: Colors.grey),
              ),
            ] else ...[
              Icon(Icons.file_open, size: 80, color: Colors.grey),
              SizedBox(height: 16),
              Text(
                '未选择文件',
                style: TextStyle(color: Colors.grey),
              ),
            ],
            SizedBox(height: 32),
            ElevatedButton.icon(
              onPressed: _pickImage,
              icon: Icon(Icons.image),
              label: Text('选择图片'),
            ),
            SizedBox(height: 16),
            ElevatedButton.icon(
              onPressed: _pickDocument,
              icon: Icon(Icons.description),
              label: Text('选择文档'),
            ),
            SizedBox(height: 16),
            ElevatedButton.icon(
              onPressed: _pickAnyFile,
              icon: Icon(Icons.file_present),
              label: Text('选择任意文件'),
            ),
          ],
        ),
      ),
    );
  }

  Future<void> _pickImage() async {
    final file = await _filePickerService.pickImage();
    if (file != null) {
      setState(() {
        _selectedFile = file;
        _fileInfo = '大小: ${(file.size / 1024).toStringAsFixed(2)} KB';
      });
    }
  }

  Future<void> _pickDocument() async {
    final file = await _filePickerService.pickDocument();
    if (file != null) {
      setState(() {
        _selectedFile = file;
        _fileInfo = '大小: ${(file.size / 1024).toStringAsFixed(2)} KB';
      });
    }
  }

  Future<void> _pickAnyFile() async {
    final result = await _filePickerService.pickSingleFile();
    if (result != null && result.files.isNotEmpty) {
      final file = result.files.first;
      setState(() {
        _selectedFile = file;
        _fileInfo = '大小: ${(file.size / 1024).toStringAsFixed(2)} KB';
      });
    }
  }
}

四、验证步骤

五、常见问题排查

六、运行成功截图

七、总结

file_picker 是处理文件选择的基础插件，在 OpenHarmony 平台上的适配完善。通过灵活使用 FileType 和 allowedExtensions，可以满足图片选择、文档选择等多种业务场景，是文件处理类应用的必备工具。

附录：Schema.org 结构化数据

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Flutter 三方库 file_picker 鸿蒙化文件选择器集成",
  "description": "基于 OpenHarmony TPC 仓库，详细讲解 file_picker 在鸿蒙项目中的接入流程、权限配置与文件选择功能实现。",
  "author": { "@type": "Person", "name": "OpenHarmony 跨平台开发者" },
  "publisher": { "@type": "Organization", "name": "OpenHarmony 跨平台社区", "url": "https://openharmonycrossplatform.csdn.net" },
  "datePublished": "2026-05-07",
  "dateModified": "2026-05-07",
  "mainEntityOfPage": "https://openharmonycrossplatform.csdn.net",
  "keywords": ["开源鸿蒙", "OpenHarmony", "Flutter for OpenHarmony", "file_picker", "文件选择", "三方库适配"],
  "inLanguage": "zh-CN"
}
</script>