用于与 wasm-vips 交互的辅助包。

安装

安装该模块

npm install @wordpress/vips --save

要求

TypeScript 使用者需要 TypeScript 5 或更高版本。

API 参考

cancelOperations

取消指定项目 ID 的所有正在进行的图像操作。

onProgress 回调会检查该列表中是否存在该 ID，如果不存在，则终止该进程。

参数

  • id ItemId：项目 ID。

返回值

  • boolean 是否取消了任何操作。

compressImage

使用 vips 压缩现有图像。

参数

  • id ItemId：项目 ID。
  • buffer ArrayBuffer：原始文件缓冲区。
  • type string：MIME 类型。
  • options ConvertImageOptions：压缩选项。

返回值

  • Promise< ArrayBuffer | ArrayBufferLike >：压缩后的文件数据。

convertImageFormat

使用 vips 将图像转换为另一种格式。

参数

  • id ItemId：项目 ID。
  • buffer ArrayBuffer：原始文件缓冲区。
  • inputType string：输入 MIME 类型。
  • outputType string：输出 MIME 类型。
  • options ConvertImageOptions：转换选项。

getUltraHdrInfo

探测 JPEG，以确定其是否为包含嵌入增益图的 UltraHDR 图像。

成功时返回尺寸和 HDR 余量；如果缓冲区不是有效的 UltraHDR JPEG（没有增益图、解码失败或格式不受支持），则返回 null。

参数

  • buffer ArrayBuffer：图像缓冲区。

返回值

  • Promise< UltraHdrInfo | null >：UltraHDR 信息；如果缓冲区不是 UltraHDR，则为 null。

hasTransparency

确定图像是否具有可见透明度。

仅凭通道存在是不够的：PNG 编码器通常即使在每个像素都完全不透明时也会保留 alpha 通道，而动态 GIF 会为了基于处置方法的帧合成而声明透明颜色索引，却不会渲染任何可见的透明像素。此检查会加载第一帧（该帧中的任何透明度都是可见的——没有前一帧可继承），并对 alpha 通道进行采样，以查找实际透明的像素。

参数

  • buffer ArrayBuffer：原始文件对象。

返回值

  • Promise< boolean >：图像中是否有任何像素部分或完全透明。

resizeImage

使用 vips 调整图像大小。

UltraHDR JPEG 会被自动检测并保留：libvips 的 uhdrload* 优先级高于 jpegload*，因此 newFromBuffer/thumbnailBuffer 会在解码基础图像的同时解码增益图，并且在附加增益图时，jpegsave* 会在输出时委托给 uhdrsave*。

动态图像的子尺寸仅从第一帧生成，与 WordPress 核心的服务器端行为一致：GD 和 Imagick 在调整大小时都会将动态图像扁平化，并且 wp_calculate_image_srcset() 会防止扁平化后的子尺寸与动态全尺寸图像混入 srcset。加载所有帧（[n=-1]）会为每个子尺寸重新编码完整动态 GIF，对于较长动画需要数十秒，并且可能产生大于原始文件的子尺寸。参见 https://github.com/WordPress/gutenberg/issues/80266。

参数

  • id ItemId：项目 ID。
  • buffer ArrayBuffer：原始文件缓冲区。
  • type string：MIME 类型。
  • resize ImageSizeCrop：调整大小选项。
  • options ResizeImageOptions：其他调整大小选项。

返回值

  • Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; originalWidth: number; originalHeight: number; } >：处理后的文件数据以及原始尺寸和新尺寸。

rotateImage

根据 EXIF 方向值旋转图像。

EXIF 方向值：1 = 正常（无需旋转） 2 = 水平翻转 3 = 旋转 180° 4 = 垂直翻转 5 = 逆时针旋转 90° 并水平翻转 6 = 顺时针旋转 90° 7 = 顺时针旋转 90° 并水平翻转 8 = 逆时针旋转 90°

参数

  • id ItemId：项目 ID。
  • buffer ArrayBuffer：原始文件缓冲区。
  • type string：MIME 类型。
  • orientation number：EXIF 方向值（1-8）。

返回值

  • Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; } >：旋转后的文件数据以及新尺寸。

vipsCancelOperations

取消指定项目 ID 的所有正在进行的图像操作。

onProgress 回调会检查该列表中是否存在该 ID，如果不存在，则终止该进程。

参数

  • id ItemId：项目 ID。

返回值

  • boolean 是否取消了任何操作。

vipsCompressImage

使用 vips 压缩现有图像。

参数

  • id ItemId：项目 ID。
  • buffer ArrayBuffer：原始文件缓冲区。
  • type string：MIME 类型。
  • options ConvertImageOptions：压缩选项。

返回值

  • Promise< ArrayBuffer | ArrayBufferLike >：压缩后的文件数据。

vipsConvertImageFormat

使用 vips 将图像转换为另一种格式。

参数

  • id ItemId：项目 ID。
  • buffer ArrayBuffer：原始文件缓冲区。
  • inputType string：输入 MIME 类型。
  • outputType string：输出 MIME 类型。
  • options ConvertImageOptions：转换选项。

vipsGetUltraHdrInfo

探测 JPEG，以确定其是否为包含嵌入增益图的 UltraHDR 图像。

成功时返回尺寸和 HDR 余量；如果缓冲区不是有效的 UltraHDR JPEG（没有增益图、解码失败或格式不受支持），则返回 null。

参数

  • buffer ArrayBuffer：图像缓冲区。

返回值

  • Promise< UltraHdrInfo | null >：UltraHDR 信息；如果缓冲区不是 UltraHDR，则为 null。

vipsHasTransparency

确定图像是否具有可见透明度。

仅凭通道存在是不够的：PNG 编码器通常即使在每个像素都完全不透明时也会保留 alpha 通道，而动态 GIF 会为了基于处置方法的帧合成而声明透明颜色索引，却不会渲染任何可见的透明像素。此检查会加载第一帧（该帧中的任何透明度都是可见的——没有前一帧可继承），并对 alpha 通道进行采样，以查找实际透明的像素。

参数

  • buffer ArrayBuffer：原始文件对象。

返回值

  • Promise< boolean >：图像中是否有任何像素部分或完全透明。

vipsResizeImage

使用 vips 调整图像大小。

UltraHDR JPEG 会被自动检测并保留：libvips 的 uhdrload* 优先级高于 jpegload*，因此 newFromBuffer/thumbnailBuffer 会在解码基础图像的同时解码增益图，并且在附加增益图时，jpegsave* 会在输出时委托给 uhdrsave*。

动态图像的子尺寸仅从第一帧生成，与 WordPress 核心的服务器端行为一致：GD 和 Imagick 在调整大小时都会将动态图像扁平化，并且 wp_calculate_image_srcset() 会防止扁平化后的子尺寸与动态全尺寸图像混入 srcset。加载所有帧（[n=-1]）会为每个子尺寸重新编码完整动态 GIF，对于较长动画需要数十秒，并且可能产生大于原始文件的子尺寸。参见 https://github.com/WordPress/gutenberg/issues/80266。

参数

  • id ItemId：项目 ID。
  • buffer ArrayBuffer：原始文件缓冲区。
  • type string：MIME 类型。
  • resize ImageSizeCrop：调整大小选项。
  • options ResizeImageOptions：其他调整大小选项。

返回值

  • Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; originalWidth: number; originalHeight: number; } >：处理后的文件数据以及原始尺寸和新尺寸。

vipsRotateImage

根据 EXIF 方向值旋转图像。

EXIF 方向值：1 = 正常（无需旋转） 2 = 水平翻转 3 = 旋转 180° 4 = 垂直翻转 5 = 逆时针旋转 90° 并水平翻转 6 = 顺时针旋转 90° 7 = 顺时针旋转 90° 并水平翻转 8 = 逆时针旋转 90°

参数

  • id ItemId：条目 ID。
  • buffer ArrayBuffer：原始文件缓冲区。
  • type string：MIME 类型。
  • orientation number：EXIF 方向值（1-8）。

返回值

  • Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; } >：旋转后的文件数据及新的尺寸。