Crop
返回按给定处理规格裁剪后的新图像资源。
Crop 方法依据给定的处理规格,从一张processable image(可处理的图像)返回新的资源。
这一页解决什么问题
Crop 从一张可处理的图像里按矩形区域截取一块,返回一个新的资源。它不缩放:你写 200x200,就得到 200×200 的像素块,取哪一块由锚点决定(默认取成像配置里的 anchor)。
典型场景:卡片缩略图、头像框、把画面焦点固定在主体的局部截图。
什么时候用,什么时候别用
四个变换方法最容易混,先记住这一行:
| 方法 | 缩放? | 裁剪? | 会放大吗? | 一句话 |
|---|---|---|---|---|
Crop |
否 | 是(按给定矩形取一块) | 不会 | 只裁不缩 |
Fit |
是(等比缩小) | 否 | 不会 | 缩到「装得进」为止 |
Fill |
是 | 是(裁掉溢出) | 会(为铺满而放大) | 缩放到铺满后裁掉多余 |
Resize |
是 | 否 | 会 | 直接缩到指定尺寸(可能变形) |
该用:只要局部、不想重采样(像素级还原);目标尺寸固定且知道要保留哪个角。
别用:
- 想让整张图「装进」某个框 →
Fit; - 想「填满」某个框、允许裁边 →
Fill; - 只改尺寸不裁 →
Resize; - 还要转格式、旋转、调质量 →
Process一条规格字符串全包。
用法
裁剪时必须在规格中同时给出宽度和高度(例如 200x200)。该方法不做任何缩放,只是按给出的尺寸以及锚点(如果有)截取图像的一个区域。
{{ with resources.Get "images/original.jpg" }}
{{ with .Crop "200x200 TopRight" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}上面的示例中,"200x200 TopRight" 就是处理规格。
处理规格
处理规格是一个以空格分隔、大小写不敏感的列表,包含下列选项中的一个或多个,顺序任意:
- action
- 指定
crop、fill、fit或resize之一。适用于Process方法和images.Process滤镜。若指定了 action,还必须同时提供尺寸。 - anchor
- 裁剪或填充图像时使用的焦点。可选值包括
TopLeft、Top、TopRight、Left、Center、Right、BottomLeft、Bottom、BottomRight或Smart。Smart选项借助muesli/smartcrop包找出图像中最值得保留的区域。默认取成像配置中的anchor设置。 - background color
- 把透明图像转换为不支持透明度的格式(例如 PNG 转 JPEG)时使用的背景色。当图像按非正交角度旋转、产生空白区域且处理规格中未指定背景色时,该颜色也用于填充空白。取值必须是 RGB 十六进制颜色。默认取成像配置中的
bgColor设置。 - compression
- (0.153.5 新增) 编码策略,适用于 AVIF 和 WebP 图像。可选值为
lossy或lossless。默认取成像配置中与格式对应的compression设置。 - dimensions
- 结果图像的尺寸,单位为像素。格式为
WIDTHxHEIGHT,其中WIDTH与HEIGHT都是整数。缩放图像时可以只指定宽度(如600x)或只指定高度(如x400)以等比缩放;同时指定宽度和高度可能导致非等比缩放。裁剪、适配或填充时必须同时给出宽度和高度,如600x400。 - format
- 结果图像的格式。可选值包括
avif、bmp、gif、jpeg、png、tiff或webp。默认与源图像格式相同。 - hint
- 内容提示,适用于 AVIF 和 WebP 图像。可选值包括
drawing、icon、photo、picture或text。默认取成像配置中与格式对应的hint设置。取值 示例 drawing带高对比细节的手绘或线稿 icon尺寸较小的彩色图像 photo自然光照下的户外照片 picture人像等室内照片 text以文字为主的图像 - quality
- 视觉保真度,适用于 JPEG 图像,以及使用
lossy压缩的 AVIF 和 WebP 图像。格式为qQUALITY,其中QUALITY是1到100(含两端)之间的整数。数值越小越优先考虑文件体积,数值越大越优先考虑视觉清晰度。默认取成像配置中与格式对应的quality设置。 - resampling filter
- 缩放、适配或填充图像时计算新像素所用的算法。常用选项包括
box、lanczos、catmullRom、mitchellNetravali、linear或nearestNeighbor。默认取成像配置中的resampleFilter设置。滤镜 说明 box简单快速的平均滤镜,适合缩小图像 lanczos高质量重采样滤镜,用于照片可获得锐利结果 catmullRom锐利的三次滤镜,比 Lanczos 更快而结果相近 mitchellNetravali三次滤镜,结果更平滑,振铃伪影比 CatmullRom 更少 linear双线性重采样滤镜,输出平滑,比三次滤镜更快 nearestNeighbor最快的重采样滤镜,不做抗锯齿 可用重采样滤镜的完整列表见源文档。若愿意以性能换取画质,可以试一试其他滤镜。
- rotation
- 逆时针旋转图像的整角度数。格式为
rDEGREES,其中DEGREES是整数。Hugo 会在其他任何变换之前先执行旋转,因此你的目标尺寸和锚点都应针对旋转后的图像方向。正交旋转用r90、r180或r270,任意角度如r45。要顺时针旋转,使用r-45这样的负数。要根据图像的 Exif 方向标记自动旋转,请改用images.AutoOrient滤镜,而不是手动旋转。按非正交角度旋转会扩大图像范围以容纳旋转后的四角。对 AVIF、PNG、WebP 等支持 alpha 通道的格式,这些多出来的空白区域默认透明。若目标格式不支持透明度(如 JPEG),或在处理规格中显式指定了背景色,空白区域会被填充。若需要颜色但处理字符串中没有指定,则默认取成像配置中的
bgColor设置。
示例
{{ with resources.Get "images/original.jpg" }}
{{ with .Crop "200x200 TopRight" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}英文原文此处用示例照片演示 crop 200x200 TopRight 的前后对比效果;本站未收录该示例图。
完整示例(实测)
测量条件:Hugo 0.167.0 extended,Windows;assets/images/original.jpg 是一张 600×400 的 JPEG。把下面这段放进 layouts/_default/single.html:
{{ with resources.Get "images/original.jpg" }}
{{ with .Crop "200x200 TopRight" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}Hugo 渲染为:
<img src="/images/original_hu_c40a25d8b29cdb3e.jpg" width="200" height="200" alt="">你应当看到什么:宽高正是 200×200;URL 里的 _hu_ 段是 Hugo 的缓存键(由源文件与处理规格算出),同一张图同一规格每次构建都一样,换图或换规格就会变。裁剪出来的文件同时被发布到 public/images/。
再试一个越界请求:源图只有 600×400,却要求 1000x1000:
{{ with resources.Get "images/original.jpg" }}
{{ with .Crop "1000x1000" }}宽 {{ .Width }},高 {{ .Height }}{{ end }}
{{ end }}实测输出:
宽 400,高 400这里有个容易踩的坑:越界不会报错,你拿到的是一个比请求尺寸小的图。Crop 不会放大图像,超出源图的部分自然取不到。要「放大到指定尺寸」,得用 Resize 或 Fill。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
规格正常(200x200 TopRight) |
images.ImageResource,尺寸即所写 |
否 |
只写一个维度(200x、x200) |
—— | 是:error calling Crop: failed to crop image "…": must provide Width and Height |
请求尺寸大于源图(1000x1000) |
返回源图范围内可取的尺寸(实测 400×400),不放大 | 否 |
锚点拼错(NoSuchAnchor) |
实测仍返回 200×200,不报错;本页无法从输出判断它最终用了哪个锚点 | 否 |
| 对非图像资源调用 | —— | 是:does not support this method: use reflect.IsImageResource… |
resources.Get 找不到文件(nil) |
—— | 是:nil pointer evaluating resource.Resource.Crop |
写模板时可以先用 reflect.IsImageResourceProcessable 判断,再用 with 接住结果:
{{ with resources.Get "images/original.jpg" }}
{{ if reflect.IsImageResourceProcessable . }}
{{ with .Crop "200x200 TopRight" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ else }}
{{ errorf "无法处理这张图:%s" .RelPermalink }}
{{ end }}
{{ end }}常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 输出比预期小 | 请求尺寸超过源图,Crop 不放大 |
换 Resize/Fill,或把目标尺寸调小 |
| 没报错但结果不对 | 裁出来的位置不是想要的 | 锚点写错或没写(默认取成像配置的 anchor) |
显式写 TopRight、Center、Smart 等 |
| 报错看不懂 | must provide Width and Height |
裁剪必须同时给出宽和高 | 补成 200x200(不能只写 200x) |
| 构建失败 | does not support this method |
对文本等非图像资源用了 Crop |
先用 reflect.IsImageResourceProcessable 判断 |
更多排查入口见故障排查。