输出选项

toFile

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

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

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

默认情况下，所有元数据将被移除，包括基于 EXIF 的方向。有关此方面的控制，请参见 withMetadata。

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

当未提供 callback 时，将返回一个 Promise。

返回: Promise.<Object> - 未提供回调时
抛出:

• Error 无效参数

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

示例

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

示例

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

toBuffer

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

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

使用 toFormat 或其他格式特定函数，如 jpeg、png 等来设置输出格式。

如果未设置明确的格式，则输出格式将与输入图像匹配，除非输入为 SVG，则输出将为 PNG。

默认情况下，所有元数据将被移除，包括基于 EXIF 的方向。有关此方面的控制，请参见 withMetadata。

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

• err 是一个错误（如果有）。
• data 是输出图像数据。
• info 包含输出图像的 format、size（字节）、width、height、channels 和 premultiplied（指示是否使用了预乘）。当使用裁剪策略时，还包含 cropOffsetLeft 和 cropOffsetTop。动画输出还将包含 pageHeight 和 pages。如果图像是从文本创建的，也可能包含 textAutofitDpi（字体渲染时的 DPI）。

底层的 ArrayBuffer 可能会被某些 JavaScript 运行时标记为不可传输。 请使用 toUint8Array 以获得可保证可传输的 ArrayBuffer。

当未提供 callback 时，将返回一个 Promise。

返回: Promise.<Buffer> - 未提供回调时

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

示例

const data = await sharp(input)
  .png()
  .toBuffer();

Example

const { data, info } = await sharp(input)
  .png()
  .toBuffer({ resolveWithObject: true });

示例

const { data, info } = await sharp('my-image.jpg')
  // 输出原始像素
  .raw()
  .toBuffer({ resolveWithObject: true });

// 创建一种更安全的方式来处理原始像素数据
// 这不会复制数据，而是会改变 `data` 的底层 ArrayBuffer
// 因此 `data` 和 `pixelArray` 指向相同的内存位置
const pixelArray = new Uint8ClampedArray(data.buffer);

// 当你完成更改 pixelArray 后，sharp 将 `pixelArray` 作为输入
const { width, height, channels } = info;
await sharp(pixelArray, { raw: { width, height, channels } })
  .toFile('my-changed-image.jpg');

toUint8Array

toUint8Array() ⇒ Promise.<{data: Uint8Array, info: Object}>

将输出写入一个由可转移 ArrayBuffer 支持的 Uint8Array。 支持 JPEG、PNG、WebP、AVIF、TIFF、GIF 和原始像素数据输出。

使用 toFormat 或其他格式特定函数，如 jpeg、png 等来设置输出格式。

如果未设置明确的格式，则输出格式将与输入图像匹配，除非输入为 SVG，则输出将为 PNG。

默认情况下，所有元数据将被移除，包括基于 EXIF 的方向。 有关此方面的控制，请参见 keepExif 和类似方法。

解析为一个包含以下内容的 Object：

• data 是由可转移 ArrayBuffer 支持的输出图像 Uint8Array。
• info 包含与输出图像相关的属性，如 width 和 height。

自: v0.35.0
示例

const { data, info } = await sharp(input).toUint8Array();

示例

const { data } = await sharp(input)
  .avif()
  .toUint8Array();
const base64String = data.toBase64();

withDensity

withDensity(density) ⇒ Sharp

在 EXIF 元数据中设置输出密度（DPI）。

抛出:

• Error 无效参数

自: 0.35.0

参数	类型	描述
density	number	每英寸像素数（DPI）。

示例

const data = await sharp(input)
  .withDensity(96)
  .toBuffer();

keepExif

keepExif() ⇒ Sharp

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

TIFF 输出不支持 EXIF 元数据。

自: 0.33.0 示例

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

withExif

withExif(exif) ⇒ Sharp

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

抛出:

• Error 无效参数

自: 0.33.0

参数	类型	描述
exif	Object.<string, Object.<string, string>>	以 IFD0、IFD1 等为键的对象，键值对将作为 EXIF 数据写入。

示例

const dataWithExif = await sharp(input)
  .withExif({
    IFD0: {
      Copyright: '国家美术馆'
    },
    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 元数据。

抛出:

• Error 无效参数

自: 0.33.0

参数	类型	描述
exif	Object.<string, Object.<string, string>>	按 IFD0、IFD1 等键入的对象，键值对写入为 EXIF 数据。

示例

const dataWithMergedExif = await sharp(inputWithExif)
  .withExifMerge({
    IFD0: {
      Copyright: '国家美术馆'
    }
  })
  .toBuffer();

保留 ICC 配置文件

keepIccProfile() ⇒ Sharp

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

当输入和输出色彩空间不同时，请与toColourspace一起使用，并可选择性地使用pipelineColourspace。

自: 0.33.0 示例

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

示例

const cmykOutputWithIccProfile = await sharp(cmykInputWithIccProfile)
  .pipelineColourspace('cmyk')
  .toColourspace('cmyk')
  .keepIccProfile()
  .toBuffer();

withIccProfile

withIccProfile(icc, [options]) ⇒ Sharp

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

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

抛出:

• Error 无效参数

自: 0.33.0

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

示例

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

keepGainMap

keepGainMap() ⇒ Sharp

If the input contains gain map metadata, attempts to process the image and gain map separately, and recombine them into a single output image.

This method is faster and should produce better results than withGainMap, but not all operations are supported.

Only JPEG input and output are supported. JPEG output options other than quality are ignored.

This feature is experimental and the API may change.

自: 0.35.0
示例

const outputWithResizedGainMap = await sharp(inputWithGainMap)
  .keepGainMap()
  .resize({ width: 64 })
  .toBuffer();

withGainMap

withGainMap() ⇒ Sharp

如果输入包含增益图元数据，则在进一步处理前使用它将主图像转换为 HDR（高动态范围）。 输入的增益图将被丢弃。

如果输出为 JPEG，则会生成并附加一个新的 ISO 21496-1 增益图。 除 quality 外的其他 JPEG 输出选项都会被忽略。

此功能处于实验阶段，API 可能会更改。

自: 0.35.0
示例

const outputWithRegeneratedGainMap = await sharp(inputWithGainMap)
  .withGainMap()
  .toBuffer();

keepXmp

keepXmp() ⇒ Sharp

在输出图像中保留输入图像的 XMP 元数据。

自: 0.34.3 示例

const outputWithXmp = await sharp(inputWithXmp)
  .keepXmp()
  .toBuffer();

withXmp

withXmp(xmp) ⇒ Sharp

在输出图像中设置 XMP 元数据。

支持 PNG、JPEG、WebP 和 TIFF 输出。

抛出:

• Error 无效参数

自: 0.34.3

参数	类型	描述
xmp	string	包含要嵌入输出图像的 XMP 元数据的字符串。

示例

const xmpString = `
  <?xml version="1.0"?>
  <x:xmpmeta xmlns:x="adobe:ns:meta/">
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
      <rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/">
        <dc:creator><rdf:Seq><rdf:li>John Doe</rdf:li></rdf:Seq></dc:creator>
      </rdf:Description>
    </rdf:RDF>
  </x:xmpmeta>`;

const data = await sharp(input)
  .withXmp(xmpString)
  .toBuffer();

保留元数据

keepMetadata() ⇒ Sharp

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

当未使用 keepMetadata 时，默认行为是转换为设备独立的 sRGB 颜色空间并剥离所有元数据，包括移除任何 ICC 配置文件。

自: 0.33.0 示例

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

withMetadata

withMetadata([options]) ⇒ Sharp

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

If applicable, this will also convert and add a web-friendly sRGB ICC profile.

Allows setting or updating orientation and density.

Throws:

• Error Invalid parameters

参数	类型	描述
[options]	Object
[options.orientation]	number	Used to update the EXIF Orientation tag, an integer between 1 and 8.
[options.density]	number	Pixels per inch (DPI).

示例

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

强制输出为给定格式。

抛出:

• Error 不支持的格式或选项

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

示例

// 将任何输入转换为 PNG 输出
const data = await sharp(input)
  .toFormat('png')
  .toBuffer();

jpeg

jpeg([options]) ⇒ Sharp

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

抛出:

• Error 无效选项

参数	类型	默认	描述
[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	优化哈夫曼编码表的另一种拼写
[options.mozjpeg]	boolean	false	使用 mozjpeg 默认值，相当于 { trellisQuantisation: true, overshootDeringing: true, optimiseScans: true, quantisationTable: 3 }
[options.trellisQuantisation]	boolean	false	应用 trellis 量化
[options.overshootDeringing]	boolean	false	应用过冲去锯齿
[options.optimiseScans]	boolean	false	优化渐进扫描，强制渐进
[options.optimizeScans]	boolean	false	优化渐进扫描的另一种拼写
[options.quantisationTable]	number	0	要使用的量化表，整数 0-8
[options.quantizationTable]	number	0	量化表的另一种拼写
[options.force]	boolean	true	强制 JPEG 输出，否则尝试使用输入格式

示例

// 将任何输入转换为非常高质量的 JPEG 输出
const data = await sharp(input)
  .jpeg({
    quality: 100,
    chromaSubsampling: '4:4:4'
  })
  .toBuffer();

示例

// 使用 mozjpeg 减小输出 JPEG 文件大小（较慢）
const data = await sharp(input)
  .jpeg({ mozjpeg: true })
  .toBuffer();

png

png([options]) ⇒ Sharp

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

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

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

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

抛出:

• Error 无效选项

参数	类型	默认	描述
[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 输出，否则尝试使用输入格式

示例

// 将任何输入转换为全彩色 PNG 输出
const data = await sharp(input)
  .png()
  .toBuffer();

示例

// 将任何输入转换为索引 PNG 输出（较慢）
const data = await sharp(input)
  .png({ palette: true })
  .toBuffer();

示例

// 输出 16 位每像素 RGB(A)
const data = await sharp(input)
 .toColourspace('rgb16')
 .png()
 .toBuffer();

webp

webp([options]) ⇒ Sharp

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

抛出:

• Error 无效选项

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	80	质量，整数 1-100
[options.alphaQuality]	number	100	alpha 层质量，整数 0-100
[options.lossless]	boolean	false	使用无损压缩模式
[options.nearLossless]	boolean	false	使用近无损压缩模式
[options.smartSubsample]	boolean	false	使用高质量色度子采样
[options.smartDeblock]	boolean	false	自动调整去块滤波器，可改善低对比度边缘（较慢）
[options.preset]	string	"'default'"	预处理/滤波的命名预设，取值之一：default、photo、picture、drawing、icon、text
[options.effort]	number	4	CPU 努力程度，在 0（最快）和 6（最慢）之间
[options.loop]	number	0	动画迭代次数，使用 0 表示无限动画
[options.delay]	number | Array.<number>		动画帧之间的延迟（以毫秒为单位）
[options.minSize]	boolean	false	防止使用动画关键帧以最小化文件大小（较慢）
[options.mixed]	boolean	false	允许有损和无损动画帧混合（较慢）
[options.exact]	boolean	false	保留透明像素中的颜色数据
[options.force]	boolean	true	强制 WebP 输出，否则尝试使用输入格式

示例

// 将任何输入转换为无损 WebP 输出
const data = await sharp(input)
  .webp({ lossless: true })
  .toBuffer();

示例

// 优化动画 WebP 的文件大小
const outputWebp = await sharp(inputWebp, { animated: true })
  .webp({ effort: 6 })
  .toBuffer();

gif

gif([options]) ⇒ Sharp

使用这些 GIF 选项为输出图像设置。

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

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

抛出:

• Error 无效选项

自: 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.keepDuplicateFrames]	boolean	false	在输出中保留重复帧，而不是将它们合并。
[options.loop]	number	0	动画迭代次数，使用 0 表示无限动画
[options.delay]	number | Array.<number>		动画帧之间的延迟（以毫秒为单位）
[options.force]	boolean	true	强制 GIF 输出，否则尝试使用输入格式

示例

// 将 PNG 转换为 GIF
await sharp(pngBuffer)
  .gif()
  .toBuffer();

示例

// 将动画 WebP 转换为动画 GIF
await sharp('animated.webp', { animated: true })
  .toFile('animated.gif');

示例

// 创建一个 128x128 像素、裁剪的、非抖动的动画缩略图
const out = await sharp('in.gif', { animated: true })
  .resize({ width: 128, height: 128 })
  .gif({ dither: 0 })
  .toBuffer();

示例

// 动画 GIF 的有损文件大小缩减
await sharp('in.gif', { animated: true })
  .gif({ interFrameMaxError: 8 })
  .toFile('optim.gif');

jp2

jp2([options]) ⇒ Sharp

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

需要使用 OpenJPEG 编译的 libvips。 预构建的二进制文件不包括此项 - 请参阅 安装自定义 libvips。

抛出:

• Error 无效选项

自: 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’ 以使用色度子采样

示例

// 将任何输入转换为无损 JP2 输出
const data = await sharp(input)
  .jp2({ lossless: true })
  .toBuffer();

示例

// 将任何输入转换为非常高质量 JP2 输出
const data = await sharp(input)
  .jp2({
    quality: 100,
    chromaSubsampling: '4:4:4'
  })
  .toBuffer();

tiff

tiff([options]) ⇒ Sharp

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

通过 withMetadata 可以以每英寸像素设置 density，而不是提供 xres 和 yres 以每毫米像素。

抛出:

• Error 无效选项

参数	类型	默认	描述
[options]	Object		输出选项
[options.quality]	number	80	质量，整数 1-100
[options.force]	boolean	true	强制 TIFF 输出，否则尝试使用输入格式
[options.compression]	string	"'jpeg'"	压缩选项：none、jpeg、deflate、packbits、ccittfax4、lzw、webp、zstd、jp2k
[options.bigtiff]	boolean	false	使用 BigTIFF 变体（当 compression 为 none 时无效）
[options.predictor]	string	"'horizontal'"	压缩预测器选项：none、horizontal、float
[options.pyramid]	boolean	false	写入图像金字塔
[options.tile]	boolean	false	写入平铺 TIFF
[options.tileWidth]	number	256	水平瓦片大小，有效值为 1-32768 范围内的整数
[options.tileHeight]	number	256	垂直瓦片大小，有效值为 1-32768 范围内的整数
[options.xres]	number	1.0	水平分辨率，单位为像素/mm，有效值范围为 0.001-1000000
[options.yres]	number	1.0	垂直分辨率，单位为像素/mm，有效值范围为 0.001-1000000
[options.resolutionUnit]	string	"'inch'"	分辨率单位选项：inch、cm
[options.bitdepth]	number	0	将位深度降低到 1、2 或 4 位
[options.miniswhite]	boolean	false	将 1 位图像写为 miniswhite

示例

// 将 SVG 输入转换为 LZW 压缩、每像素 1 位 TIFF 输出
sharp('input.svg')
  .tiff({
    compression: 'lzw',
    bitdepth: 1
  })
  .toFile('1-bpp-output.tiff')
  .then(info => { ... });

avif

avif([options]) ⇒ Sharp

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

AVIF 图像序列不受支持。

抛出:

• Error 无效选项

自: 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 位
[options.tune]	string	"'auto'"	根据质量指标调整输出，可选 ‘auto’（默认）、‘iq’、‘psnr’ 或 ‘ssim’

示例

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 编译，并支持 libheif、libde265 和 x265。

抛出:

• Error 无效选项

自: 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 位
[options.tune]	string	"'auto'"	根据质量指标调整输出，可选 ‘auto’（默认）、‘iq’、‘psnr’ 或 ‘ssim’

示例

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

jxl

jxl([options]) ⇒ Sharp

使用这些 JPEG-XL（JXL）选项设置输出图像。

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

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

抛出:

• Error 无效选项

自: 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>		动画帧之间的延迟（以毫秒为单位）

raw

raw([options]) ⇒ Sharp

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

Throws:

• Error Invalid options

Parameter	Type	Default	Description
[options]	Object		Output options
[options.depth]	string	"'uchar'"	Bit depth, one of: char, uchar (default), short, ushort, int, uint, float, complex, double, dpcomplex

示例

// 从 JPEG 输入提取原始的无符号 8 位 RGB 像素数据
const { data, info } = await sharp('input.jpg')
  .raw()
  .toBuffer({ resolveWithObject: true });

示例

// 从 PNG 输入提取 alpha 通道作为原始的无符号 16 位像素数据
const data = await sharp('input.png')
  .ensureAlpha()
  .extractChannel(3)
  .toColourspace('b-w')
  .raw({ depth: 'ushort' })
  .toBuffer();

tile

tile([options]) ⇒ Sharp

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

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

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

抛出:

• Error 无效参数

参数	类型	默认	描述
[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	跳过瓦片生成的阈值。范围为 0-255（8 位图像），0-65535（16 位图像）。默认值为 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	centre 的另一种拼写。
[options.id]	string	"'https://example.com/iiif'"	当 layout 为 iiif/iiif3 时，设置 info.json 的 @id/id 属性
[options.basename]	string		当容器为 zip 时，zip 文件中的目录名称。

示例

sharp('input.tiff')
  .png()
  .tile({
    size: 512
  })
  .toFile('output.dz', function(err, info) {
    // output.dzi 是 Deep Zoom XML 定义
    // output_files 包含按缩放级别分组的 512x512 瓦片
  });

示例

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

示例

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

超时

timeout(options) ⇒ Sharp

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

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

自: 0.29.2

参数	类型	描述
options	Object
options.seconds	number	在超时后停止处理的秒数

示例

// 确保处理时间不超过 3 秒
try {
  const data = await sharp(input)
    .blur(1000)
    .timeout({ seconds: 3 })
    .toBuffer();
} catch (err) {
  if (err.message.includes('timeout')) { ... }
}