输出选项
toFile
Section titled “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> - 当没有提供回调时
抛出:
错误参数无效
| 参数 | 类型 | 描述 |
|---|---|---|
| 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) => { ... });Example
sharp(input) .toFile('output.png') .then(info => { ... }) .catch(err => { ... });toBuffer
Section titled “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),其中:
err是一个错误,如果有的话。data是输出的图片数据。info包含输出图片format、size(字节)、width、height、channels和premultiplied(表示是否使用了预乘)。使用裁剪策略时,还会包含cropOffsetLeft和cropOffsetTop。动画输出还会包含pageHeight和pages。如果图片是由文本创建的,还可能包含textAutofitDpi(字体渲染的 dpi)。
某些 JavaScript 运行时可能将底层 ArrayBuffer 标记为不可转移。使用 toUint8Array 可以确保 ArrayBuffer 可转移。
🌐 The underlying ArrayBuffer may be marked as non-transferable by some JavaScript runtimes.
Use toUint8Array for a guaranteed transferable ArrayBuffer.
当没有提供 callback 时,会返回 Promise。
🌐 A Promise is returned when callback is not provided.
返回: Promise.<Buffer> - 当未提供回调时
| 参数 | 类型 | 描述 |
|---|---|---|
| [options] | 对象 |
|
| [options.resolveWithObject] | 布尔值 |
用一个包含 data 和 info 属性的对象来解析 Promise,而不仅仅是用 data 来解析。 |
| [callback] | 函数 |
示例
const data = await sharp(input) .png() .toBuffer();Example
const { data, info } = await sharp(input) .png() .toBuffer({ resolveWithObject: true });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 locationconst pixelArray = new Uint8ClampedArray(data.buffer);
// When you are done changing the pixelArray, sharp takes the `pixelArray` as an inputconst { width, height, channels } = info;await sharp(pixelArray, { raw: { width, height, channels } }) .toFile('my-changed-image.jpg');toUint8Array
Section titled “toUint8Array”toUint8Array() ⇒
Promise.<{data: Uint8Array, info: Object}>
将输出写入由可转移的 ArrayBuffer 支持的 Uint8Array。
支持 JPEG、PNG、WebP、AVIF、TIFF、GIF 和原始像素数据输出。
🌐 Write output to a Uint8Array backed by a transferable ArrayBuffer.
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 的方向信息。可以参考 keepExif 和类似方法来进行控制。
🌐 By default all metadata will be removed, which includes EXIF-based orientation. See keepExif and similar methods for control over this.
以包含以下内容的 Object 解决:
🌐 Resolves with an Object containing:
data是作为可转移的ArrayBuffer支持的Uint8Array输出图片。info包含与输出图片相关的属性,例如width和height。
自:v0.35.0
示例
const { data, info } = await sharp(input).toUint8Array();Example
const { data } = await sharp(input) .avif() .toUint8Array();const base64String = data.toBase64();withDensity
Section titled “withDensity”withDensity(density) ⇒
Sharp
在 EXIF 元数据中设置输出密度(DPI)。
🌐 Set output density (DPI) in EXIF metadata.
投掷:
错误参数无效
自:0.35.0
| 参数 | 类型 | 描述 |
|---|---|---|
| density | 数字 |
每英寸像素数(DPI),介于 1 到 100000 之间。 |
示例
const data = await sharp(input) .withDensity(96) .toBuffer();keepExif
Section titled “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
示例
const outputWithExif = await sharp(inputWithExif) .keepExif() .toBuffer();withExif
Section titled “withExif”withExif(exif) ⇒
Sharp
在输出图片中设置 EXIF 元数据,忽略输入图片中的任何 EXIF。
🌐 Set EXIF metadata in the output image, ignoring any EXIF in the input image.
投掷:
错误参数无效
自:0.33.0
| 参数 | 类型 | 描述 |
|---|---|---|
| exif | Object.<string, Object.<string, string>> |
按 IFD0、IFD1 等键索引的对象,包含要写入的 EXIF 数据的键/值字符串对。 |
示例
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
Section titled “withExifMerge”withExifMerge(exif) ⇒
Sharp
在输出图片中更新输入图片的 EXIF 元数据。
🌐 Update EXIF metadata from the input image in the output image.
投掷:
错误参数无效
自:0.33.0
| 参数 | 类型 | 描述 |
|---|---|---|
| exif | Object.<string, Object.<string, string>> |
按 IFD0、IFD1 等键索引的对象,包含要写入的 EXIF 数据的键/值字符串对。 |
示例
const dataWithMergedExif = await sharp(inputWithExif) .withExifMerge({ IFD0: { Copyright: 'The National Gallery' } }) .toBuffer();keepIccProfile
Section titled “keepIccProfile”keepIccProfile() ⇒
Sharp
将输入图片中的 ICC 配置文件保留在输出图片中。
🌐 Keep ICC profile from the input image in the output image.
当输入和输出的色彩空间不同时,配合 toColourspace 使用,必要时也可以用 pipelineColourspace。
🌐 When input and output colour spaces differ, use with toColourspace and optionally pipelineColourspace.
自: 0.33.0
示例
const outputWithIccProfile = await sharp(inputWithIccProfile) .keepIccProfile() .toBuffer();Example
const cmykOutputWithIccProfile = await sharp(cmykInputWithIccProfile) .pipelineColourspace('cmyk') .toColourspace('cmyk') .keepIccProfile() .toBuffer();withIccProfile
Section titled “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).
投掷:
错误参数无效
自: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
Section titled “keepGainMap”keepGainMap() ⇒
Sharp
如果输入包含增益图元数据,尝试分别处理图片和增益图,然后将它们重新合成为一个输出图片。
🌐 If the input contains gain map metadata, attempt to process the image and gain map separately, recombining them into a single output image.
这种方法更快,并且应该比 withGainMap 产生更好的结果,不过并不是所有操作都支持。
🌐 This approach is faster and should produce better results than withGainMap, however not all operations are supported.
只支持 JPEG 输入和输出。除 quality 外的 JPEG 输出选项会被忽略。
🌐 Only JPEG input and output are supported.
JPEG output options other than quality are ignored.
此功能是实验性的,API 可能会更改。
🌐 This feature is experimental and the API may change.
自:0.35.0
示例
const outputWithResizedGainMap = await sharp(inputWithGainMap) .keepGainMap() .resize({ width: 64 }) .toBuffer();withGainMap
Section titled “withGainMap”withGainMap() ⇒
Sharp
如果输入包含增益图元数据,请先使用它将主图片转换为 HDR(高动态范围)再进行后续处理。输入的增益图会被丢弃。
🌐 If the input contains gain map metadata, use it to convert the main image to HDR (High Dynamic Range) before further processing. The input gain map is discarded.
如果输出是 JPEG,请生成并附加一个新的 ISO 21496-1 增益图。除 quality 外,其他 JPEG 输出选项会被忽略。
🌐 If the output is JPEG, generate and attach a new ISO 21496-1 gain map.
JPEG output options other than quality are ignored.
此功能是实验性的,API 可能会更改。
🌐 This feature is experimental and the API may change.
自:0.35.0
示例
const outputWithRegeneratedGainMap = await sharp(inputWithGainMap) .withGainMap() .toBuffer();keepXmp
Section titled “keepXmp”keepXmp() ⇒
Sharp
在输出图片中保留输入图片的 XMP 元数据。
🌐 Keep XMP metadata from the input image in the output image.
自:0.34.3
示例
const outputWithXmp = await sharp(inputWithXmp) .keepXmp() .toBuffer();withXmp
Section titled “withXmp”withXmp(xmp) ⇒
Sharp
在输出图片中设置 XMP 元数据。
🌐 Set XMP metadata in the output image.
PNG、JPEG、WebP 和 TIFF 输出均支持。
🌐 Supported by PNG, JPEG, WebP, and TIFF output.
投掷:
错误参数无效
自: 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
Section titled “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
示例
const outputWithMetadata = await sharp(inputWithMetadata) .keepMetadata() .toBuffer();withMetadata
Section titled “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.
投掷:
错误参数无效
| 参数 | 类型 | 描述 |
|---|---|---|
| [options] | 对象 |
|
| [options.orientation] | 数字 |
用于更新 EXIF Orientation 标签,整数范围在 1 到 8 之间。 |
| [options.density] | 数字 |
每英寸像素数(DPI),范围在 1 到 100000 之间。 |
示例
const outputSrgbWithMetadata = await sharp(inputRgbWithMetadata) .withMetadata() .toBuffer();Example
// Set output metadata to 96 DPIconst data = await sharp(input) .withMetadata({ density: 96 }) .toBuffer();toFormat
Section titled “toFormat”toFormat(format, options) ⇒
Sharp
强制输出为给定格式。
🌐 Force output to a given format.
投掷:
错误不支持的格式或选项
| 参数 | 类型 | 描述 |
|---|---|---|
| 格式 | 字符串 |对象 |
作为带有“id”属性的字符串或对象 |
| options | 对象 |
输出选项 |
示例
// Convert any input to PNG outputconst data = await sharp(input) .toFormat('png') .toBuffer();jpeg([options]) ⇒
Sharp
使用这些 JPEG 选项来输出图片。
🌐 Use these JPEG options for output image.
投掷:
错误无效的选项
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| [options] | 对象 |
输出选项 | |
| [options.quality] | 数字 |
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] | 布尔值 |
false |
使用 mozjpeg 默认设置,相当于 { trellisQuantisation: true, overshootDeringing: true, optimiseScans: true, quantisationTable: 3 } |
| [options.trellisQuantisation] | 布尔型 |
false |
应用网格量化 |
| [options.overshootDeringing] | 布尔值 |
false |
应用过冲去振铃 |
| [options.optimiseScans] | boolean |
false |
优化渐进式扫描,强制渐进式 |
| [options.optimizeScans] | 布尔值 |
false |
optimiseScans 的另一种拼写 |
| [options.quantisationTable] | 数字 |
0 |
使用的量化表,整数 0-8 |
| [options.quantizationTable] | 数字 |
0 |
quantisationTable 的另一种拼写 |
| [options.force] | boolean |
true |
强制输出 JPEG,否则尝试使用输入格式 |
示例
// Convert any input to very high quality JPEG outputconst 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([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.
投掷:
错误无效的选项
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| [options] | 对象 |
||
| [options.progressive] | boolean |
false |
使用渐进(交错)扫描 |
| [options.compressionLevel] | number |
6 |
zlib 压缩级别,0(最快,最大)到 9(最慢,最小) |
| [options.adaptiveFiltering] | 布尔值 |
false |
使用自适应行过滤 |
| [options.palette] | boolean |
false |
量化为支持 alpha 透明的调色板图片 |
| [options.quality] | 数字 |
100 |
使用实现给定质量所需的最少颜色数量,将 palette 设置为 true |
| [options.effort] | 数字 |
7 |
CPU 努力程度,介于 1(最快)和 10(最慢)之间,将 palette 设置为 true |
| [options.colours] | number |
256 |
调色板最大条目数,设置 palette 到 true |
| [options.colors] | 数字 |
256 |
options.colours 的另一种拼写方式,将 palette 设置为 true |
| [options.dither] | 数字 |
1.0 |
Floyd-Steinberg误差扩散的水平,将 palette 设置为 true |
| [options.force] | boolean |
true |
强制输出 PNG,否则尝试使用输入格式 |
示例
// Convert any input to full colour PNG outputconst 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([options]) ⇒
Sharp
使用这些 WebP 选项输出图片。
🌐 Use these WebP options for output image.
投掷:
错误无效的选项
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| [options] | 对象 |
输出选项 | |
| [options.quality] | 数字 |
80 |
质量,整数 1-100 |
| [options.alphaQuality] | 数字 |
100 |
alpha 图层的质量,整数 0-100 |
| [options.lossless] | boolean |
false |
使用无损压缩模式 |
| [options.nearLossless] | boolean |
false |
使用接近无损的压缩模式 |
| [options.smartSubsample] | 布尔值 |
false |
使用高质量色度子采样 |
| [options.smartDeblock] | boolean |
false |
自动调整去块滤镜,可改善低对比度边缘(慢) |
| [options.preset] | 字符串 |
"'default'" |
用于预处理/过滤的命名预设,可选值:default, photo, picture, drawing, icon, text |
| [options.effort] | 数字 |
4 |
CPU 负载,范围从 0(最快)到 6(最慢) |
| [options.loop] | number |
0 |
动画循环次数,使用 0 表示无限循环 |
| [options.delay] | 数字 |数组。<数> |
动画帧之间的延迟(以毫秒计) | |
| [options.minSize] | boolean |
false |
防止使用动画关键帧以减小文件大小(慢) |
| [options.mixed] | 布尔值 |
false |
允许有损和无损动画帧混合(慢) |
| [options.exact] | boolean |
false |
保留透明像素中的颜色数据 |
| [options.force] | boolean |
true |
强制输出 WebP,否则尝试使用输入格式 |
示例
// Convert any input to lossless WebP outputconst data = await sharp(input) .webp({ lossless: true }) .toBuffer();Example
// Optimise the file size of an animated WebPconst outputWebp = await sharp(inputWebp, { animated: true }) .webp({ effort: 6 }) .toBuffer();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.
投掷:
错误无效的选项
自:0.30.0
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| [options] | 对象 |
输出选项 | |
| [options.reuse] | boolean |
true |
重用已有调色板,否则生成新的(慢) |
| [options.progressive] | boolean |
false |
使用渐进(交错)扫描 |
| [options.colours] | 数字 |
256 |
调色板条目的最大数量,包括透明度,范围在2到256之间 |
| [options.colors] | 数字 |
256 |
options.colours 的另一种拼写 |
| [options.effort] | 数字 |
7 |
CPU 使用强度,范围从 1(最快)到 10(最慢) |
| [options.dither] | 数字 |
1.0 |
Floyd-Steinberg 误差扩散的等级,范围从 0(最少)到 1(最多) |
| [options.interFrameMaxError] | 数字 |
0 |
最大帧间透明度误差,范围从 0(无损)到 32 |
| [options.interPaletteMaxError] | 数字 |
3 |
调色板重用的最大调色板间错误,范围是 0 到 256 |
| [options.keepDuplicateFrames] | 布尔值 |
false |
在输出中保留重复帧而不是合并它们 |
| [options.loop] | number |
0 |
动画循环次数,使用 0 表示无限循环 |
| [options.delay] | 数字 |数组。<数> |
动画帧之间的延迟(以毫秒计) | |
| [options.force] | boolean |
true |
强制输出 GIF,否则尝试使用输入格式 |
示例
// Convert PNG to GIFawait sharp(pngBuffer) .gif() .toBuffer();Example
// Convert animated WebP to animated GIFawait sharp('animated.webp', { animated: true }) .toFile('animated.gif');Example
// Create a 128x128, cropped, non-dithered, animated thumbnail of an animated GIFconst out = await sharp('in.gif', { animated: true }) .resize({ width: 128, height: 128 }) .gif({ dither: 0 }) .toBuffer();Example
// Lossy file size reduction of animated GIFawait sharp('in.gif', { animated: true }) .gif({ interFrameMaxError: 8 }) .toFile('optim.gif');jp2([options]) ⇒
Sharp
使用这些 JP2 选项输出图片。
🌐 Use these JP2 options for output image.
需要用 OpenJPEG 支持编译的 libvips。预编译的二进制文件不包括这个 - 详见 安装自定义 libvips。
🌐 Requires libvips compiled with support for OpenJPEG. The prebuilt binaries do not include this - see installing a custom libvips.
投掷:
错误无效的选项
自:0.29.1
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| [options] | 对象 |
输出选项 | |
| [options.quality] | 数字 |
80 |
质量,整数 1-100 |
| [options.lossless] | 布尔值 |
false |
使用无损压缩模式 |
| [options.tileWidth] | 数字 |
512 |
水平瓦片大小 |
| [options.tileHeight] | 数字 |
512 |
垂直瓦片大小 |
| [options.chromaSubsampling] | 字符串 |
"‘4:4:4’" |
设置为 ‘4:2:0’ 以使用色度子采样 |
示例
// Convert any input to lossless JP2 outputconst data = await sharp(input) .jp2({ lossless: true }) .toBuffer();Example
// Convert any input to very high quality JP2 outputconst data = await sharp(input) .jp2({ quality: 100, chromaSubsampling: '4:4:4' }) .toBuffer();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.
投掷:
错误无效的选项
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| [options] | 对象 |
输出选项 | |
| [options.quality] | 数字 |
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 变体(当压缩为 none 时无效) |
| [options.predictor] | 字符串 |
"‘horizontal’" |
压缩预测器选项:无、水平、浮点 |
| [options.pyramid] | 布尔值 |
false |
写入图片金字塔 |
| [options.tile] | boolean |
false |
写入平铺 tiff |
| [options.tileWidth] | 数字 |
256 |
横向瓦片大小,有效值是 1-32768 范围内的整数 |
| [options.tileHeight] | number |
256 |
垂直瓦片大小,有效值为 1-32768 之间的整数 |
| [options.xres] | 数字 |
1.0 |
水平分辨率(像素/毫米),有效值为 0.001-1000000 范围内的数字 |
| [options.yres] | 数字 |
1.0 |
垂直分辨率,单位为像素/毫米,有效值范围是 0.001-1000000 |
| [options.resolutionUnit] | string |
"‘inch’" |
分辨率单位选项:英寸, 厘米 |
| [options.bitdepth] | 数字 |
0 |
将位深度降低到 1、2 或 4 位 |
| [options.miniswhite] | 布尔值 |
false |
将1位图片写为miniswhite |
示例
// Convert SVG input to LZW-compressed, 1 bit per pixel TIFF outputsharp('input.svg') .tiff({ compression: 'lzw', bitdepth: 1 }) .toFile('1-bpp-output.tiff') .then(info => { ... });avif([options]) ⇒
Sharp
使用这些 AVIF 选项来输出图片。
🌐 Use these AVIF options for output image.
不支持 AVIF 图片序列。
🌐 AVIF image sequences are not supported.
投掷:
错误无效的选项
自: 0.27.0
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| [options] | 对象 |
输出选项 | |
| [options.quality] | 数字 |
50 |
质量,整数 1-100 |
| [options.lossless] | 布尔值 |
false |
使用无损压缩 |
| [options.effort] | 数字 |
4 |
CPU 计算强度,范围 0(最快)到 9(最慢) |
| [options.chromaSubsampling] | 字符串 |
"'4:4:4'" |
设置为 ‘4:2:0’ 来使用色度子采样 |
| [options.bitdepth] | 数字 |
8 |
设置比特深度为 8、10 或 12 位 |
| [options.tune] | 字符串 |
"'auto'" |
根据质量指标调节输出选项,可选 ‘auto’(默认)、‘iq’、‘psnr’ 或 ‘ssim’ |
示例
const data = await sharp(input) .avif({ effort: 2 }) .toBuffer();Example
const data = await sharp(input) .avif({ lossless: true }) .toBuffer();heif(options) ⇒
Sharp
使用这些 HEIF 选项输出图片。
🌐 Use these HEIF options for output image.
要支持使用 hevc 压缩的受专利限制的 HEIC 图片,需要使用全局安装、并且编译时支持 libheif、libde265 和 x265 的 libvips。
🌐 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.
投掷:
错误无效的选项
自:0.23.0
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| options | 对象 |
输出选项 | |
| options.compression | 字符串 |
压缩格式:av1, hevc | |
| [options.quality] | 数字 |
50 |
质量,整数 1-100 |
| [options.lossless] | 布尔值 |
false |
使用无损压缩 |
| [options.effort] | 数字 |
4 |
CPU 努力程度,0 表示最快,9 表示最慢 |
| [options.chromaSubsampling] | 字符串 |
"‘4:4:4’" |
设置为 ‘4:2:0’ 以使用色度子采样 |
| [options.bitdepth] | 数字 |
8 |
设置位深为 8、10 或 12 位 |
| [options.tune] | 字符串 |
"‘auto’" |
根据质量指标调整输出,可选 ‘auto’(av1 默认)、‘iq’(仅 av1)、‘psnr’ 或 ‘ssim’(hevc 默认) |
示例
const data = await sharp(input) .heif({ compression: 'hevc' }) .toBuffer();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.
需要使用支持 libjxl 的 libvips 编译。预编译的二进制文件不包括这个功能——请参阅 安装自定义 libvips。
🌐 Requires libvips compiled with support for libjxl. The prebuilt binaries do not include this - see installing a custom libvips.
投掷:
错误无效的选项
自:0.31.3
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| [options] | 对象 |
输出选项 | |
| [options.distance] | 数字 |
1.0 |
最大编码误差,范围从 0(最高质量)到 15(最低质量) |
| [options.quality] | 数字 |
根据类似 JPEG 的质量计算 distance,值在 1 到 100 之间,如果指定则覆盖 distance |
|
| [options.decodingTier] | 数字 |
0 |
目标解码速度等级,范围从 0(最高质量)到 4(最低质量) |
| [options.lossless] | 布尔值 |
false |
使用无损压缩 |
| [options.effort] | 数字 |
7 |
CPU 使用强度,范围从 1(最快)到 9(最慢) |
| [options.loop] | number |
0 |
动画循环次数,使用 0 表示无限循环 |
| [options.delay] | 数字 |数组。<数> |
动画帧之间的延迟(以毫秒计) |
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.
投掷:
错误无效的选项
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| [options] | 对象 |
输出选项 | |
| [options.depth] | 字符串 |
"‘uchar’" |
位深度,可选:char, uchar(默认), short, ushort, int, uint, float, complex, double, dpcomplex |
示例
// Extract raw, unsigned 8-bit RGB pixel data from JPEG inputconst { data, info } = await sharp('input.jpg') .raw() .toBuffer({ resolveWithObject: true });Example
// Extract alpha channel as raw, unsigned 16-bit pixel data from PNG inputconst data = await sharp('input.png') .ensureAlpha() .extractChannel(3) .toColourspace('b-w') .raw({ depth: 'ushort' }) .toBuffer();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.
投掷:
错误参数无效
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| [options] | 对象 |
||
| [options.size] | 数字 |
256 |
瓷砖大小(像素),取值范围为1到8192。 |
| [options.overlap] | 数字 |
0 |
瓷砖重叠的像素值,取值范围在 0 到 8192 之间。 |
| [options.angle] | 数字 |
0 |
瓷砖的旋转角度,必须是90的倍数。 |
| [options.background] | 字符串 |对象 |
“{r: 255, g: 255, b: 255, alpha: 1}” |
背景颜色,由[color](https://www.npmjs.org/package/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] | 字符串 |
"‘dz’" |
文件系统布局,可选值为 dz、iiif、iiif3、zoomify 或 google。 |
| [options.centre] | boolean |
false |
在图块中居中图片。 |
| [options.center] | boolean |
false |
centre 的另一种拼写方式。 |
| [options.id] | 字符串 |
"'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 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
Section titled “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
| 参数 | 类型 | 描述 |
|---|---|---|
| options | Object |
|
| options.seconds | number |
处理将在多少秒后停止 |
示例
// Ensure processing takes no longer than 3 secondstry { const data = await sharp(input) .blur(1000) .timeout({ seconds: 3 }) .toBuffer();} catch (err) { if (err.message.includes('timeout')) { ... }}