输出选项

toFile

toFile(fileOut, [callback]) ⇒ Promise.<Object>

将输出图像数据写入文件。

如果未选择明确的输出格式，则将从扩展中推断，支持 JPEG、PNG、WebP、AVIF、TIFF、GIF、DZI 和 libvips 的 V 格式。请注意，原始像素数据仅支持缓冲区输出。

默认情况下，将删除所有元数据，包括基于 EXIF 的方向。请参阅 withMetadata 以控制这一点。

调用者负责确保目录结构和权限存在。

未提供回调时返回 Promise。

返回值: Promise.<Object> - - 当没有提供回调时

Throws:

• 错误 参数无效

示例

sharp(input)
  .toFile('output.png', (err, info) => { ... });

示例

sharp(input)
  .toFile('output.png')
  .then(info => { ... })
  .catch(err => { ... });

toBuffer

toBuffer([options], [callback]) ⇒ Promise.<Buffer>

将输出写入缓冲区。支持 JPEG、PNG、WebP、AVIF、TIFF、GIF 和原始像素数据输出。

使用 toFormat 或格式特定的函数之一（如 jpeg、png 等）来设置输出格式。

如果未设置显式格式，则输出格式将与输入图像匹配，但 SVG 输入除外，SVG 输入将变为 PNG 输出。

默认情况下，将删除所有元数据，包括基于 EXIF 的方向。请参阅 withMetadata 以控制这一点。

如果存在回调，则回调将获取三个参数（[err]、[data]、[info]），其中：

• [err] 是错误（如果有）。
• [data] 是输出图像数据。
• [info] 包含输出图像格式、大小（字节）、宽度、高度、通道和预乘（指示是否使用了预乘）。使用裁剪策略时还包含 cropOffsetLeft 和 cropOffsetTop。如果图像是从文本创建的，还可能包含 textAutofitDpi（字体渲染时的 dpi）。

如果未提供回调，则返回 Promise。

返回: Promise.<Buffer> - - 当没有提供回调时

示例

sharp(input)
  .toBuffer((err, data, info) => { ... });

示例le

sharp(input)
  .toBuffer()
  .then(data => { ... })
  .catch(err => { ... });

示例

sharp(input)
  .png()
  .toBuffer({ resolveWithObject: true })
  .then(({ data, info }) => { ... })
  .catch(err => { ... });

示例

const { data, info } = await sharp('my-image.jpg')
  // output the raw pixels
  .raw()
  .toBuffer({ resolveWithObject: true });

// create a more type safe way to work with the raw pixel data
// this will not copy the data, instead it will change `data`s underlying ArrayBuffer
// so `data` and `pixelArray` point to the same memory location
const pixelArray = new Uint8ClampedArray(data.buffer);

// When you are done changing the pixelArray, sharp takes the `pixelArray` as an input
const { width, height, channels } = info;
await sharp(pixelArray, { raw: { width, height, channels } })
  .toFile('my-changed-image.jpg');

keepExif

keepExif() ⇒ Sharp

将输入图像中的所有 EXIF 元数据保留在输出图像中。

TIFF 输出不支持 EXIF 元数据。

自: 0.33.0

示例

const outputWithExif = await sharp(inputWithExif)
  .keepExif()
  .toBuffer();

withExif

withExif(exif) ⇒ Sharp

在输出图像中设置 EXIF 元数据，忽略输入图像中的任何 EXIF。

Throws:

• 错误 参数无效

自: 0.33.0

示例

const dataWithExif = await sharp(input)
  .withExif({
    IFD0: {
      Copyright: 'The National Gallery'
    },
    IFD3: {
      GPSLatitudeRef: 'N',
      GPSLatitude: '51/1 30/1 3230/100',
      GPSLongitudeRef: 'W',
      GPSLongitude: '0/1 7/1 4366/100'
    }
  })
  .toBuffer();

withExifMerge

withExifMerge(exif) ⇒ Sharp

在输出图像中更新输入图像的 EXIF 元数据。

Throws:

• 错误 参数无效

自: 0.33.0

示例

const dataWithMergedExif = await sharp(inputWithExif)
  .withExifMerge({
    IFD0: {
      Copyright: 'The National Gallery'
    }
  })
  .toBuffer();

keepIccProfile

keepIccProfile() ⇒ Sharp

将输入图像中的 ICC 配置文件保留在输出图像中。

必要时，将尝试转换输出色彩空间以匹配配置文件。

自: 0.33.0

示例

const outputWithIccProfile = await sharp(inputWithIccProfile)
  .keepIccProfile()
  .toBuffer();

withIccProfile

withIccProfile(icc, [options]) ⇒ Sharp

使用 ICC 配置文件进行转换并附加到输出图像。

这可以是绝对文件系统路径或内置配置文件名称（srgb、p3、cmyk）。

Throws:

• 错误 参数无效

自: 0.33.0

示例

const outputWithP3 = await sharp(input)
  .withIccProfile('p3')
  .toBuffer();

keepMetadata

keepMetadata() ⇒ Sharp

在输出图像中保留输入图像中的所有元数据（EXIF、ICC、XMP、IPTC）。

当不使用 keepMetadata 时，默认行为是转换为与设备无关的 sRGB 颜色空间并删除所有元数据，包括删除任何 ICC 配置文件。

自: 0.33.0

示例

const outputWithMetadata = await sharp(inputWithMetadata)
  .keepMetadata()
  .toBuffer();

withMetadata

withMetadata([options]) ⇒ Sharp

在输出图像中保留输入图像中的大多数元数据 (EXIF、XMP、IPTC)。

如果适用，这还将转换为并添加适合网络的 sRGB ICC 配置文件。

允许设置或更新方向和密度。

Throws:

• 错误 参数无效

示例

const outputSrgbWithMetadata = await sharp(inputRgbWithMetadata)
  .withMetadata()
  .toBuffer();

示例

// Set output metadata to 96 DPI
const data = await sharp(input)
  .withMetadata({ density: 96 })
  .toBuffer();

toFormat

toFormat(format, options) ⇒ Sharp

强制输出为给定格式。

Throws:

• 错误：不支持的格式或选项

示例

// Convert any input to PNG output
const data = await sharp(input)
  .toFormat('png')
  .toBuffer();

jpeg

jpeg([options]) ⇒ Sharp

使用这些 JPEG 选项输出图像。

Throws:

• 错误 选项无效

示例

// Convert any input to very high quality JPEG output
const data = await sharp(input)
  .jpeg({
    quality: 100,
    chromaSubsampling: '4:4:4'
  })
  .toBuffer();

示例

// Use mozjpeg to reduce output JPEG file size (slower)
const data = await sharp(input)
  .jpeg({ mozjpeg: true })
  .toBuffer();

png

png([options]) ⇒ Sharp

使用这些 PNG 选项输出图像。

默认情况下，PNG 输出为 8 位/像素的全彩色。

1、2 或 4 位/像素的索引 PNG 输入将转换为 8 位/像素。将调色板设置为 true 以获得较慢的索引 PNG 输出。

对于 16 位/像素输出，通过 toColourspace 转换为 rgb16。

Throws:

• 错误无效选项

示例

// Convert any input to full colour PNG output
const data = await sharp(input)
  .png()
  .toBuffer();

示例

// Convert any input to indexed PNG output (slower)
const data = await sharp(input)
  .png({ palette: true })
  .toBuffer();

示例

// Output 16 bits per pixel RGB(A)
const data = await sharp(input)
 .toColourspace('rgb16')
 .png()
 .toBuffer();

webp

webp([options]) ⇒ Sharp

使用这些 WebP 选项输出图像。

Throws:

• 错误 选项无效

示例

// Convert any input to lossless WebP output
const data = await sharp(input)
  .webp({ lossless: true })
  .toBuffer();

示例

// Optimise the file size of an animated WebP
const outputWebp = await sharp(inputWebp, { animated: true })
  .webp({ effort: 6 })
  .toBuffer();

gif

gif([options]) ⇒ Sharp

将这些 GIF 选项用于输出图像。

调色板中的第一个条目保留用于透明度。

如果可能，将重新使用输入图像的调色板。

Throws:

• 错误 选项无效

自: 0.30.0

示例

// Convert PNG to GIF
await sharp(pngBuffer)
  .gif()
  .toBuffer();

示例

// Convert animated WebP to animated GIF
await sharp('animated.webp', { animated: true })
  .toFile('animated.gif');

示例

// Create a 128x128, cropped, non-dithered, animated thumbnail of an animated GIF
const out = await sharp('in.gif', { animated: true })
  .resize({ width: 128, height: 128 })
  .gif({ dither: 0 })
  .toBuffer();

示例

// Lossy file size reduction of animated GIF
await sharp('in.gif', { animated: true })
  .gif({ interFrameMaxError: 8 })
  .toFile('optim.gif');

jp2

jp2([options]) ⇒ Sharp

使用这些 JP2 选项输出图像。

需要编译支持 OpenJPEG 的 libvips。预构建的二进制文件不包含此功能 - 请参阅安装自定义 libvips。

Throws:

• 错误 选项无效

自: 0.29.1

示例

// Convert any input to lossless JP2 output
const data = await sharp(input)
  .jp2({ lossless: true })
  .toBuffer();

示例

// Convert any input to very high quality JP2 output
const data = await sharp(input)
  .jp2({
    quality: 100,
    chromaSubsampling: '4:4:4'
  })
  .toBuffer();

tiff

tiff([options]) ⇒ Sharp

使用这些 TIFF 选项输出图像。

可以通过 withMetadata 以像素/英寸为单位设置密度，而不必以像素/毫米为单位提供 xres 和 yres。

Throws:

• 错误 选项无效

示例

// Convert SVG input to LZW-compressed, 1 bit per pixel TIFF output
sharp('input.svg')
  .tiff({
    compression: 'lzw',
    bitdepth: 1
  })
  .toFile('1-bpp-output.tiff')
  .then(info => { ... });

avif

avif([options]) ⇒ Sharp

使用这些 AVIF 选项输出图像。

不支持 AVIF 图像序列。预构建的二进制文件仅支持 8 位深度。

Throws:

• 错误 选项无效

自: 0.27.0

示例

const data = await sharp(input)
  .avif({ effort: 2 })
  .toBuffer();

示例

const data = await sharp(input)
  .avif({ lossless: true })
  .toBuffer();

heif

heif(options) ⇒ Sharp

使用这些 HEIF 选项输出图像。

使用 hevc 压缩支持受专利保护的 HEIC 图像需要使用全局安装的 libvips，该 libvips 编译时支持 libheif、libde265 和 x265。

Throws:

• 错误 选项无效

自: 0.23.0

示例

const data = await sharp(input)
  .heif({ compression: 'hevc' })
  .toBuffer();

jxl

jxl([options]) ⇒ Sharp

使用这些 JPEG-XL (JXL) 选项输出图像。

此功能为实验性功能，请勿在生产系统中使用。

需要使用 libjxl 支持编译的 libvips。预构建的二进制文件不包含此功能 - 请参阅安装自定义 libvips。

不支持图像元数据（EXIF、XMP）。

Throws:

• 错误无效选项

自: 0.31.3

raw

raw([options]) ⇒ Sharp

强制输出为原始、未压缩的像素数据。像素排序为从左到右、从上到下，无填充。对于非灰度色彩空间，通道排序将为 RGB 或 RGBA。

Throws:

• 错误 选项无效

示例

// Extract raw, unsigned 8-bit RGB pixel data from JPEG input
const { data, info } = await sharp('input.jpg')
  .raw()
  .toBuffer({ resolveWithObject: true });

示例

// Extract alpha channel as raw, unsigned 16-bit pixel data from PNG input
const data = await sharp('input.png')
  .ensureAlpha()
  .extractChannel(3)
  .toColourspace('b-w')
  .raw({ depth: 'ushort' })
  .toBuffer();

tile

tile([options]) ⇒ Sharp

使用基于图块的深度缩放（图像金字塔）输出。

通过 toFormat、jpeg、png 或 webp 函数设置图块图像的格式和选项。使用带有 toFile 的 .zip 或 .szi 文件扩展名写入压缩存档文件格式。

当输出为缓冲区或流时，容器将设置为 zip，否则将默认为 fs。

需要使用 libgsf 支持编译的 libvips。预构建的二进制文件不包含此功能 - 请参阅安装自定义 libvips。

Throws:

• 错误 参数无效

示例

sharp('input.tiff')
  .png()
  .tile({
    size: 512
  })
  .toFile('output.dz', function(err, info) {
    // output.dzi is the Deep Zoom XML definition
    // output_files contains 512x512 tiles grouped by zoom level
  });

示例

const zipFileWithTiles = await sharp(input)
  .tile({ basename: "tiles" })
  .toBuffer();

示例

const iiififier = sharp().tile({ layout: "iiif" });
readableStream
  .pipe(iiififier)
  .pipe(writeableStream);

timeout

timeout(options) ⇒ Sharp

设置处理超时时间（以秒为单位）。使用零值可无限期继续处理，这是默认行为。

当 libvips 打开输入图像进行处理时，时钟开始计时。等待 libuv 线程可用的时间不包括在内。

自： 0.29.2

示例

// Ensure processing takes no longer than 3 seconds
try {
  const data = await sharp(input)
    .blur(1000)
    .timeout({ seconds: 3 })
    .toBuffer();
} catch (err) {
  if (err.message.includes('timeout')) { ... }
}