云策 WordPress 开发者社区

块编辑器开发文档

@wordpress/vips

查看官方原文 ↗
💡 云策文档标注

概述

@wordpress/vips 是一个用于与 wasm-vips 交互的辅助包，提供图像处理功能，如批量调整大小、压缩、格式转换和旋转。它通过 WASM 内存优化性能，避免重复解码。

关键要点

  • 安装方式：通过 npm install @wordpress/vips --save 安装。
  • 核心 API：包括 batchResizeImage、compressImage、convertImageFormat、hasTransparency、resizeImage、rotateImage 等函数，以及对应的 vips 前缀版本。
  • 性能优化：使用 copyMemory() 在 WASM 内存中一次性解码图像，提高批量处理效率。
  • 功能特性：支持智能裁剪、EXIF 方向旋转、透明度检测和渐进式图像输出。
  • 参数类型：使用 ItemId、ArrayBuffer、BatchResizeConfig 等类型，返回 Promise 处理异步操作。

代码示例

// 示例：批量调整图像大小
const result = await batchResizeImage(id, buffer, 'image/jpeg', 'image/webp', resizes, true);
// 示例：旋转图像
const rotated = await rotateImage(id, buffer, 'image/png', 6);

注意事项

  • 函数参数如 quality 和 interlaced 需根据输出格式支持情况使用。
  • cancelOperations 函数用于取消指定 ItemId 的进行中操作，依赖 onProgress 回调检查。
  • EXIF 方向值范围是 1-8，对应不同的旋转和翻转组合。
📄 原文内容

Helper package to interact with wasm-vips.

Installation

Install the module

npm install @wordpress/vips --save

API Reference

batchResizeImage

Resizes an image into multiple sizes in a single pass using copyMemory().

Decodes the source image once, materializes it in WASM memory via copyMemory(), then uses thumbnailImage() for each sub-size. This avoids re-decoding the source for every thumbnail.

Parameters

  • id ItemId: Item ID.
  • buffer ArrayBuffer: Original file buffer.
  • inputType string: Input mime type.
  • outputType string: Output mime type for all results.
  • resizes BatchResizeConfig[]: Array of resize configurations.
  • smartCrop Whether to use smart cropping (i.e. saliency-aware).

Returns

  • Promise< BatchResizeResult[] >: Array of processed results, one per resize config.

cancelOperations

Cancels all ongoing image operations for a given item ID.

The onProgress callbacks check for an IDs existence in this list, killing the process if it’s absent.

Parameters

  • id ItemId: Item ID.

Returns

  • boolean Whether any operation was cancelled.

compressImage

Compresses an existing image using vips.

Parameters

  • id ItemId: Item ID.
  • buffer ArrayBuffer: Original file buffer.
  • type string: Mime type.
  • quality Desired quality.
  • interlaced Whether to use interlaced/progressive mode. Only used if the outputType supports it.

Returns

  • Promise< ArrayBuffer | ArrayBufferLike >: Compressed file data.

convertImageFormat

Converts an image to a different format using vips.

Parameters

  • id ItemId: Item ID.
  • buffer ArrayBuffer: Original file buffer.
  • inputType string: Input mime type.
  • outputType string: Output mime type.
  • quality Desired quality.
  • interlaced Whether to use interlaced/progressive mode. Only used if the outputType supports it.

hasTransparency

Determines whether an image has an alpha channel.

Parameters

  • buffer ArrayBuffer: Original file object.

Returns

  • Promise< boolean >: Whether the image has an alpha channel.

resizeImage

Resizes an image using vips.

Parameters

  • id ItemId: Item ID.
  • buffer ArrayBuffer: Original file buffer.
  • type string: Mime type.
  • resize ImageSizeCrop: Resize options.
  • smartCrop Whether to use smart cropping (i.e. saliency-aware).
  • quality Desired quality (0-1).

Returns

  • Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; originalWidth: number; originalHeight: number; } >: Processed file data plus the old and new dimensions.

rotateImage

Rotates an image based on EXIF orientation value.

EXIF orientation values: 1 = Normal (no rotation needed) 2 = Flipped horizontally 3 = Rotated 180° 4 = Flipped vertically 5 = Rotated 90° CCW and flipped horizontally 6 = Rotated 90° CW 7 = Rotated 90° CW and flipped horizontally 8 = Rotated 90° CCW

Parameters

  • id ItemId: Item ID.
  • buffer ArrayBuffer: Original file buffer.
  • type string: Mime type.
  • orientation number: EXIF orientation value (1-8).

Returns

  • Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; } >: Rotated file data plus the new dimensions.

vipsBatchResizeImage

Resizes an image into multiple sizes in a single pass using copyMemory().

Decodes the source image once, materializes it in WASM memory via copyMemory(), then uses thumbnailImage() for each sub-size. This avoids re-decoding the source for every thumbnail.

Parameters

  • id ItemId: Item ID.
  • buffer ArrayBuffer: Original file buffer.
  • inputType string: Input mime type.
  • outputType string: Output mime type for all results.
  • resizes BatchResizeConfig[]: Array of resize configurations.
  • smartCrop Whether to use smart cropping (i.e. saliency-aware).

Returns

  • Promise< BatchResizeResult[] >: Array of processed results, one per resize config.

vipsCancelOperations

Cancels all ongoing image operations for a given item ID.

The onProgress callbacks check for an IDs existence in this list, killing the process if it’s absent.

Parameters

  • id ItemId: Item ID.

Returns

  • boolean Whether any operation was cancelled.

vipsCompressImage

Compresses an existing image using vips.

Parameters

  • id ItemId: Item ID.
  • buffer ArrayBuffer: Original file buffer.
  • type string: Mime type.
  • quality Desired quality.
  • interlaced Whether to use interlaced/progressive mode. Only used if the outputType supports it.

Returns

  • Promise< ArrayBuffer | ArrayBufferLike >: Compressed file data.

vipsConvertImageFormat

Converts an image to a different format using vips.

Parameters

  • id ItemId: Item ID.
  • buffer ArrayBuffer: Original file buffer.
  • inputType string: Input mime type.
  • outputType string: Output mime type.
  • quality Desired quality.
  • interlaced Whether to use interlaced/progressive mode. Only used if the outputType supports it.

vipsHasTransparency

Determines whether an image has an alpha channel.

Parameters

  • buffer ArrayBuffer: Original file object.

Returns

  • Promise< boolean >: Whether the image has an alpha channel.

vipsResizeImage

Resizes an image using vips.

Parameters

  • id ItemId: Item ID.
  • buffer ArrayBuffer: Original file buffer.
  • type string: Mime type.
  • resize ImageSizeCrop: Resize options.
  • smartCrop Whether to use smart cropping (i.e. saliency-aware).
  • quality Desired quality (0-1).

Returns

  • Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; originalWidth: number; originalHeight: number; } >: Processed file data plus the old and new dimensions.

vipsRotateImage

Rotates an image based on EXIF orientation value.

EXIF orientation values: 1 = Normal (no rotation needed) 2 = Flipped horizontally 3 = Rotated 180° 4 = Flipped vertically 5 = Rotated 90° CCW and flipped horizontally 6 = Rotated 90° CW 7 = Rotated 90° CW and flipped horizontally 8 = Rotated 90° CCW

Parameters

  • id ItemId: Item ID.
  • buffer ArrayBuffer: Original file buffer.
  • type string: Mime type.
  • orientation number: EXIF orientation value (1-8).

Returns

  • Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; } >: Rotated file data plus the new dimensions.