# @capawesome/capacitor-photo-manipulator 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/

版本：0\.1\.2
npm 元数据更新时间：2026-09-02T08:26:25.155Z
中文译文更新时间：2026-11-09T04:43:29.652Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-photo-manipulator
原文对照：https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/photo-manipulator/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：191 kB，42 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-07T18:36:16.561Z
- 最新版本发布：2026-09-02T08:26:24.741Z
- 近 30 天下载量：13963（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

无头图像的电容插件在Android,iOS,和Web上进行变形,如裁剪大小,旋转,翻转和格式等,包括HEIC到JPEG.

## 安装

```sh
npm install @capawesome/capacitor-photo-manipulator
```

也可以使用：`pnpm add @capawesome/capacitor-photo-manipulator`、`yarn add @capawesome/capacitor-photo-manipulator`、`bun add @capawesome/capacitor-photo-manipulator`

## README

# 相片操纵器插件

无头图像的电容插件会像裁剪一样进行变换,大小调整,旋转,翻转和格式转换,包括HEIC到JPEG.

[![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1)](https://cloud.capawesome.io/)

## 特征

-   🖼️ **无头变形**:裁剪,调整大小,旋转并翻转代码中的图像,没有任何UI.
-   🔄 **HEIC 到 JPEG 数据**: 将 HEIC 和 AVIF 相片转换为 JPEG, PNG 或 WebP, 并配有本地平台解码器. 没有WASM的blobs,没有WebView的内存钉.
-   📐 **右上输出**: EXIF方向在解码时被应用,因此输出总是向上.
-   🧠 **内存效率**: Bundes-aware下标解码,因此全分辨率位图在再缩放时永远不会被加载.
-   🕵️ **隐私友好**:所有元数据(如EXIF,GPS)通过再编码从输出中剥离.
-   📂 **文件输出**:结果被写入文件,因此即使是大图像也不会耗尽内存.
-   i **图像信息**:不解码像素数据而读取图像的尺寸和格式.
-   🔒 **App 存储安全**:只使用官方平台API.
-   🤝 **兼容性**: 与 [相片编辑器](https://capawesome.io/docs/sdks/capacitor/photo-editor/), (中文(简体) ), [爱沙尼亚文](https://capawesome.io/docs/sdks/capacitor/exif/) 财务报告和审定财务报表 [文件压缩器](https://capawesome.io/docs/sdks/capacitor/file-compressor/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

当应用程序需要从代码处理图像时,通常使用相片操纵器插件,而不使用任何UI,例如:

-   **HEIC 到 JPEG 转换**:在上传前将iPhone上所拍摄的照片转换为JPEG,因此服务器和浏览器可以显示.
-   **缩略图生成**:将图像裁剪并缩放为小预览,并有内存高效的下标解码.
-   **上传缩小大小**: 调整图像大小并用更低的编码 `quality` 在上传到服务器之前.
-   **隐私安全共享**:在没有元数据的情况下共享图像,因为所有元数据(如EXIF,GPS)都通过再编码从输出中剥去.
-   **方向修正**: 出出正向图像,因为EXIF方向在解码时被应用.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.x.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

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

然后使用下列提示:

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

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

```bash
npm install @capawesome/capacitor-photo-manipulator
npx cap sync
```

### 机器人

#### 变量

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

-   `$androidxExifInterfaceVersion` 版本 `androidx.exifinterface:exifinterface` (默认 : `1.4.1`(中文(简体) )

### iOS系统

在iOS上,此插件使用 [图一/ 欧](https://developer.apple.com/documentation/imageio) 财务报告和审定财务报表 [核心图形](https://developer.apple.com/documentation/coregraphics) 框架。 不需要额外的配置.

### 网页

此插件提供了基于 : [相机 API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API). HEIC和AVIF图像无法被大多数浏览器解码,这正是本地执行存在的原因(参见: [格式支持](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-format-support)) (中文(简体) ).

## 配置

此插件不需要配置 .

## 使用量

以下示例显示如何将一幅图像转换为另一种格式,创建缩略图,并读取一幅图像的尺寸和格式.

已转换的图像被写入缓存目录中的新文件并被删除在下一次应用发布时. 如果您想要保留, 请将其移动到永久位置, 例如使用 `rename(...)` 方法 [文件系统](https://capacitorjs.com/docs/apis/filesystem) 插件 .

### 将 HEIC 图像转换为 JPEG

使用 `format` 选项 `transform(...)` 将图像转换成另一种格式的方法,例如,在iPhone上拍摄的HEIC相片被转换为JPEG。 这个 `quality` 选项控制输出文件的压缩 :

```typescript
import { PhotoManipulator, ImageFormat } from '@capawesome/capacitor-photo-manipulator';

const convertHeicToJpeg = async () => {
  // Convert an HEIC photo (e.g. taken on an iPhone) to JPEG
  const { path } = await PhotoManipulator.transform({
    path: 'file:///var/mobile/.../photo.heic',
    format: ImageFormat.Jpeg,
    quality: 0.9,
  });
  return path;
};
```

### 创建缩略图

合并 `crop`, (中文(简体) ), `resize`, (中文(简体) ), `rotate` 并在一个呼叫中翻转选项。 操作总是按固定顺序进行 → 调整大小 → 旋转 → 翻:

```typescript
import { PhotoManipulator } from '@capawesome/capacitor-photo-manipulator';

const createThumbnail = async () => {
  // Crop, resize, rotate and flip in one call
  const { path, width, height } = await PhotoManipulator.transform({
    path: 'file:///var/mobile/.../photo.jpeg',
    crop: { x: 100, y: 100, width: 1080, height: 1080 },
    resize: { width: 256 },
    rotate: 90,
    flipHorizontal: true,
  });
  return { path, width, height };
};
```

### 读取图像的尺寸和格式

使用 `getInfo(...)` 在可能情况下不解码像素数据而读取图像的尺寸和格式的方法:

```typescript
import { PhotoManipulator } from '@capawesome/capacitor-photo-manipulator';

const getInfo = async () => {
  const { width, height, format } = await PhotoManipulator.getInfo({
    path: 'file:///var/mobile/.../photo.heic',
  });
  return { width, height, format };
};
```

## API 密码

-   [`getInfo(...)`](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-getinfo)
-   [`transform(...)`](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-transform)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-interfaces)
-   [数字](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-enums)

### 获取信息(...)

```typescript
getInfo(options: GetInfoOptions) => Promise<GetInfoResult>
```

获得图像的尺寸和格式而不解码 尽可能提供像素数据.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetInfoOptions](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-getinfooptions)` |

**回返情况:** `Promise<[GetInfoResult](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-getinforesult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 转换(...)

```typescript
transform(options: TransformOptions) => Promise<TransformResult>
```

应用一个或多个转换到图像并写入 生成新文件.

操作总是按下列固定顺序进行: 轮回 轮回 需要联系多通电话 一个不同的顺序.

解码时应用源图像的 EXIF 方向 这样输出总是直立的。 所有其他元数据(例如EXIF, GPS)被再编码剥去.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[TransformOptions](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-transformoptions)` |

**回返情况:** `Promise<[TransformResult](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-transformresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 接口

#### 获取信息结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`format`** | `string | null` | 图像格式或 `null` 如果无法确定格式。 该值由平台解码器提供,并可能因同一文件(例如. `heic` 在iOS和网络上,但是 `heif` (原始内容存档于2018-09-21). Android. | 0.1.0 (中文(简体) ) |
| **`height`** | `number` | EXIF方向后图像以像素显示的高度已被应用. | 0.1.0 (中文(简体) ) |
| **`width`** | `number` | EXIF方向后图像以像素表示的宽度已被应用. | 0.1.0 (中文(简体) ) |

#### 获取信息选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`path`** | `string` | 图像文件的路径 。 在Android和iOS上,只有本地文件路径和 `file://` URI得到支持. 在网络上,任何可获取的URL(例如. `https://`, (中文(简体) ), `blob:`, (中文(简体) ), `data:`) 得到支持. | 0.1.0 (中文(简体) ) |

#### 变换结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`height`** | `number` | 变相图像以像素表示的高度. | 0.1.0 (中文(简体) ) |
| **`path`** | `string` | 已转换图像文件的路径 。 在Android和iOS上,文件被存储在缓存目录中,并在下一次应用发布时被删除. 移动到永久位置, 如果您想要保留它 。 在网络上,路径是一个对象URL. | 0.1.0 (中文(简体) ) |
| **`width`** | `number` | 变形图像以像素表示的宽度. | 0.1.0 (中文(简体) ) |

#### 变换选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`crop`** | `[CropOptions](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-cropoptions)` | 收割源图像的区域,以源像素表示. 区域必须在源图像的界限之内. |  | 0.1.0 (中文(简体) ) |
| **`flipHorizontal`** | `boolean` | 是否水平翻转图像 . | `false` | 0.1.0 (中文(简体) ) |
| **`flipVertical`** | `boolean` | 是否垂直翻转图像 . | `false` | 0.1.0 (中文(简体) ) |
| **`format`** | `[ImageFormat](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-imageformat)` | 输出文件的格式 。 在iOS上, [`ImageFormat.Webp`](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-imageformat) 不支持和拒绝 `UNSUPPORTED_FORMAT` 错误代码 . | `ImageFormat.Jpeg` | 0.1.0 (中文(简体) ) |
| **`path`** | `string` | 要转换的图像文件路径 。 在Android和iOS上,只有本地文件路径和 `file://` URI得到支持. 在网络上,任何可获取的URL(例如. `https://`, (中文(简体) ), `blob:`, (中文(简体) ), `data:`) 得到支持. |  | 0.1.0 (中文(简体) ) |
| **`quality`** | `number` | 输出文件的质量介于 `0` 财务报告和审定财务报表 `1`。仅在 `format` 实值 [`ImageFormat.Jpeg`](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-imageformat) 或者说 [`ImageFormat.Webp`](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-imageformat)。 。 。 . | `0.9` | 0.1.0 (中文(简体) ) |
| **`resize`** | `[ResizeOptions](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-resizeoptions)` | 将图像大小调整到像素的目标大小。 如果只有一个 `width` 财务报告和审定财务报表 `height` 提供宽度比。 调整大小在收成后应用. |  | 0.1.0 (中文(简体) ) |
| **`rotate`** | `number` | 顺时针角度来旋转图像,以度为单位。 一定是这样 `90`, (中文(简体) ), `180` 或者说 `270`。 。 。 . | `0` | 0.1.0 (中文(简体) ) |

#### 裁剪选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`height`** | `number` | 作物区域以像素为单位的高度. | 0.1.0 (中文(简体) ) |
| **`width`** | `number` | 以像素表示的作物区域的宽度. | 0.1.0 (中文(简体) ) |
| **`x`** | `number` | 以像素为单位的作物区域水平相抵,从源图像的左边缘测量出. | 0.1.0 (中文(简体) ) |
| **`y`** | `number` | 以像素为单位的作物区域垂直相抵,从源图像的上边缘测量出. | 0.1.0 (中文(简体) ) |

#### 更改选项大小

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`height`** | `number` | 以像素计的目标高度. 如果只有一个 `width` 财务报告和审定财务报表 `height` 提供宽度比. | 0.1.0 (中文(简体) ) |
| **`width`** | `number` | 目标宽度以像素为单位. 如果只有一个 `width` 财务报告和审定财务报表 `height` 提供宽度比. | 0.1.0 (中文(简体) ) |

### 数字

#### 图像格式

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`Jpeg`** | `'JPEG'` | JPEG (英语:`image/jpeg`) (中文(简体) ). | 0.1.0 (中文(简体) ) |
| **`Png`** | `'PNG'` | 巴布亚新几内亚`image/png`) (中文(简体) ). | 0.1.0 (中文(简体) ) |
| **`Webp`** | `'WEBP'` | 网络P (`image/webp`) (中文(简体) ). 仅在Android和Web上提供. | 0.1.0 (中文(简体) ) |

## 格式支持

图像的格式可以从平台上解码并编码,以依赖平台:

### 输入( 十进制)

| 格式 | 机器人 | iOS系统 | 网页 |
| --- | --- | --- | --- |
| JPEG 组合 | ✅ | ✅ | ✅ |
| 巴布亚新几内亚 | ✅ | ✅ | ✅ |
| 网络P | ✅ | ✅ | ✅ |
| 全球投资框架 | ✅ | ✅ | ✅ |
| 银行 | ✅ | ✅ | ✅ |
| 赫尔辛基 | QQ (Android 9+) (英语) | ✅ | ❌ |
| AVIF 亚军 | QQ (Android 12+) (英语) | (iOS 16+) (中文(简体) ) | 浏览器依赖 |

### 输出( 编码)

| 格式 | 机器人 | iOS系统 | 网页 |
| --- | --- | --- | --- |
| JPEG 组合 | ✅ | ✅ | ✅ |
| 巴布亚新几内亚 | ✅ | ✅ | ✅ |
| 网络P | ✅ | ❌ | 浏览器依赖 |

如果一个图像无法在当前平台上被解码或编码,则该调用被拒绝 `UNSUPPORTED_FORMAT` 错误代码,所以你可以优雅地退后.

## 内存

这个插件旨在保持内存脚印的低水平, 即使对于非常大的图像:

-   当a `resize` 提供了目标,图像被解码为下取样(使用 `inSampleSize` 机器人和 `kCGImageSourceThumbnailMaxPixelSize` iOS)上,因此全分辨率位图从未被装入内存.
-   变形在背景队列上一次处理一次.
-   结果被写入一个文件,而不是作为基数64的数据被返回.

对于最小可能的记忆足迹,总是提供 `resize` 目标,如果你不需要 完整的分辨率.

## 元数据

源图像的EXIF方向在解码过程中被应用,这样输出总是向上. 所有其他元数据(如EXIF,GPS)被再编码剥去. 使用 [爱沙尼亚文](https://capawesome.io/docs/sdks/capacitor/exif/) 如果您想要读取源图像的元数据并将其写回已转换的图像,则插件 .

## 财务问题

### 此插件与其他类似插件有何不同?

它使用本地平台解码器进行无头图像转换——裁剪,大小调整,旋转,翻转和格式转换,包括HEIC和AVIF转换为JPEG,PNG或WebP,没有UI和WebView内存突起. 它解码了有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-无界-有界-有界-有界-有界-无界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界-有界- 它在Android,iOS和Web上工作,只使用官方平台API,被完全打入并保持了最新的Capacitor版本.

### 转换按什么顺序进行?

操作始终按以下固定顺序进行: 收成 → 大小调整 → 旋转 → 翻转. 如果您需要不同的顺序, 链条多 `transform(...)` ,将一个调用输出路径传递为下一个调用输入路径.

### 为何在应用程序重启后变换的图像会消失?

在Android和iOS上,被转换的图像被写入缓存目录中的新文件并被删除在下个应用程序发布会上. 如果您想要保留, 请将其移动到永久位置, 例如使用 `rename(...)` 官员的方法 [文件系统](https://capacitorjs.com/docs/apis/filesystem) 插件 .

### 该插件是否保存源图像的 EXIF 元数据 ?

不,EXIF方向在解码过程中被应用,这样输出总是直立的,所有其他元数据(如EXIF,GPS)通过再编码从输出中剥离. 这默认是方便隐私的。 如果你想保留元数据,请使用 [爱沙尼亚文](https://capawesome.io/docs/sdks/capacitor/exif/) 从源图像读取并写回已转换图像的插件.

### 为什么在iOS上转换到WebP失败?

在iOS上, `ImageFormat.Webp` 不支持作为输出格式,并且使用 `UNSUPPORTED_FORMAT` 错误代码 。 WebP输出仅在Android和Web上提供. 使用 `ImageFormat.Jpeg` 或者说 `ImageFormat.Png` 作为跨平台的替代品.

### 为什么我不能在网络上转换HEIC或AVIF图像?

网页执行基于Canvas API,大多数浏览器无法解码HEIC和AVIF图像. 正因为如此,原生实施才存在:在Android上(HEIC/HEIF为9+,AVIF为12+)和iOS上(AVIF为16+),插件使用原生平台解码器. 见 [格式支持](https://npmcn.com/package/%40capawesome/capacitor-photo-manipulator/#readme-format-support) 完整概览.

### 插件如何处理非常大的图像 ?

该插件旨在使内存足迹保持低水平. 当a `resize` 提供了目标,图像被解码为下图,因此全分辨率位图从不被装入内存,变换一次在背景队列上处理,结果被写入一个文件,而不是作为基数64的数据被返回. 对于最小可能的记忆足迹,总是提供 `resize` 目标,如果你不需要 完整的分辨率.

## 相关插件

-   [爱沙尼亚文](https://capawesome.io/docs/sdks/capacitor/exif/):从图像文件中读取,写入并删除EXIF元数据.
-   [文件压缩器](https://capawesome.io/docs/sdks/capacitor/file-compressor/): 压缩文件,支持PNG,JPEG,和WebP等图像格式.
-   [文件拾取器](https://capawesome.io/docs/sdks/capacitor/file-picker/):让用户从图片库或文件系统中选择要转换的图像.
-   [相片编辑器](https://capawesome.io/docs/sdks/capacitor/photo-editor/):让用户在已安装相片编辑应用程序中编辑相片.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/photo-manipulator/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/photo-manipulator/LICENSE)。 。 。 .

## 常见问题

### @capawesome/capacitor-photo-manipulator 是什么？

无头图像的电容插件在Android,iOS,和Web上进行变形,如裁剪大小,旋转,翻转和格式等,包括HEIC到JPEG\.

### 如何安装 @capawesome/capacitor-photo-manipulator？

在项目目录运行 npm install @capawesome/capacitor-photo-manipulator，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capawesome/capacitor-photo-manipulator 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capawesome/capacitor-photo-manipulator 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capawesome/capacitor-photo-manipulator 可以商用吗？

@capawesome/capacitor-photo-manipulator 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-photo-manipulator 的下载量有多少？

根据 npm 官方下载统计，@capawesome/capacitor-photo-manipulator 在 2026/10/09 – 2026/11/07 这 30 天内被下载 13,963 次，日均约 465 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capawesome/capacitor-photo-manipulator 还在维护吗？

最新版本 0\.1\.2 发布于 2026/09/02（2 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/07/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。