电容文件拾取器插件

控制器插件,允许用户从设备的文件系统或相册中选择文件,目录,图像,或视频.

特征

Capacitor File Picker插件是Capacitor app最完整的文件选择解决方案之一. 以下是一些关键特征:

• 🖥️ 跨平台:支持Android,iOS和Web.
• 📂 目录选择:允许用户选择一个目录来检索所有文件.
• 🖼️ 图像选择:让用户从画廊中选择一个或多个图像.
• 🎥 视频采集:让用户从画廊中选择一个或多个视频.
• 📄 文件选择: 让用户从文件系统中选择一个或多个杂项文件.
• 📸 HEIC 到 JPEG 转换:在iOS上将HEIC图像转换为JPEG格式.
• 📜 文件元数据:检索文件大小,名称,mime类型等元数据,以及最后修改的时间戳.
• 🤝 兼容性: 与 文件压缩器, (中文(简体) ), 文件打开器 财务报告和审定财务报表 共享目标 插件 .
• 📦 可可花和SPM:支持CocoaPods和Swift软件包管理器用于iOS.
• 🔁 最新数据:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 打开一个问题 我们看看!

使用大小写

文件拾取器插件通常在应用程序需要用户交出文件时使用,例如:

• 文件上传:让用户将PDF或电子表格等文档附加到一个表格上并上传到服务器上.
• 简介和封面图片:让用户从他们的画廊中选择一张照片.
• 媒体附件: 将图像和视频添加到聊天消息,帖子,或支持票.
• 数据导入: 导入 CSV, JSON, 或备份文件到您的应用程序中 .

兼容性

指南

• 处理器文件处理指南

安装

你可以用我们的 AI 辅助设置 以安装插件. 添加数据 超级技能 至您的 AI 工具,使用以下命令:

npx skills add capawesome-team/skills --skill capacitor-plugins

然后使用下列提示:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-file-picker` plugin in my project.

如果你喜欢 手动设置,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

npm install @capawesome/capacitor-file-picker
npx cap sync

机器人

变量

此插件将使用以下工程变量( 在您的应用程序中定义) variables.gradle 文件名 :

• $androidxActivityVersion 版本 androidx.activity:activity (默认 : 1.13.0(中文(简体) )

权限

此 API 需要将以下权限添加到您 AndroidManifest.xml 开始之前或之后 application 标签 :

<!-- Needed if you want to retrieve unredacted EXIF metadata from photos -->
<uses-permission android:name="android.permission.ACCESS_MEDIA_LOCATION" />
<!-- Needed if you want to read files from external storage -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

iOS系统

应享权利

要使用这个带有Mac Cactoryst的插件, 您的应用程序必须拥有 com.apple.security.files.user-selected.read-only 已启用。 这允许应用程序读取用户选择的文件. 看看这个 苹果文档 更多信息.

<key>com.apple.security.files.user-selected.read-only</key>
<true/>

如果您不想使用带有Mac Catalyst的插件,可以跳过这个步骤.

配置

此插件不需要配置 .

使用量

以下例子显示了如何选择文件,图像,视频和目录,以及如何处理所选文件.

选择一个或多个文件

打开系统文件拾取器,让用户选择一个或多个任意类型的文件. 其结果包括元数据(名称、大小、mime类型、最后修改的时间戳)以及Android和iOS上每个所选文件的路径:

import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickFiles = async () => {
  const result = await FilePicker.pickFiles();
  const file = result.files[0];
};

将拾取器限制为特定文件类型

使用 types 只接受某些选项 IANA 媒体类型,例如PDF文档:

import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickPdfFiles = async () => {
  const result = await FilePicker.pickFiles({
    types: ['application/pdf'],
  });
};

在Android上,系统文件取取器只能提供设备出自文件扩展名的媒体类型文件. 在Android 9 岁及以上, .json 文件没有映射到 application/json 报告为: application/octet-stream第三方文件提供者在任何版本上的行为都可能相同。 添加 application/octet-stream 改为 types 如果这些文件必须是可选择的.

从画廊取出图像或视频

使用 pickImages(...), (中文(简体) ), pickVideos(...) 或者说 pickMedia(...) 打开相册,而不是文件取取器。 这些方法仅在Android和iOS上提供:

import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickImages = async () => {
  const result = await FilePicker.pickImages();
};

const pickVideos = async () => {
  const result = await FilePicker.pickVideos();
};

const pickMedia = async () => {
  // Pick both images and videos
  const result = await FilePicker.pickMedia({ limit: 3 });
};

在网页视图中显示所选图像

使用 webPath 在网页视图中加载所选文件的属性, 例如 src 一、导 言 <img> 元素 :

import { FilePicker } from '@capawesome/capacitor-file-picker';

const displayImage = async () => {
  const { files } = await FilePicker.pickImages({ limit: 1 });
  const image = document.createElement('img');
  image.src = files[0].webPath!;
  document.body.appendChild(image);
};

选择目录

让用户选择一个目录,例如导入它包含的所有文件. 仅在Android和iOS上提供:

import { FilePicker } from '@capawesome/capacitor-file-picker';

const pickDirectory = async () => {
  const { path } = await FilePicker.pickDirectory();
};

将选中的文件上传到服务器

在网络上,选中的文件包含 Blob 举个例子 在Android和iOS上,使用 获取 API 和文档的 webPath。然后您可以将 blob 附加到 a FormData 对象并上传:

import { FilePicker } from '@capawesome/capacitor-file-picker';

const uploadFile = async () => {
  const result = await FilePicker.pickFiles({ limit: 1 });
  const file = result.files[0];

  let blob: Blob;
  if (file.blob) {
    // Web
    blob = file.blob;
  } else {
    // Android and iOS
    const response = await fetch(file.webPath!);
    blob = await response.blob();
  }

  const formData = new FormData();
  formData.append('file', blob, file.name);
  await fetch('https://example.com/upload', {
    method: 'POST',
    body: formData,
  });
};

请注意: 避开 readData 选项。 它将整个文件装入内存作为 Base64 字符串,这可以崩溃您的应用. 基于获取的方法在文件上方流出 .

将 HEIC 图像转换为 JPEG

在iOS上,相片经常被以HEIC格式存储,许多服务器和浏览器无法显示. 使用 convertHeicToJpeg(...) 以转换它们。 仅在iOS上可用 :

import { FilePicker } from '@capawesome/capacitor-file-picker';

const convertHeicToJpeg = async () => {
  const { path } = await FilePicker.convertHeicToJpeg({
    path: 'path/to/image.heic',
  });
};

将 RAW 图像转换为 JPEG

RAW图像(如DNG)在被取出时没有被转码. 使用 convertRawToJpeg(...) 以转换它们。 仅在iOS上可用 :

import { FilePicker } from '@capawesome/capacitor-file-picker';

const convertRawToJpeg = async () => {
  const { path } = await FilePicker.convertRawToJpeg({
    path: 'path/to/image.dng',
  });
};

检查和请求权限

取取文件不需要任何权限,因为操作系统呈现取取取器. 不过,如果你需要的话 ACCESS_MEDIA_LOCATION 或者说 READ_EXTERNAL_STORAGE android上的权限(参见 安装),你可以检查和要求它们:

import { FilePicker } from '@capawesome/capacitor-file-picker';

const checkPermissions = async () => {
  const result = await FilePicker.checkPermissions();
};

const requestPermissions = async () => {
  const result = await FilePicker.requestPermissions();
};

听好,被开除的选手

在iOS上,当用户关闭拾取器而不选择任何内容时,可以通知您:

import { FilePicker } from '@capawesome/capacitor-file-picker';

const addPickerDismissedListener = async () => {
  await FilePicker.addListener('pickerDismissed', () => {
    console.log('Picker was dismissed');
  });
};

复制文件

将选中的文件复制到新位置, 例如, 复制到您的应用程序的数据目录 :

import { FilePicker } from '@capawesome/capacitor-file-picker';

const copyFile = async () => {
  await FilePicker.copyFile({
    from: 'path/to/file',
    to: 'path/to/destination',
  });
};

API 密码

• checkPermissions()
• convertHeicToJpeg(...)
• convertRawToJpeg(...)
• copyFile(...)
• pickFiles(...)
• pickDirectory()
• pickImages(...)
• pickMedia(...)
• pickVideos(...)
• requestPermissions(...)
• addListener('pickerDismissed', ...)
• removeAllListeners()
• 接口
• 类型异名

检查( )

checkPermissions() => Promise<PermissionStatus>

检查访问文件的权限 .

只能从Android上找到.

回返情况: Promise<PermissionStatus>

自: 6.1.0 (中文(简体) )

转换HeicToJpeg(...)

convertHeicToJpeg(options: ConvertHeicToJpegOptions) => Promise<ConvertHeicToJpegResult>

将 HEIC 图像转换为 JPEG .

仅在iOS上可用.

回返情况: Promise<ConvertHeicToJpegResult>

自: 0.6.0 (中文(简体) )

转换RawToJpeg(...)

convertRawToJpeg(options: ConvertRawToJpegOptions) => Promise<ConvertRawToJpegResult>

将 RAW 图像转换为 JPEG .

仅在iOS上可用.

回返情况: Promise<ConvertRawToJpegResult>

自: 8.1.0 联合国

复制文件(...)

copyFile(options: CopyFileOptions) => Promise<void>

复制文件到新位置 .

自: 7.1.0 (中文(简体) )

pickFiles (...) (帮助)

pickFiles(options?: PickFilesOptions | undefined) => Promise<PickFilesResult>

打开文件拾取器,允许用户选择一个或多个文件.

回返情况: Promise<PickFilesResult>

选择目录( )

pickDirectory() => Promise<PickDirectoryResult>

打开一个可让用户选择目录的拾取器对话框 .

仅在Android和iOS上提供.

回返情况: Promise<PickDirectoryResult>

自: 6.2.0 (单位:千美元)

选择图像(...)

pickImages(options?: PickMediaOptions | undefined) => Promise<PickImagesResult>

从画廊取出一个或多个图像.

在iOS 13 和 更年长时,它只允许选择一个图像.

仅在Android和iOS上提供.

回返情况: Promise<PickFilesResult>

自: 0.5.3 (韩语)

选择媒体(...)

pickMedia(options?: PickMediaOptions | undefined) => Promise<PickMediaResult>

从画廊中取出一个或多个图像或视频.

在iOS 13及更年长时,它只能选择一个图像或视频.

仅在Android和iOS上提供.

回返情况: Promise<PickFilesResult>

自: 0.5.3 (韩语)

选择视频(...)

pickVideos(options?: PickMediaOptions | undefined) => Promise<PickVideosResult>

从画廊取出一或多段视频.

在iOS 13 岁及更年长时,只能选择一个视频.

仅在Android和iOS上提供.

回返情况: Promise<PickFilesResult>

自: 0.5.3 (韩语)

请求(...)

requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<PermissionStatus>

请求访问文件的权限 .

只能从Android上找到.

回返情况: Promise<PermissionStatus>

自: 6.1.0 (中文(简体) )

添加收听器( “ picker Dismission” ,...)

addListener(eventName: 'pickerDismissed', listenerFunc: () => void) => Promise<PluginListenerHandle>

取取文件者被开除时打电话.

仅在iOS上可用.

回返情况: Promise<PluginListenerHandle>

自: 0.6.2 (中文(简体) )

删除所有收听器( )

removeAllListeners() => Promise<void>

删除此插件的所有听众 .

自: 0.6.2 (中文(简体) )

接口

权限状态

转换HeicToJpeg结果

转换HeicToJpeg 选项

转换RawToJpeg结果

转换 RawToJpeg 选项

复制文件选项

拾荒档案

选中文件

PickFiles 选项

选取剪贴板

选择媒体选项

请求允许选项

插件听筒

类型异名

权限状态

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

选项

PickMediaOptions

选择图像

PickMediaResult

选择媒体

PickFilesResult

选择视频选项

PickMediaOptions

选择视频结果

PickMediaResult

权限类型

'accessMediaLocation' | 'readExternalStorage'

财务问题

我怎么把选中的文件上传到服务器?

在网络上,所选文件已经包含 Blob 实例 FormData 对象。 在Android和iOS上,将文件作为blob上载,使用获取API和文件路径,再以同样方式上载. 见 使用示例 上文及 处理器文件处理指南 完全通过.

为什么我的应用程序在选取大文件时会崩溃?

这通常发生在 readData 选项已启用。 它将整个文件读入内存为Base64字符串,可以超过大文件可用的内存. 保留 readData 禁用(默认),并用取取 API 作为 blob 装入文件, 如 使用示例 见上文.

两者有什么区别 pickFiles, (中文(简体) ), pickImages, (中文(简体) ), pickMedia 财务报告和审定财务报表 pickVideos? 吗?

这个 pickFiles(...) 方法打开系统文件拾取器,并支持Android,iOS和Web上的任何文件类型. 这个 pickImages(...), (中文(简体) ), pickVideos(...) 财务报告和审定财务报表 pickMedia(...) 取而代之的是打开相册,它为选择相片和视频提供了更熟悉的经验,并且只在Android和iOS上提供.

我需要任何运行时间权限来选择文件吗?

不, 选择文件本身不需要任何运行时间权限, 因为操作系统代表您的应用程序呈现选择器 。 安卓号上 ACCESS_MEDIA_LOCATION 只需从照片中获取未编辑的 EXIF 元数据即可,并且 READ_EXTERNAL_STORAGE 只用于从外部存储读取文件。 在iOS上,不需要隐私描述.

此插件与相机相机和文件系统插件有何不同?

Capacitor相机插件会与相机相接相机相接相机或从相廊取出相机相机相机相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相机相接相接相机相接相接相机相机相接相接相接相机相接相机相接相机相接相机相机相接相相机相机相接相相相机相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 Capacitor 文件系统插件在已知路径读取并写入文件,但它没有为选择它们提供任何用户界面. File Picker 插件填补了这个空白:它让用户选择任何文件,目录,图像,或视频,并返回其路径和元数据,然后用其他插件处理.

我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

相关插件

• 文件压缩器:在上传图像之前压缩图像.
• 文件打开器: 打开带有默认应用程序的所选文件.
• 共享目标:接收其他应用程序共享的文件.
• 齐普: Zip和unzip文件和目录.

通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 《卡帕索克通讯》。 。 。 .

更改日志

见 变动情况。 。 。 .

许可证

见 自由主义。 。 。 .

贷项

此插件基于 电容文件拾取器 插件 . 感谢所有为这个项目捐款的人!