Flutter外部存储访问插件external_storage的使用

external_storage简介

• 作者: 李俊才 (jcLee95)
• 博客: jcLee95
• 邮箱: 291148484@163.com
• 描述: 一个强大的Flutter Android外部存储管理插件，提供全面的文件系统操作、存储设备管理、文件监控和权限处理。
• 许可证: LICENSE
• 中文版: README_CN.md

简介

External Storage 是一款功能强大且易于使用的Flutter插件，专为跨平台文件和存储管理设计。该库提供了丰富的API来处理外部存储设备上的文件和目录操作，支持各种文件系统交互场景。

功能亮点

• 📱 多存储设备管理
• 📂 完整的文件和目录操作
• 👀 实时文件系统监控
• 🔒 全面的权限管理
• 🛠 丰富的文件实用方法
• ⚡ 高性能文件操作
• 🎯 类型安全的API

关键特性

External Storage 插件提供了丰富的文件和存储管理能力，包括但不限于：

• 文件操作：读取、写入、复制、移动和删除文件
• 目录管理：创建、列出、复制和监控目录
• 存储设备信息：检索详细的存储设备信息
• 文件系统监控：实时监听文件和目录的变化
• 权限管理：简化存储权限申请和管理

安装

在 pubspec.yaml 文件中添加以下依赖：

dependencies:
  external_storage: ^最新版本

然后执行以下命令以获取Flutter包：

flutter pub get

或者直接使用以下命令安装最新版本：

flutter pub add external_storage

配置

在 AndroidManifest.xml 中添加以下权限：

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Android 13+ (API 33+) 精细存储权限 -->
    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
    <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
    <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

    <!-- Android 14+ (API 34+) 图片和视频访问权限 -->
    <uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED" />

    <!-- Android 10及以下版本的存储权限 -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="29" />

    <!-- 全局文件访问权限（需要手动在系统设置中授权） -->
    <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

    <application
        android:label="external_storage_example"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
        <!-- 文件提供者（可选） -->
        <provider
            android:name="androidx.core.content.FileProvider"
            android:authorities="${applicationId}.fileProvider"
            android:exported="false"
            android:grantUriPermissions="true">
            <meta-data
                android:name="android.support.FILE_PROVIDER_PATHS"
                android:resource="@xml/file_paths" />
        </provider>
    </application>
</manifest>

有关详细信息，请参考提供的示例项目。

基本用法

初始化

import 'package:external_storage/external_storage.dart';

final externalStorage = ExternalStorage();

存储设备信息

获取所有可用的存储设备：

Future<void> getStorageDevices() async {
  try {
    List<StorageDevice> devices = await externalStorage.getAllStorageDevices();
    devices.forEach((device) {
      print('设备路径: ${device.path}');
      print('设备名称: ${device.name}');
      print('总空间: ${device.totalSize} 字节');
      print('可用空间: ${device.availableSize} 字节');
    });
  } catch (e) {
    print('获取存储设备失败: $e');
  }
}

文件操作

读取文件

Future<void> readFileContent() async {
  try {
    Uint8List fileData = await externalStorage.readFile('/path/to/file');
    print('文件内容: $fileData');
  } catch (e) {
    print('读取文件失败: $e');
  }
}

写入文件

Future<void> writeFileContent() async {
  try {
    Uint8List data = Uint8List.fromList('Hello, External Storage!'.codeUnits);
    int bytesWritten = await externalStorage.writeFile('/path/to/file', data);
    print('写入字节数: $bytesWritten');
  } catch (e) {
    print('写入文件失败: $e');
  }
}

目录操作

列出目录内容

Future<void> listDirectoryContents() async {
  try {
    List<FileInfo> files = await externalStorage.listDirectory('/path/to/directory');
    files.forEach((file) {
      print('文件名: ${file.name}');
      print('文件路径: ${file.path}');
      print('文件大小: ${file.size} 字节');
    });
  } catch (e) {
    print('列出目录内容失败: $e');
  }
}

文件系统监控

监听文件系统事件

Future<void> watchDirectory() async {
  try {
    await externalStorage.startWatching(
      '/path/to/watch',
      recursive: true,
      events: [
        WatchEventType.create,
        WatchEventType.delete,
        WatchEventType.modify
      ],
    );

    externalStorage.registerWatchEventCallback((path, event) {
      print('文件系统事件: $path, 事件类型: ${event.name}');
    });
  } catch (e) {
    print('监听目录失败: $e');
  }
}

权限管理

检查和请求存储权限

Future<void> manageStoragePermissions() async {
  try {
    bool hasPermission = await externalStorage.checkStoragePermissions();
    if (!hasPermission) {
      bool permissionGranted = await externalStorage.requestStoragePermissions();
      if (permissionGranted) {
        print('存储权限已授予');
      } else {
        print('存储权限被拒绝');
      }
    }
  } catch (e) {
    print('权限管理失败: $e');
  }
}

高级功能

External Storage 提供了额外的高级功能，例如文件MD5计算、MIME类型检索、文件属性检查等。建议查阅API文档以获取更多详细信息。

注意事项

在使用 External Storage 时，请注意以下几点：

• 确保处理潜在的异常情况
• 使用文件和目录操作时遵循最佳实践
• 注意跨平台兼容性
• 在某些平台上可能需要额外的权限配置

许可证

该插件遵循MIT许可证。请参阅项目的许可证文件以获取详细信息。

贡献

欢迎通过GitHub仓库提交问题和拉取请求，共同改进 External Storage 插件。

示例代码

以下是完整的示例代码，展示了如何使用 external_storage 插件进行文件和目录操作：

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

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

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'External Storage Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const StorageDemo(),
    );
  }
}

class StorageDemo extends StatefulWidget {
  [@override](/user/override)
  State<StorageDemo> createState() => _StorageDemoState();
}

class _StorageDemoState extends State<StorageDemo> {
  final ExternalStorage _storage = ExternalStorage();

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('External Storage Demo')),
      body: Center(
        child: ElevatedButton(
          onPressed: () async {
            // 获取存储设备信息
            List<StorageDevice> devices = await _storage.getAllStorageDevices();
            print('设备数量: ${devices.length}');
          },
          child: const Text('获取存储设备'),
        ),
      ),
    );
  }
}