# @capacitor-community/media 中文文档 规范地址：https://npmcn.com/package/%40capacitor-community/media/ 版本：9\.1\.0 npm 元数据更新时间：2026-10-23T21:47:53.931Z 中文译文更新时间：2026-11-09T02:03:55.439Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40capacitor-community/media 原文对照：https://npmcn.com/package/%40capacitor-community/media/?lang=original 项目主页：https://github.com/capacitor-community/media#readme 源码仓库：https://github.com/capacitor-community/media ## 关键信息（来自 npm 元数据） - 包体积（解压后）：149 kB，26 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：@capacitor/core \>=8\.0\.0 - 首次发布：2020-06-28T06:11:27.779Z - 最新版本发布：2026-03-27T00:10:54.720Z - 近 30 天下载量：317460（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：33（近 12 个月 4 个） ## 中文简介 用于保存并取回相片和视频,管理相册的电容插件. ## 安装 ```sh npm install @capacitor-community/media ``` 也可以使用：`pnpm add @capacitor-community/media`、`yarn add @capacitor-community/media`、`bun add @capacitor-community/media` ## README ![](https://user-images.githubusercontent.com/236501/85893648-1c92e880-b7a8-11ea-926d-95355b8175c7.png) ### 电容介质 **`@capacitor-community/media`** 用于保存并取回相片和视频,管理相册的电容插件. ![](https://img.shields.io/maintenance/yes/2026?style=flat-square) [![](https://img.shields.io/npm/l/@capacitor-community/media?style=flat-square)](https://www.npmjs.com/package/@capacitor-community/media) [![](https://img.shields.io/npm/dw/@capacitor-community/media?style=flat-square)](https://www.npmjs.com/package/@capacitor-community/media) [![](https://img.shields.io/npm/v/@capacitor-community/media?style=flat-square)](https://www.npmjs.com/package/@capacitor-community/media) [![](https://img.shields.io/badge/all%20contributors-14-orange?style=flat-square)](https://npmcn.com/package/%40capacitor-community/media/#readme-contributors) ## 维护者 | 维护者 | GitHub 图像 | 社会 | | --- | --- | --- | | 尼萨拉·卡卢帕哈纳 | [纳鲁帕哈纳](https://github.com/nkalupahana) | | | 斯特万·席尔瓦 | [炖鱼](https://github.com/stewones) | [@stewones (英语)](https://twitter.com/stewones) | ## 安装 ```bash npm install @capacitor-community/media ``` 目前为Capacitor 8(插件版9)维护了这个插件. 添加一个 `@8` 或 `@7` 用于电容 6. 目前这三个版本之间没有API的更改,因此如果在插件v7-v9(Capacitor 6-8)之间迁移,则不需要代码更改. SPM 仅支持插件 v9 . 安装后, 请通过运行确定同步 `npx cap sync`。 。 。 . ## 从插件 v6 移到 v7+ 在Android上处理权限的方式发生了突破性的变化. - 如果你的应用不是"垃圾"的应用(不需要访问设备上的所有相册,只是它自己的),你不再需要了 `READ_EXTERNAL_STORAGE`, (中文(简体) ), `WRITE_EXTERNAL_STORAGE`, (中文(简体) ), `READ_MEDIA_IMAGES`,或 `READ_MEDIA_VIDEO` 权限。 你可以把它们从你的 `AndroidManifest.xml` 文档。 该插件将不再请求任何权限来保存您的相册中的图像 . - 如果你的应用是画廊应用 你需要访问设备上的所有相册 你需要更新 `capacitor.config.ts` 文件(并保留上述所有权限) -- -- 见下面的设置指示. 您需要更新到 v7 才能在 Google Play Store 上发布此插件的应用程序 . ## 从插件 v5 移到 v6 有一些零星的改动需要注意: - `saveGif` 已经不复存在。 使用 `savePhoto` 用于图像和GIF. - 错误文本已更改 。 如果您正在检查特定错误消息, 您现在应该使用 `error.code`,这将是 `accessDenied`, (中文(简体) ), `argumentError`, (中文(简体) ), `downloadError`,或 `filesystemError`。 。 。 . ## 设置 ### iOS系统 你需要在你的应用中加入以下内容 `Info.plist` 文件 : ```xml ... NSPhotoLibraryUsageDescription Describe why you need access to user's photos (getting albums and media) NSPhotoLibraryAddUsageDescription Describe why you need to add photos to user's photo library ... ``` ### 机器人 默认情况下,此插件仅可访问与此相册相关的相册 应用安装在。 这应足以用于大多数案件. 对于此基本访问级别,您只需添加以下权限: ```xml ... ... ``` 如果你正在建立一个需要访问设备上所有照片和视频的应用程序 (如相册相册应用),您需要以下权限: 1 ```xml ... ... ``` 您还需要添加以下配置到 `capacitor.config.ts`数字 : ```ts plugins: { Media: { androidGalleryMode: true } } ``` 你可以找到一个例子 说明这应该如何看待 `example/` 文件夹. ## 演示 走开 `example/` 文件夹将使用一个实例应用程序,该程序应显示此插件的所有功能. ![](https://github.com/capacitor-community/media/blob/main/example_app.png?raw=true) ## API 密码 除非另有说明,iOS和Android之间应实现完全的特征等同. 网络不支持 . - [`getMedias(...)`](https://npmcn.com/package/%40capacitor-community/media/#readme-getmedias) - [`getMediaByIdentifier(...)`](https://npmcn.com/package/%40capacitor-community/media/#readme-getmediabyidentifier) - [`getAlbums()`](https://npmcn.com/package/%40capacitor-community/media/#readme-getalbums) - [`savePhoto(...)`](https://npmcn.com/package/%40capacitor-community/media/#readme-savephoto) - [`saveVideo(...)`](https://npmcn.com/package/%40capacitor-community/media/#readme-savevideo) - [`createAlbum(...)`](https://npmcn.com/package/%40capacitor-community/media/#readme-createalbum) - [`getAlbumsPath()`](https://npmcn.com/package/%40capacitor-community/media/#readme-getalbumspath) - [接口](https://npmcn.com/package/%40capacitor-community/media/#readme-interfaces) - [类型异名](https://npmcn.com/package/%40capacitor-community/media/#readme-type-aliases) - [数字](https://npmcn.com/package/%40capacitor-community/media/#readme-enums) ### 获取媒体(...) ```typescript getMedias(options?: MediaFetchOptions | undefined) => Promise ``` 从相机上取出过滤的缩略图 仅iOS. [代码示例](https://github.com/capacitor-community/media/blob/main/example/src/components/GetMedias.tsx) | 参数 | 类型 | | --- | --- | | **`options`** | `[MediaFetchOptions](https://npmcn.com/package/%40capacitor-community/media/#readme-mediafetchoptions)` | **回返情况:** `Promise<[MediaResponse](https://npmcn.com/package/%40capacitor-community/media/#readme-mediaresponse)>` * * * ### 获取媒体识别符(...) ```typescript getMediaByIdentifier(options?: { identifier: string; } | undefined) => Promise ``` 以标识符获取一个文件系统路径来获取一个完整的媒体资产 。 仅iOS. 这不包括Android,因为Android上,一个媒体资产的身份识别符就是它的路径! 您可以简单地使用文件系统插件来工作 。 在iOS上,您必须将标识符转换为路径 使用此函数。 之后可以使用与Android相同的"文件系统"插件. [代码示例](https://github.com/capacitor-community/media/blob/main/example/src/components/GetMedias.tsx) | 参数 | 类型 | | --- | --- | | **`options`** | `{ identifier: string; }` | **回返情况:** `Promise<[MediaPath](https://npmcn.com/package/%40capacitor-community/media/#readme-mediapath)>` * * * ### 获取 Albums () ```typescript getAlbums() => Promise ``` 获得专辑列表. [代码示例](https://github.com/capacitor-community/media/blob/main/example/src/components/GetAlbums.tsx) **回返情况:** `Promise<[MediaAlbumResponse](https://npmcn.com/package/%40capacitor-community/media/#readme-mediaalbumresponse)>` * * * ### 保存图片(...) ```typescript savePhoto(options?: MediaSaveOptions | undefined) => Promise ``` 将静态相片或GIF保存到相机卷中. 在Android和iOS上,它支持网络URL, Base64 编码图像 (例如:数据:image/jpeg;base64,.),以及本地文件. 在Android上,用户相片取景器所支持的所有图像格式都得到支持. 在iOS上,支持大多数常见的图像格式. [代码示例](https://github.com/capacitor-community/media/blob/main/example/src/components/SaveMedia.tsx) | 参数 | 类型 | | --- | --- | | **`options`** | `[MediaSaveOptions](https://npmcn.com/package/%40capacitor-community/media/#readme-mediasaveoptions)` | **回返情况:** `Promise<[PhotoResponse](https://npmcn.com/package/%40capacitor-community/media/#readme-photoresponse)>` * * * ### 保存视频(...) ```typescript saveVideo(options?: MediaSaveOptions | undefined) => Promise ``` 保存视频到相机卷. 在Android和iOS上,它支持网络URL, Base64编码视频 (例如:数据:image/mp4;base64,.),以及本地文件. 在Android上,支持用户相片取景器支持的所有视频格式. 在iOS上,所支持的格式是基于当时任何iOS支持. [代码示例](https://github.com/capacitor-community/media/blob/main/example/src/components/SaveMedia.tsx) | 参数 | 类型 | | --- | --- | | **`options`** | `[MediaSaveOptions](https://npmcn.com/package/%40capacitor-community/media/#readme-mediasaveoptions)` | **回返情况:** `Promise<[PhotoResponse](https://npmcn.com/package/%40capacitor-community/media/#readme-photoresponse)>` * * * ### 创建 Album (...) ```typescript createAlbum(options: MediaAlbumCreate) => Promise ``` 创建相册. [代码示例](https://github.com/capacitor-community/media/blob/main/example/src/components/CreateDemoAlbum.tsx) | 参数 | 类型 | | --- | --- | | **`options`** | `[MediaAlbumCreate](https://npmcn.com/package/%40capacitor-community/media/#readme-mediaalbumcreate)` | * * * ### 获取 AlbumsPath () ```typescript getAlbumsPath() => Promise ``` 获得相册文件夹及其相片的路径 保存在Android文件系统中。 可用于识别 您的相册不只是在Android上的名字 以防万一 是多张同名相册,这在Android上是可能的. 只需比较相册路径到相册标识符的开始 获得专辑. 只能从Android上找到. 代码示例 : [基础](https://github.com/capacitor-community/media/blob/main/example/src/components/CreateDemoAlbum.tsx), (中文(简体) ), [保存媒体时](https://github.com/capacitor-community/media/blob/main/example/src/components/SaveMedia.tsx) **回返情况:** `Promise<[AlbumsPathResponse](https://npmcn.com/package/%40capacitor-community/media/#readme-albumspathresponse)>` * * * ### 接口 #### 媒体响应 | Prop | 类型 | | --- | --- | | **`medias`** | `MediaAsset[]` | #### 媒体配置 | Prop | 类型 | 说明 | | --- | --- | --- | | **`identifier`** | `string` | 平台专用标识符 | | **`data`** | `string` | 作为基数64编码字符串的相片资产数据( JPEG 仅支持) | | **`creationDate`** | `string` | 创建资产日期的ISO 日期字符串 | | **`duration`** | `number` | 资产持续时间, 以秒计, 只返回视频 | | **`fullWidth`** | `number` | 原始资产的全宽 | | **`fullHeight`** | `number` | 原始资产的全部高度 | | **`thumbnailWidth`** | `number` | 缩略图预览的宽度 | | **`thumbnailHeight`** | `number` | 缩略图预览的高度 | | **`location`** | `[MediaLocation](https://npmcn.com/package/%40capacitor-community/media/#readme-medialocation)` | 资产位置元数据 | #### 媒体定位 | Prop | 类型 | 说明 | | --- | --- | --- | | **`latitude`** | `number` | GPS 纬度图像拍摄于 | | **`longitude`** | `number` | GPS经度图像拍摄到 | | **`heading`** | `number` | 拍摄了用户的图像标题 | | **`altitude`** | `number` | 拍摄了时间图像的用户高度 | | **`speed`** | `number` | 拍摄了时间图像的用户速度 | #### 媒体选择 | Prop | 类型 | 说明 | | --- | --- | --- | | **`quantity`** | `number` | 要取取的照片数量, 按上次创建的日期来排序 。 为了活化,只要要求更高的数量 -- OS缓存应该能使这个功能相对发挥. | | **`thumbnailWidth`** | `number` | 返回缩略图的宽度 | | **`thumbnailHeight`** | `number` | 返回缩略图的高度 | | **`thumbnailQuality`** | `number` | 缩略图质量返回为 JPEG (0- 100) | | **`types`** | `'photos' | 'videos' | 'all'` | 要返回缩略图的资产类型 . | | **`albumIdentifier`** | `string` | 要查询的相册标识符( 用 getAlbums () 获得标识符) | | **`sort`** | `[MediaField](https://npmcn.com/package/%40capacitor-community/media/#readme-mediafield) | MediaSort[]` | 按字段和升/降级排序返回资产的顺序 | #### 介质种子 | Prop | 类型 | | --- | --- | | **`key`** | `[MediaField](https://npmcn.com/package/%40capacitor-community/media/#readme-mediafield)` | | **`ascending`** | `boolean` | #### 媒体 | Prop | 类型 | 说明 | | --- | --- | --- | | **`path`** | `string` | 媒体资产路径 | | **`identifier`** | `string` | 媒体资产的标识符 | #### 媒体Album 回复 | Prop | 类型 | | --- | --- | | **`albums`** | `MediaAlbum[]` | #### 媒体Album | Prop | 类型 | | --- | --- | | **`identifier`** | `string` | | **`name`** | `string` | | **`type`** | `[MediaAlbumType](https://npmcn.com/package/%40capacitor-community/media/#readme-mediaalbumtype)` | #### 相机响应 | Prop | 类型 | 说明 | | --- | --- | --- | | **`filePath`** | `string` | 仅限Android使用. | | **`identifier`** | `string` | 仅在iOS上可用. 要获得iOS上图像的文件路径, 请将此标识符传递给 `getMediaByIdentifier`。 。 。 . | #### 媒体保存选项 | Prop | 类型 | 说明 | | --- | --- | --- | | **`path`** | `string` | Web URL, Base64 已编码 URI, 或要保存的本地文件路径. | | **`albumIdentifier`** | `string` | 专辑标识符来自 getAlbums (). 自5.0起,标识符同时被使用在Android和iOS上. 在Android上需要识别器,但在iOS上则不需要识别. 在iOS 14+上,如果未指定标识符且尚未请求权限,则会请求添加权限而不是全部权限(假设为 NSPhotoLibraryAddUsageDescription in Info.plist). | | **`fileName`** | `string` | 要保存相册中图像的文件名 。 不包括扩展名。 仅限Android. | #### 媒体AlbumCreate | Prop | 类型 | | --- | --- | | **`name`** | `string` | #### 相册 Path 回复 | Prop | 类型 | | --- | --- | | **`path`** | `string` | ### 类型异名 #### 媒体领域 媒体排序属性 . [iOS 源代码](https://developer.apple.com/documentation/photokit/phfetchoptions) `'mediaType' | 'mediaSubtypes' | 'sourceType' | 'pixelWidth' | 'pixelHeight' | 'creationDate' | 'modificationDate' | 'isFavorite' | 'burstIdentifier'` ### 数字 #### 介质AlbumType | 成员 | 数值 | 说明 | | --- | --- | --- | | **`Smart`** | `'smart'` | 相册是"智能"相册(如Favorites或Recent Added) | | **`Shared`** | `'shared'` | 相册是共享相册 | | **`User`** | `'user'` | 相册是用户创建的相册 | ## 贡献者 感谢这些伟大的人[emoji 密钥](https://allcontributors.org/docs/en/emoji-key):
stewones
炖鱼
💻 📖 🚧		Zachary Keeton
扎卡里·基顿
💻		Pierre Grimaud
皮埃尔·格里莫德
📖		Talles Alves
高地阿尔维斯
🚧		Zyad Yasser
亚德·亚西尔
🚧
Manuel Rodríguez
曼努埃尔·罗德里格斯
💻 🚧		Michael
迈克尔
💻		Nisala Kalupahana
尼萨拉·卡卢帕哈纳
💻 📖 💡 🚧		Masahiko Sakakibara
坂原正彦
🚧		ha6-6ru
ha6-6ru (韩语)
💻
Stephan Fischer
斯蒂芬·菲舍尔
💻		Matheus Davidson
马修斯·戴维森
💻 📖		Maurice Wegner
莫里斯·韦格纳
💻		Samuel Ramos Muñoz
塞缪尔·拉莫斯·穆尼奥斯
💻
本项目遵循 [全部贡献者](https://github.com/all-contributors/all-contributors) 规格。 任何捐款都欢迎! ## 常见问题 ### @capacitor-community/media 是什么？ 用于保存并取回相片和视频,管理相册的电容插件\. ### 如何安装 @capacitor-community/media？ 在项目目录运行 npm install @capacitor-community/media，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @capacitor-community/media 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @capacitor-community/media 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @capacitor-community/media 可以商用吗？ @capacitor-community/media 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @capacitor-community/media 的下载量有多少？ 根据 npm 官方下载统计，@capacitor-community/media 在 2026/10/09 – 2026/11/07 这 30 天内被下载 317,460 次，日均约 10,582 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @capacitor-community/media 还在维护吗？ 最新版本 9\.1\.0 发布于 2026/03/27（7 个月前）；至今共发布 33 个版本，其中过去 12 个月发布了 4 个；首次发布于 2020/06/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。