输出选项

toFile

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

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

¥Write output image data to a file.

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

¥If an explicit output format is not selected, it will be inferred from the extension, with JPEG, PNG, WebP, AVIF, TIFF, GIF, DZI, and libvips’ V format supported. Note that raw pixel data is only supported for buffer output.

默认情况下，所有元数据都将被删除，其中包括基于 EXIF 的方向。请参阅 withMetadata 以了解对此的控制。

¥By default all metadata will be removed, which includes EXIF-based orientation. See withMetadata for control over this.

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

¥The caller is responsible for ensuring directory structures and permissions exist.

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

¥A Promise is returned when callback is not provided.

返回：Promise.<Object> - * 当没有提供回调时抛出：

¥Returns: Promise.<Object> - - when no callback is provided
Throws:

• Error 无效参数

  ¥Error Invalid parameters

参数	类型	描述
fileOut	string	写入图片数据的路径。
[callback]	function	使用两个参数 (err, info) 调用完成。info 包含输出图片 format、size（字节）、width、height、channels 和 premultiplied（指示是否使用预乘）。使用裁剪策略时还包含 cropOffsetLeft 和 cropOffsetTop。使用注意力裁剪策略时，还包含 attentionX 和 attentionY，即裁剪区域的焦点。动画输出还将包含 pageHeight 和 pages。如果图片是从文本创建的，还可能包含 textAutofitDpi（渲染字体的 dpi）。

示例

¥Example

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

示例

¥Example

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

toBuffer

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

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

¥Write output to a Buffer. JPEG, PNG, WebP, AVIF, TIFF, GIF and raw pixel data output are supported.

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

¥Use toFormat or one of the format-specific functions such as jpeg, png etc. to set the output format.

如果未设置明确的格式，则输出格式将与输入图片匹配，但 SVG 输入除外，它会变成 PNG 输出。

¥If no explicit format is set, the output format will match the input image, except SVG input which becomes PNG output.

默认情况下，所有元数据都将被删除，其中包括基于 EXIF 的方向。请参阅 withMetadata 以了解对此的控制。

¥By default all metadata will be removed, which includes EXIF-based orientation. See withMetadata for control over this.

callback（如果存在）获取三个参数 (err, data, info)，其中：

¥callback, if present, gets three arguments (err, data, info) where:

• err 是一个错误（如果有）。

  ¥err is an error, if any.

• data 是输出图片数据。

  ¥data is the output image data.

• info 包含输出图片 format、size（字节）、width、height、channels 和 premultiplied（指示是否使用预乘）。使用裁剪策略时还包含 cropOffsetLeft 和 cropOffsetTop。动画输出还将包含 pageHeight 和 pages。如果图片是从文本创建的，还可能包含 textAutofitDpi（渲染字体的 dpi）。

  ¥info contains the output image format, size (bytes), width, height, channels and premultiplied (indicating if premultiplication was used). When using a crop strategy also contains cropOffsetLeft and cropOffsetTop. Animated output will also contain pageHeight and pages. May also contain textAutofitDpi (dpi the font was rendered at) if image was created from text.

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

¥A Promise is returned when callback is not provided.

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

¥Returns: Promise.<Buffer> - - when no callback is provided

参数	类型	描述
[options]	Object
[options.resolveWithObject]	boolean	使用包含 data 和 info 属性的对象解析 Promise，而不是仅使用 data 解析。
[callback]	function

示例

¥Example

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

示例

¥Example

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

示例

¥Example

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

示例

¥Example

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 元数据保留在输出图片中。

¥Keep all EXIF metadata from the input image in the output image.

TIFF 输出不支持 EXIF 元数据。

¥EXIF metadata is unsupported for TIFF output.

自从：0.33.0 示例

¥Since: 0.33.0
Example

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

withExif

withExif(exif) ⇒ Sharp

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

¥Set EXIF metadata in the output image, ignoring any EXIF in the input image.

抛出：

¥Throws:

• Error 无效参数

  ¥Error Invalid parameters

自从：0.33.0

¥Since: 0.33.0

参数	类型	描述
exif	Object.<string, Object.<string, string>>	由键/值字符串对的 IFD0、IFD1 等键入的对象，以写入 EXIF 数据。

示例

¥Example

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 元数据。

¥Update EXIF metadata from the input image in the output image.

抛出：

¥Throws:

• Error 无效参数

  ¥Error Invalid parameters

自从：0.33.0

¥Since: 0.33.0

参数	类型	描述
exif	Object.<string, Object.<string, string>>	由键/值字符串对的 IFD0、IFD1 等键入的对象，以写入 EXIF 数据。

示例

¥Example

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

keepIccProfile

keepIccProfile() ⇒ Sharp

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

¥Keep ICC profile from the input image in the output image.

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

¥Where necessary, will attempt to convert the output colour space to match the profile.

自从：0.33.0 示例

¥Since: 0.33.0
Example

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

withIccProfile

withIccProfile(icc, [options]) ⇒ Sharp

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

¥Transform using an ICC profile and attach to the output image.

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

¥This can either be an absolute filesystem path or built-in profile name (srgb, p3, cmyk).

抛出：

¥Throws:

• Error 无效参数

  ¥Error Invalid parameters

自从：0.33.0

¥Since: 0.33.0

参数	类型	默认	描述
icc	string		输出 ICC 配置文件或内置配置文件名称（srgb、p3、cmyk）的绝对文件系统路径。
[options]	Object
[options.attach]	number	true	ICC 配置文件是否应该包含在输出图片元数据中？

示例

¥Example

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

keepMetadata

keepMetadata() ⇒ Sharp

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

¥Keep all metadata (EXIF, ICC, XMP, IPTC) from the input image in the output image.

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

¥The default behaviour, when keepMetadata is not used, is to convert to the device-independent sRGB colour space and strip all metadata, including the removal of any ICC profile.

自从：0.33.0 示例

¥Since: 0.33.0
Example

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

withMetadata

withMetadata([options]) ⇒ Sharp

将输入图片中的大部分元数据（EXIF、XMP、IPTC）保留在输出图片中。

¥Keep most metadata (EXIF, XMP, IPTC) from the input image in the output image.

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

¥This will also convert to and add a web-friendly sRGB ICC profile if appropriate.

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

¥Allows orientation and density to be set or updated.

抛出：

¥Throws:

• Error 无效参数

  ¥Error Invalid parameters

参数	类型	描述
[options]	Object
[options.orientation]	number	用于更新 EXIF Orientation 标签，1 到 8 之间的整数。
[options.density]	number	每英寸像素数 (DPI)。

示例

¥Example

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

示例

¥Example

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

toFormat

toFormat(format, options) ⇒ Sharp

强制输出为给定格式。

¥Force output to a given format.

抛出：

¥Throws:

• Error 不支持的格式或选项

  ¥Error unsupported format or options

参数	类型	描述
format	string | Object	作为字符串或具有 ‘id’ 属性的对象
options	Object	输出选项

示例

¥Example

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

jpeg

jpeg([options]) ⇒ Sharp

使用这些 JPEG 选项来输出图片。

¥Use these JPEG options for output image.

抛出：

¥Throws:

• Error 无效选项

  ¥Error Invalid options

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	80	质量，整数 1-100
[options.progressive]	boolean	false	使用逐行（隔行）扫描
[options.chromaSubsampling]	string	“‘4:2:0‘“	设置为 ‘4:4:4’ 以防止色度子采样，否则默认为 ‘4:2:0’ 色度子采样
[options.optimiseCoding]	boolean	true	优化哈夫曼编码表
[options.optimizeCoding]	boolean	true	optimiseCoding 的替代拼写
[options.mozjpeg]	boolean	false	使用 mozjpeg 默认值，相当于 { trellisQuantisation: true, overshootDeringing: true, optimiseScans: true, quantisationTable: 3 }
[options.trellisQuantisation]	boolean	false	应用网格量化
[options.overshootDeringing]	boolean	false	应用过冲去振铃
[options.optimiseScans]	boolean	false	优化逐行扫描，强制逐行扫描
[options.optimizeScans]	boolean	false	optimiseScans 的替代拼写
[options.quantisationTable]	number	0	要使用的量化表，整数 0-8
[options.quantizationTable]	number	0	quantizationTable 的替代拼写
[options.force]	boolean	true	强制 JPEG 输出，否则尝试使用输入格式

示例

¥Example

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

示例

¥Example

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

png

png([options]) ⇒ Sharp

使用这些 PNG 选项来输出图片。

¥Use these PNG options for output image.

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

¥By default, PNG output is full colour at 8 bits per pixel.

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

¥Indexed PNG input at 1, 2 or 4 bits per pixel is converted to 8 bits per pixel. Set palette to true for slower, indexed PNG output.

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

¥For 16 bits per pixel output, convert to rgb16 via toColourspace.

抛出：

¥Throws:

• Error 无效选项

  ¥Error Invalid options

参数	类型	默认	描述
[options]	Object
[options.progressive]	boolean	false	使用逐行（隔行）扫描
[options.compressionLevel]	number	6	zlib 压缩级别，0（最快、最大）到 9（最慢、最小）
[options.adaptiveFiltering]	boolean	false	使用自适应行过滤
[options.palette]	boolean	false	量化为具有 alpha 透明度支持的基于调色板的图片
[options.quality]	number	100	使用达到给定质量所需的最少颜色数，将 palette 设置为 true
[options.effort]	number	7	CPU 工作量，介于 1（最快）和 10（最慢）之间，将 palette 设置为 true
[options.colours]	number	256	调色板条目的最大数量，设置 palette 到 true
[options.colors]	number	256	options.colours 的替代拼写，将 palette 设置为 true
[options.dither]	number	1.0	Floyd-Steinberg 误差扩散水平，设置 palette 到 true
[options.force]	boolean	true	强制 PNG 输出，否则尝试使用输入格式

示例

¥Example

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

示例

¥Example

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

示例

¥Example

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

webp

webp([options]) ⇒ Sharp

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

¥Use these WebP options for output image.

抛出：

¥Throws:

• Error 无效选项

  ¥Error Invalid options

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	80	质量，整数 1-100
[options.alphaQuality]	number	100	Alpha 层的质量，整数 0-100
[options.lossless]	boolean	false	使用无损压缩模式
[options.nearLossless]	boolean	false	使用 near_lossless 压缩模式
[options.smartSubsample]	boolean	false	使用高质量色度子采样
[options.smartDeblock]	boolean	false	自动调整去块效应滤镜，可以改善低对比度边缘（慢）
[options.preset]	string	“‘default‘“	用于预处理/过滤的命名预设，其中之一：默认、照片、图片、绘图、图标、文本
[options.effort]	number	4	CPU 工作量，介于 0（最快）和 6（最慢）之间
[options.loop]	number	0	动画迭代次数，使用 0 表示无限动画
[options.delay]	number | Array.<number>		delay(s) between animation frames (in milliseconds)
[options.minSize]	boolean	false	防止使用动画关键帧来最小化文件大小（慢）
[options.mixed]	boolean	false	允许混合有损和无损动画帧（慢）
[options.force]	boolean	true	强制 WebP 输出，否则尝试使用输入格式

示例

¥Example

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

示例

¥Example

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

gif

gif([options]) ⇒ Sharp

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

¥Use these GIF options for the output image.

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

¥The first entry in the palette is reserved for transparency.

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

¥The palette of the input image will be re-used if possible.

抛出：

¥Throws:

• Error 无效选项

  ¥Error Invalid options

自从：0.30.0

¥Since: 0.30.0

参数	类型	默认	描述
[options]	Object		输出选项
[options.reuse]	boolean	true	重新使用现有的调色板，否则生成新的（慢）
[options.progressive]	boolean	false	使用逐行（隔行）扫描
[options.colours]	number	256	调色板条目的最大数量（包括透明度）介于 2 到 256 之间
[options.colors]	number	256	options.colours 的替代拼写
[options.effort]	number	7	CPU 工作量，介于 1（最快）和 10（最慢）之间
[options.dither]	number	1.0	Floyd-Steinberg 误差扩散水平，介于 0（最小）和 1（最大）之间
[options.interFrameMaxError]	number	0	透明度的最大帧间误差，介于 0（无损）和 32 之间
[options.interPaletteMaxError]	number	3	调色板重用的最大调色板间错误，介于 0 到 256 之间
[options.loop]	number	0	动画迭代次数，使用 0 表示无限动画
[options.delay]	number | Array.<number>		delay(s) between animation frames (in milliseconds)
[options.force]	boolean	true	强制输出 GIF，否则尝试使用输入格式

示例

¥Example

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

示例

¥Example

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

示例

¥Example

// 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();

示例

¥Example

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

jp2

jp2([options]) ⇒ Sharp

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

¥Use these JP2 options for output image.

需要编译为支持 OpenJPEG 的 libvips。预构建的二进制文件不包含此内容 - see 安装自定义 libvips。

¥Requires libvips compiled with support for OpenJPEG. The prebuilt binaries do not include this - see installing a custom libvips.

抛出：

¥Throws:

• Error 无效选项

  ¥Error Invalid options

自从：0.29.1

¥Since: 0.29.1

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	80	质量，整数 1-100
[options.lossless]	boolean	false	使用无损压缩模式
[options.tileWidth]	number	512	水平瓷砖尺寸
[options.tileHeight]	number	512	垂直瓷砖尺寸
[options.chromaSubsampling]	string	“‘4:4:4‘“	设置为 ‘4:2:0’ 以使用色度子采样

示例

¥Example

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

示例

¥Example

// 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 选项输出图片。

¥Use these TIFF options for output image.

density 可以通过 withMetadata 以像素/英寸为单位进行设置，而不是提供以像素/毫米为单位的 xres 和 yres。

¥The density can be set in pixels/inch via withMetadata instead of providing xres and yres in pixels/mm.

抛出：

¥Throws:

• Error 无效选项

  ¥Error Invalid options

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	80	质量，整数 1-100
[options.force]	boolean	true	强制 TIFF 输出，否则尝试使用输入格式
[options.compression]	string	“‘jpeg‘“	压缩选项：无、jpeg、deflate、packbits、ccittfax4、lzw、webp、zstd、jp2k
[options.predictor]	string	“‘horizontal‘“	压缩预测器选项：无、水平、浮动
[options.pyramid]	boolean	false	写一个图片金字塔
[options.tile]	boolean	false	写一个平铺的 tiff
[options.tileWidth]	number	256	水平瓷砖尺寸
[options.tileHeight]	number	256	垂直瓷砖尺寸
[options.xres]	number	1.0	水平分辨率（像素/毫米）
[options.yres]	number	1.0	垂直分辨率（像素/毫米）
[options.resolutionUnit]	string	“‘inch‘“	分辨率单位选项：英寸、厘米
[options.bitdepth]	number	8	将位深度减少到 1、2 或 4 位
[options.miniswhite]	boolean	false	将 1 位图片写入 miniswhite

示例

¥Example

// 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 选项来输出图片。

¥Use these AVIF options for output image.

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

¥AVIF image sequences are not supported. Prebuilt binaries support a bitdepth of 8 only.

抛出：

¥Throws:

• Error 无效选项

  ¥Error Invalid options

自从：0.27.0

¥Since: 0.27.0

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	50	质量，整数 1-100
[options.lossless]	boolean	false	使用无损压缩
[options.effort]	number	4	CPU 工作量，介于 0（最快）和 9（最慢）之间
[options.chromaSubsampling]	string	“‘4:4:4‘“	设置为 ‘4:2:0’ 以使用色度子采样
[options.bitdepth]	number	8	将位深度设置为 8、10 或 12 位

示例

¥Example

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

示例

¥Example

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

heif

heif(options) ⇒ Sharp

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

¥Use these HEIF options for output image.

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

¥Support for patent-encumbered HEIC images using hevc compression requires the use of a globally-installed libvips compiled with support for libheif, libde265 and x265.

抛出：

¥Throws:

• Error 无效选项

  ¥Error Invalid options

自从：0.23.0

¥Since: 0.23.0

参数	类型	默认	描述
options	Object		输出选项
options.compression	string		压缩格式：AV1、HEVC
[options.quality]	number	50	质量，整数 1-100
[options.lossless]	boolean	false	使用无损压缩
[options.effort]	number	4	CPU 工作量，介于 0（最快）和 9（最慢）之间
[options.chromaSubsampling]	string	“‘4:4:4‘“	设置为 ‘4:2:0’ 以使用色度子采样
[options.bitdepth]	number	8	将位深度设置为 8、10 或 12 位

示例

¥Example

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

jxl

jxl([options]) ⇒ Sharp

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

¥Use these JPEG-XL (JXL) options for output image.

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

¥This feature is experimental, please do not use in production systems.

需要编译 libvips 并支持 libjxl。预构建的二进制文件不包含此内容 - see 安装自定义 libvips。

¥Requires libvips compiled with support for libjxl. The prebuilt binaries do not include this - see installing a custom libvips.

抛出：

¥Throws:

• Error 无效选项

  ¥Error Invalid options

自从：0.31.3

¥Since: 0.31.3

参数	类型	默认	描述
[options]	Object		输出选项
[options.distance]	number	1.0	最大编码错误，介于 0（最高质量）和 15（最低质量）之间
[options.quality]	number		基于类似 JPEG 的质量计算 distance，介于 1 到 100 之间，如果指定则覆盖距离
[options.decodingTier]	number	0	目标解码速度等级，介于 0（最高质量）和 4（最低质量）之间
[options.lossless]	boolean	false	使用无损压缩
[options.effort]	number	7	CPU 工作量，介于 1（最快）和 9（最慢）之间
[options.loop]	number	0	动画迭代次数，使用 0 表示无限动画
[options.delay]	number | Array.<number>		delay(s) between animation frames (in milliseconds)

raw

raw([options]) ⇒ Sharp

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

¥Force output to be raw, uncompressed pixel data. Pixel ordering is left-to-right, top-to-bottom, without padding. Channel ordering will be RGB or RGBA for non-greyscale colourspaces.

抛出：

¥Throws:

• Error 无效选项

  ¥Error Invalid options

参数	类型	默认	描述
[options]	Object		输出选项
[options.depth]	string	“‘uchar‘“	位深度，其中之一：char、uchar（默认）、short、ushort、int、uint、float、complex、double、dpcomplex

示例

¥Example

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

示例

¥Example

// 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

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

¥Use tile-based deep zoom (image pyramid) output.

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

¥Set the format and options for tile images via the toFormat, jpeg, png or webp functions. Use a .zip or .szi file extension with toFile to write to a compressed archive file format.

当输出是 Buffer 或 Stream 时，容器将设置为 zip，否则将默认为 fs。

¥The container will be set to zip when the output is a Buffer or Stream, otherwise it will default to fs.

抛出：

¥Throws:

• Error 无效参数

  ¥Error Invalid parameters

参数	类型	默认	描述
[options]	Object
[options.size]	number	256	切片大小（以像素为单位），值介于 1 到 8192 之间。
[options.overlap]	number	0	平铺重叠（以像素为单位），值介于 0 到 8192 之间。
[options.angle]	number	0	瓷砖旋转角度，必须是 90 的倍数。
[options.background]	string | Object	”{r: 255, g: 255, b: 255, alpha: 1}“	背景颜色，由 color 模块解析，默认为白色，不透明。
[options.depth]	string		金字塔的深度，可能的值为 onepixel、onetile 或 one，默认值基于布局。
[options.skipBlanks]	number	-1	跳过图块生成的阈值。对于 8 位图片，范围为 0-255；对于 16 位图片，范围为 0-65535。google 布局的默认值为 5，否则为 -1（不跳过）。
[options.container]	string	“‘fs‘“	切片容器，值为 fs（文件系统）或 zip（压缩文件）。
[options.layout]	string	“‘dz‘“	文件系统布局，可能的值为 dz、iiif、iiif3、zoomify 或 google。
[options.centre]	boolean	false	平铺中的中心图片。
[options.center]	boolean	false	中心的替代拼写。
[options.id]	string	“‘https://example.com/iiif'“	当 layout 为 iiif/iiif3 时，设置 info.json 的 @id/id 属性
[options.basename]	string		当容器为 zip 时，zip 文件中的目录名称。

示例

¥Example

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
  });

示例

¥Example

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

示例

¥Example

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

timeout

timeout(options) ⇒ Sharp

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

¥Set a timeout for processing, in seconds. Use a value of zero to continue processing indefinitely, the default behaviour.

当 libvips 打开输入图片进行处理时，时钟启动。等待 libuv 线程变得可用所花费的时间不包括在内。

¥The clock starts when libvips opens an input image for processing. Time spent waiting for a libuv thread to become available is not included.

自从：0.29.2

¥Since: 0.29.2

参数	类型	描述
options	Object
options.seconds	number	处理停止之前的秒数

示例

¥Example

// 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')) { ... }
}