输出选项

输出选项

toFile

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

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

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

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

未提供callback时，将返回Promise。

参数

fileOut string 将图像数据写入的路径
callback Function ? 在完成时调用了两个参数(err, info). info 包含输出图像format, size (bytes),width, height, channels和premultiplied (表示是否使用了预乘法)。当使用裁剪策略时，还包含cropOffsetLeft and 及cropOffsetTop.

例子

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

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

无效参数，将引发错误 Error

当没有提供callback时，返回 Promise <Object >

toBuffer

将输出写入缓冲区。支持JPEG，PNG，WebP，AVIF, TIFF, GIF和RAW输出。

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

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

如果提供callback, 将返回3个参数 (err, data, info):

err 错误信息（如果有）。
data 输出图像数据。
info 包含输出图像format, size (bytes), width, height, channels 和premultiplied （指示是否使用预乘）。使用裁剪策略时，还包含cropOffsetLeft和cropOffsetTop。
contains the output image format, size (bytes), width, height,

未提供callback时，将返回Promise。

参数

options Object ?
- options.resolveWithObject boolean ? 使用包含data和info属性的对象来解决Promise，而不是仅使用data解决。
callback Function ?

例子

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

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

sharp(input)
  .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');

未提供callback时，将返回Promise <Buffer > 。

withMetadata

将来自输入图像的所有元数据（EXIF，XMP，IPTC）包括在输出图像中。除非提供自定义输出配置文件，否则这也将转换为并添加对Web友好的sRGB ICC配置文件。

如果withMetadata不使用默认行为，则将其转换为与设备无关的sRGB色彩空间，并剥离所有元数据，包括删除任何ICC配置文件。

参数

options Object ?
- options.orientation number ? 值介于1到8之间，用于更新EXIF Orientation标签。
- options.icc string ? 输出ICC配置文件的文件系统路径，默认为sRGB。
- options.exif Object <Object > 对象由 IFD0, IFD1等键/值字符串对组成，以 EXIF 数据形式写入。(可选，默认{})
- options.density number ? 每英寸像素数(DPI)

例子

sharp('input.jpg')
  .withMetadata()
  .toFile('output-with-metadata.jpg')
  .then(info => { ... });

// Set "IFD0-Copyright" in output EXIF metadata
const data = await sharp(input)
  .withMetadata({
    exif: {
      IFD0: {
        Copyright: 'Wernham Hogg'
      }
    }
  })
  .toBuffer();

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

无效参数将抛出错误 Error

返回 Sharp

toFormat

强制输出为给定格式。

参数

format (string | Object ) 作为字符串或具有’id’属性的Object
options Object 输出选项

例子

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

不支持的格式或选项将引发错误 Error

返回 Sharp

jpeg

使用JPEG选项输出图像。

参数

options Object ? 输出选项
- options.quality number 输出质量，整数1-100（可选，默认80）
- options.progressive boolean 使用渐进式（隔行扫描）（可选，默认false）
- options.chromaSubsampling string 设置为'4:4:4'以防止色度二次采样，否则默认为'4:2:0'色度二次采样（可选，默认'4:2:0'）
- options.optimiseCoding boolean 优化霍夫曼编码表（可选，默认true）
- options.optimizeCoding boolean optimiseCoding的替代拼写（可选，默认true）
- options.mozjpeg boolean 使用 mozjpeg 默认值，等价于{ trellisQuantisation: true, overshootDeringing: true, optimiseScans: true, quantisationTable: 3 } (可选，默认false)
- options.trellisQuantisation boolean 应用网格量化，要求libvips编译时支持mozjpeg（可选，默认false）
- options.overshootDeringing boolean 应用过冲延迟，需要libvips编译并支持mozjpeg（可选，默认false）
- options.optimiseScans boolean 优化渐进式扫描，强制渐进式，需要libmops编译并支持mozjpeg（可选，默认false）
- options.optimizeScans boolean aoptimiseScans 的可选拼写(可选，默认false)
- options.quantisationTable number 要使用的量化表，整数0-8，要求libvips编译时支持mozjpeg（可选，默认0）
- options.quantizationTable number 量化表的替代拼写，要求libvips编译时支持mozjpeg（可选，默认0）
- options.force boolean boolean JPEG输出，否则尝试使用输入格式（可选，默认true）

例子

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

无效的选项将引发 Error

返回 Sharp

png

对输出图像使用 PNG 选项。

默认情况下，PNG 输出是每像素8或16位的全彩色。以每像素1、2或4位为索引的 PNG 输入被转换为每像素8位。对于较慢的索引 PNG 输出，将palette设置为 true。

参数

options Object ?
- options.progressive boolean 使用渐进(隔行)扫描(可选，默认false)
- options.compressionLevel number zlib的压缩级别，0(最快的，最大的)到9(最慢的，最小的)(可选的，默认值为6)
- options.adaptiveFiltering boolean 使用自适应行过滤（可选，默认false）
- options.palette boolean 量化为具有alpha透明性支持的基于调色板的图像，要求libvips编译时支持libimagequant（可选，默认false）
- options.quality number 使用达到给定质量所需的最低颜色数，必须设置palette为true，要求libvips编译时支持libimagequant（可选，默认100）
- options.effort number 设置CPU 工作量，介于1(最快的)和10(最慢的)之间，设置palette 为true (可选，默认7)
- options.colours number 调色板项目的最大数目，必须设置palette为true，需要有用于libimagequant支持编译libvips（可选，默认256）
- options.colors number options.colours替代拼写，必须设置palette为true，需要libvips编译并支持libimagequant（可选，默认256）
- options.dither number Floyd-Steinberg错误扩散的级别，必须设置palette为true，需要libvips编译并支持libimagequant（可选，默认1.0）
- options.force boolean f 强制PNG输出，否则尝试使用输入格式（可选，默认true）

例子

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

无效的选项将引发错误 Error

返回 Sharp

webp

使用WebP选项输出图像。

参数

options Object ? 输出选项
- options.quality number 质量，整数1-100（可选，默认80）
- options.alphaQuality number alpha层的质量，整数0-100（可选，默认 100)
- options.lossless boolean 使用无损压缩模式（可选，默认false)
- options.nearLossless boolean 使用near_lossless压缩模式（可选，默认 false)
- options.smartSubsample boolean 使用高质量色度子采样（可选，默认false)
- options.effort number CPU工作的水平，减少文件大小，整数0-6（可选，默认4)
- options.loop number 动画迭代次数，为无限循环动画使用0（可选，默认0)
- options.delay (number | Array <number >)? 动画帧之间的延迟列表数组（以毫秒为单位）
- options.force boolean WebP输出，否则尝试使用输入格式（可选，默认true)

例子

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

无效选项时抛出错误 Error

返回Sharp对象

gif

使用GIF选项输出图像。

面板中的第一个条目是为透明性而保留的。

注意：需要使用支持ImageMagick或GraphicsMagick编译的libvips。预编译的二进制文件不包含此文件-请参阅安装自定义libvips 。

参数

options Object ? 输出选项
- options.colours number 面板条目的最大数量(包括透明度)在2到256之间(可选的，默认的256)
- options.colors number options.colours的另一种拼法 (可选，默认256)
- options.effort number CPU 工作量，介于1(最快的)和10(最慢的)之间(可选的，默认值7)
- options.dither number 错误扩散级别，介于0(最小)和1(最大)之间(可选，默认1.0)
- options.loop number 动画迭代次数，为无限循环动画使用0（可选，默认0)
- options.delay (number | Array <number >)? 动画帧之间的延迟列表数组（以毫秒为单位）
- options.force boolean GIF输出，否则尝试使用输入格式（可选，默认true)

例子

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

无效选项时抛出错误 Error

返回 Sharp对象

Meta

since: 0.30.0

jp2

使用 jp2选项输出图像。

需要使用 OpenJPEG 支持编译的 libvips。预构建的二进制文件不包括这个-请参见自定义安装 libvips。

参数

options Object ? 输出选项
- options.quality number 质量，整数1-100(可选，默认 80)
- options.lossless boolean 使用无损数据压缩模式(可选，默认 false)
- options.tileWidth number 水平平铺大小(可选，默认 512)
- options.tileHeight number 垂直平铺大小(可选，默认512)
- options.chromaSubsampling string 设定为’4:2:0’以使用色度抽样(可选的，默认的'4:4:4')

例子

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

无效选项时抛出错误 Error

返回 Sharp对象

Meta

since: 0.29.1

tiff

对输出图像使用 TIFF 选项。

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

参数

options Object ? 输出选项
- options.quality number 质量，整数1-100(可选，默认 80)
- options.force boolean 强制 TIFF 输出，否则尝试使用输入格式(可选，默认true)
- options.compression string 压缩选项: lzw，deflate，jpeg，ccittfax4(可选，默认'jpeg')
- options.predictor string 压缩预测变量选项：none, horizontal, float（可选，默认 'horizontal')
- options.pyramid boolean 写一个图像金字塔（可选，默认 false)
- options.tile boolean 写入平铺的tiff（可选，默认值 false)
- options.tileWidth number 垂直图块大小（可选，默认256)
- options.tileHeight number 水平图块大小（可选，默认 256)
- options.xres number 水平分辨率，以pixels/ mm为单位 (可选，默认 1.0)
- options.yres number 垂直分辨率，以pixels/ mm为单位 (可选，默认 1.0)
- options.resolutionUnit string 分辨率单位，选项: inch（英寸），cm厘米） (可选，默认 'inch')
- options.bitdepth number 将位深度减小为1、2或4位 (可选，默认 8)

例子

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

无效选项时抛出错误 Error

返回 Sharp对象

avif

使用 AVIF 选项输出图像。

虽然可以创建小于16x16像素的 AVIF 图像，但大多数浏览器并不能正确显示这些图像。

不支持 AVIF 图像序列。

参数

options Object ? 输出选项
- options.quality number 质量，整数1-100(可选，默认 50)
- options.lossless boolean 使用无损数据压缩 (可选，默认 false)
- options.effort number CPU 工作量，在0(最快的)和9(最慢的)之间 (可选，默认 4)
- options.chromaSubsampling string 设定为’4:2:0’以使用色度抽样
无效选项时抛出错误 Error

返回 Sharp对象

Meta

since: 0.27.0

heif

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

对受专利限制的 HEIC 图像的支持需要使用全局安装的 libvips，该 libvips 编译后支持 libheif、 libde265和 x265。

参数

options Object ? 输出选项
- options.quality number 质量，整数1-100(可选，默认 50)
- options.compression string compression format: av1, hevc (可选，默认 'av1')
- options.lossless boolean 使用无损数据压缩 (可选，默认 false)
- options.effort number CPU 工作量，在0(最快的)和9(最慢的)之间 (可选，默认 4)
- options.chromaSubsampling string 设定为’4:2:0’以使用色度抽样
无效选项时抛出错误 Error

返回 Sharp对象

Meta

since: 0.23.0

raw

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

参数

options Object ? 输出选项
- options.depth string 位深度, 选项: char, uchar (默认), short, ushort, int, uint, float, complex, double, dpcomplex (可选，默认 'uchar')

例子

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

无效选项时抛出错误 Error

tile

使用基于平铺的深度缩放(图像金字塔)输出。通过 toFormat, jpeg, png 或 webp 函数设置平铺图像的格式和选项。使用.zip 或 .szi文件扩展名和 toFile 一起写到一个压缩的归档文件。

警告：在某些版本的libgsf中，多个同时生成图块输出的Sharp实例对象可能会暴露可能的竞争状况。

参数

options Object ?
- options.size number 以像素为单位的平铺大小，值在1到8192之间 (可选，默认 256)
- options.overlap number 以像素为单位的平铺重叠，值介于0和8192之间 (可选，默认 0)
- options.angle number tile旋转角度，必须为90的倍数。 (可选，默认 0)
- options.background (string | Object ) 背景颜色, 由 color 模块解析，默认为白色，不透明。 (可选，默认 {r:255,g:255,b:255,alpha:1})
- options.depth string ? 使金字塔有多深，可能值 onepixel, onetile 或 one, 默认基于布局。
- options.skipBlanks number 跳过图块生成的阈值，对于8位图像为0-255，对于16位图像为0-65535 (可选，默认 -1)
- options.container string 图块容器，具有值fs (文件系统) 或 zip (压缩文件). (可选，默认 'fs')
- options.layout string 文件系统布局，可能的值是 dz, iiif, iiif3, zoomify 或 google. (可选，默认 'dz')
- options.centre boolean 方块中的中心图片。 (可选，默认 false)
- options.center boolean centre的替代拼写。 (可选，默认 false)
- options.id string 当layout 是iiif/iiif3, 设定@id/id的属性info.json(可选，默认‘https://example.com/iiif’`)

例子

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

无效参数时抛出错误 Error

返回 Sharp对象

timeout

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

当 libvips 打开一个输入图像进行处理时，时钟就开始了。不包括等待 libuv 线程可用所花费的时间。

参数

options Object
- options.seconds number 停止处理的秒数

返回 Sharp对象

Meta

since: 0.29.2