[译]Flutter文件选取器组件file_picker(二)API

「这是我参与2022首次更文挑战的第27天，活动详情查看：2022首次更文挑战」。

本文翻译自： API · miguelpruivo/flutter_file_picker Wiki · GitHub

版本： file_picker 4.3.3

---

过滤器

所有的路径都可以使用下面的枚举之一过滤：

过滤器	说明
FileType.any	可选取所有有效的文件。在 iOS 上会打开 文件 应用。
FileType.custom	可选取匹配 allowedExtensions 指定的扩展名的路径。在 iOS 上会打开 Files 应用。
FileType.image	可选取图像文件。在 iOS 上打开 照片 应用。
FileType.video	可选取视频文件。在 iOS 上打开 照片 应用。
FileType.media	可选取视频或图像。在 iOS 上打开 照片 应用。
FileType.audio	可选取音频文件。在 iOS 上打开 音乐 应用 设备必须安装了 音乐 应用。 注意：受 DRM 保护的文件不会提供路径，而是返回 null 。

参数

有一些选取方法支持的通用参数，列在下面：

参数	类型	说明	支持的平台	默认
allowedExtensions	List<String>?	接收用于过滤的扩展名列表。例：[pdf, jpg]	所有平台	-
allowCompression	bool	定义了在选取时图像 和/或 视频文件是否会被操作系统自动压缩。设置时，动态照片也被被转换为静态的 JPEG 图像。在 Android 上不起作用，因为它永远返回原始文件或构成文件的副本。	iOS	true
dialogTitle	String?	设置桌面端模态对话框的标题。在 Web 或移动端不起作用。	桌面端	File Picker
lockParentWindow	bool	如果为 true ，子窗口（文件选取窗口）会一直显示在 Flutter 窗口的前面，直到被关闭（像模态窗口）。	桌面端 (仅 Windows)	false
onFileLoading	Function(FilePickerStatus)?	当提供该设置时，它会接收选中文件的处理状态。如果想要显示加载对话框或者文件正在下载/缓存时尤其有用。	移动端和 Web	-
type	FileType	定义要过滤文件的类型。	All	FileType.any
useFullScreenDialog	bool	让开发者设置用来使用全屏对话框（UIModalPresentationFullScreen）或平台默认对话框（typically UIModalPresentationFormSheet）。	iOS (13+)	false
withData	bool	设置是否直接将文件加载到内存中，并在 PlatformFile 实例中作为 Uint8List 可用。	移动端和 Web	在 Web 上为 true ，其它地方为 false
withReadStream	bool	允许将文件读入到 Stream<List<int>> 代替直接加载到内存中，来防止过高的（内存）占用，特别是大文件。如果想参考如何使用的示例，查看这里.	移动端和 Web	false

方法

◉ pickFiles()

该方法是选取文件和设置上面提到的所有属性的主方法。 FilePickerResult — 包含 List<PlatformFile>> — 或 null 如果放弃选取的话。

注意事项： 当设置 allowedExtensions 时 必须 使用 FileType.custom ，否则会抛出异常。

注意事项 2：  在 Web 上 path 总是 null 因为 Web 使用的是假路径，需要使用 bytes 来代替用以获取选中文件的内容。

用法示例

// 可选取单个文件路径，允许所有扩展名
FilePickerResult result = await FilePicker.platform.pickFiles(type: FileType.any);

if(result != null) {
 File file = File(result.files.first.path);
}

// 会进行过滤且仅可选取 svg 和 pdf 扩展名的文件
FilePickerResult result = await FilePicker.platform.pickFiles(type: FileType.custom, allowedExtensions: ['svg', 'pdf']);

if(result != null) {
 File file = File(result.files.first.path);
}

---

◉ getDirectoryPath()

可选取一个目录路径。（可选）可以在桌面端平台设置 dialogTitle （对话框标题）。

平台	信息
iOS	需要 iOS 11 或以上
Android	需要 SDK 21 或以上
桌面端	支持
Web	不支持

---

◉ clearTemporaryFiles()

一个工具方法可明确地从选取器除去缓存文件。这 不是必需的 ，因为系统会自己处理好，有时可能想要移除它们，特别是应用要处理大量的文件。

平台	信息
iOS	所有 选取的文件会被缓存，所以该设置会直接移除它们。
Android	从 2.0.0 开始，所有 选取的文件会被缓存，所以该设置会直接移除它们。
桌面端和 Web	没有实现因为不会有任何效果。路径总是会引用原始文件。

---

◉ saveFile()

打开 保存文件 / 另存为 对话框可以让用户选择文件路径和文件名来保存文件。该功能不会实际保存文件。它只是打开对话框让用户选择位置和文件名。该功能只返回指向（尚不存在）文件的 path 的字符串。如果取消了对话框则返回 null 。

（可选）可以通过 dialogTitle 参数设置对话框的标题，通过 fileName 参数设置默认文件名。参数 type 和 allowedExtensions 可用于设置有效文件类型的列表。请注意这两个参数只是给用户的建议，因为 保存文件/另存为 对话框不会强制使用这些限制。

注意： 设置 allowedExtensions 时 必须 使用 FileType.custom ，否则会抛出异常。

平台	信息
iOS	不支持
Android	不支持
桌面端	支持
Web	不支持

---