跳转到内容
# Sharp 中文文档

调整图像大小

resize

Section titled “resize”

resize([width], [height], [options]) ⇒ Sharp

将图像调整为 width、height 或 width x height。

当同时提供 width 和 height 时，符合这些尺寸的图像应当适配的可能方法有：

  • cover：（默认）保持宽高比，尽量确保图像覆盖提供的两个尺寸，通过裁剪/剪切以适应。
  • contain：保持宽高比，在必要时使用“宽屏效果”使图像包含在提供的两个尺寸内。
  • fill：忽略输入的宽高比，拉伸到提供的两个尺寸。
  • inside：保持宽高比，调整图像，使其尽可能大，同时确保其尺寸不大于指定的尺寸。
  • outside：保持宽高比，调整图像，使其尽可能小，同时确保其尺寸不小于指定的尺寸。

这些值中的一些基于 object-fit CSS 属性。

调整大小时适配属性的各种值示例

使用 fit 为 cover 或 contain 时，默认 position 为 centre。其他选项有：

  • sharp.position：top、right top、right、right bottom、bottom、left bottom、left、left top。
  • sharp.gravity：north、northeast、east、southeast、south、southwest、west、northwest、center 或 centre。
  • sharp.strategy：仅限 cover，使用 entropy 或 attention 策略动态裁剪。

这些值中的一些基于 object-position CSS 属性。

基于策略的方法最初将图像调整为一维达到目标长度，然后重复排名边缘区域，丢弃得分最低的边缘，基于所选策略。

  • entropy：关注具有最高 香农熵 的区域。
  • attention：关注具有最高亮度频率、颜色饱和度和肤色存在的区域。

可能的下采样内核有：

上采样时，这些内核映射到 nearest、linear 和 cubic 插值器。 没有匹配的上采样插值器的下采样内核映射为 cubic。

每个管道只能进行一次调整大小。 在同一管道中之前对 resize 的调用将被忽略。

抛出：

  • Error 无效的参数
参数类型默认描述
[width]number生成图像的宽度（像素数）。使用 null 或 undefined 自动缩放宽度以匹配高度。
[height]number生成图像的高度（像素数）。使用 null 或 undefined 自动缩放高度以匹配宽度。
[options]Object
[options.width]number指定 width 的另一种方式。如果两者都存在，这个优先。
[options.height]number指定 height 的另一种方式。如果两者都存在，这个优先。
[options.fit]String’cover’图像应如何调整大小/裁剪以适应目标尺寸，可以是 cover、contain、fill、inside 或 outside。
[options.position]String’centre’当 fit 为 cover 或 contain 时使用的位置、重力或策略。
[options.background]String | Object{r: 0, g: 0, b: 0, alpha: 1}当 fit 为 contain 时的背景颜色，由 color 模块解析，默认为不透明的黑色。
[options.kernel]String’lanczos3’用于图像缩减的内核和用于上采样的推断插值器。使用 fastShrinkOnLoad 选项控制内核和加载时缩小的关系。
[options.withoutEnlargement]Booleanfalse如果宽度 或 高度已经小于目标尺寸，则不进行放大，相当于 GraphicsMagick 的 > 几何选项。这可能导致输出尺寸小于目标尺寸。
[options.withoutReduction]Booleanfalse如果宽度 或 高度已经大于目标尺寸，则不进行缩小，相当于 GraphicsMagick 的 < 几何选项。这仍可能导致裁剪以达到目标尺寸。
[options.fastShrinkOnLoad]Booleantrue更充分利用 JPEG 和 WebP 的加载时缩小特性，这可能导致轻微的摩尔图案或自动缩放尺寸的四舍五入。

示例

sharp(input)
  .resize({ width: 100 })
  .toBuffer()
  .then(data => {
    // 100 像素宽，自动缩放高度
  });

示例

sharp(input)
  .resize({ height: 100 })
  .toBuffer()
  .then(data => {
    // 100 像素高，自动缩放宽度
  });

示例

sharp(input)
  .resize(200, 300, {
    kernel: sharp.kernel.nearest,
    fit: 'contain',
    position: 'right top',
    background: { r: 255, g: 255, b: 255, alpha: 0.5 }
  })
  .toFile('output.png')
  .then(() => {
    // output.png 是一幅宽 200 像素、高 300 像素的图像
    // 包含了最近邻缩放的版本
    // 被包裹在半透明白色画布的东北角
  });

示例

const transformer = sharp()
  .resize({
    width: 200,
    height: 200,
    fit: sharp.fit.cover,
    position: sharp.strategy.entropy
  });
// 从 readableStream 读取图像数据
// 将 200px 正方形的自动裁剪图像数据写入 writableStream
readableStream
  .pipe(transformer)
  .pipe(writableStream);

示例

sharp(input)
  .resize(200, 200, {
    fit: sharp.fit.inside,
    withoutEnlargement: true
  })
  .toFormat('jpeg')
  .toBuffer()
  .then(function(outputBuffer) {
    // outputBuffer 包含 JPEG 图像数据
    // 宽度和高度均不超过 200 像素
    // 不大于输入图像
  });

示例

sharp(input)
  .resize(200, 200, {
    fit: sharp.fit.outside,
    withoutReduction: true
  })
  .toFormat('jpeg')
  .toBuffer()
  .then(function(outputBuffer) {
    // outputBuffer 包含 JPEG 图像数据
    // 至少 200 像素宽和 200 像素高，同时保持宽高比
    // 不小于输入图像
  });

示例

const scaleByHalf = await sharp(input)
  .metadata()
  .then(({ width }) => sharp(input)
    .resize(Math.round(width * 0.5))
    .toBuffer()
  );

extend

Section titled “extend”

extend(extend) ⇒ Sharp

通过提供的背景颜色或从图像衍生的像素扩展/填充/突出图像的一个或多个边缘。 此操作总是在调整大小和提取后发生（如果有）。

抛出：

  • Error 无效的参数
参数类型默认描述
extendnumber | Object要添加到所有边缘的单个像素数，或包含每个边缘计数的对象
[extend.top]number0
[extend.left]number0
[extend.bottom]number0
[extend.right]number0
[extend.extendWith]String’background’使用此方法填充新像素，可以是：background、copy、repeat、mirror。
[extend.background]String | Object{r: 0, g: 0, b: 0, alpha: 1}背景颜色，由 color 模块解析，默认为不透明的黑色。

示例

// 调整为 140 像素宽，然后在顶部、左侧和右边添加 10 个透明像素，在底部边缘添加 20 个
sharp(input)
  .resize(140)
  .extend({
    top: 10,
    bottom: 20,
    left: 10,
    right: 10,
    background: { r: 0, g: 0, b: 0, alpha: 0 }
  })
  ...

示例

// 在底部添加一排 10 个红色像素
sharp(input)
  .extend({
    bottom: 10,
    background: 'red'
  })
  ...

示例

// 向右突出 8 像素，镜像现有的右边缘
sharp(input)
  .extend({
    right: 8,
    background: 'mirror'
  })
  ...

extract

Section titled “extract”

extract(options) ⇒ Sharp

提取/裁剪图像的区域。

  • 在调整大小之前使用 extract 进行预裁剪。
  • 在调整大小之后使用 extract 进行后裁剪。
  • 使用 extract 两次并使用 resize 一次来实现提取-然后调整大小-再提取的固定操作顺序。

抛出：

  • Error 无效的参数
参数类型描述
optionsObject描述使用整数像素值提取的区域
options.leftnumber从左边缘的零索引偏移
options.topnumber从顶部边缘的零索引偏移
options.widthnumber要提取的区域宽度
options.heightnumber要提取的区域高度

示例

sharp(input)
  .extract({ left: left, top: top, width: width, height: height })
  .toFile(output, function(err) {
    // 从输入图像中提取区域，保存为相同格式。
  });

示例

sharp(input)
  .extract({ left: leftOffsetPre, top: topOffsetPre, width: widthPre, height: heightPre })
  .resize(width, height)
  .extract({ left: leftOffsetPost, top: topOffsetPost, width: widthPost, height: heightPost })
  .toFile(output, function(err) {
    // 提取区域、调整大小，然后从调整后的图像中提取
  });

trim

Section titled “trim”

trim([options]) ⇒ Sharp

修剪所有边缘上与给定背景颜色相似的像素，默认背景颜色为左上角像素的颜色。

具有 alpha 通道的图像将使用 alpha 和非 alpha 通道的组合边界框。

如果该操作的结果会将图像修剪为无内容，则不进行更改。

info 响应对象将包含 trimOffsetLeft 和 trimOffsetTop 属性。

抛出：

  • Error 无效的参数
参数类型默认描述
[options]Object
[options.background]string | Object“‘左上角像素‘“背景颜色，由 color 模块解析，默认为左上角像素的颜色。
[options.threshold]number10允许的颜色差异，正数。
[options.lineArt]booleanfalse输入更像线条艺术（例如矢量）而不是摄影吗？

示例

// 修剪与左上角像素颜色相似的像素。
await sharp(input)
  .trim()
  .toFile(output);

示例

// 仅修剪与左上角像素颜色完全相同的像素。
await sharp(input)
  .trim({
    threshold: 0
  })
  .toFile(output);

示例

// 假设输入是线条艺术，仅修剪与红色相似的像素。
const output = await sharp(input)
  .trim({
    background: "#FF0000",
    lineArt: true
  })
  .toBuffer();

示例

// 修剪所有“黄色的”像素，在更高的阈值下更宽容。
const output = await sharp(input)
  .trim({
    background: "yellow",
    threshold: 42,
  })
  .toBuffer();