Fill
返回按给定处理规格裁剪并缩放后的新图像资源。
Fill 方法依据给定的处理规格,从一张processable image(可处理的图像)返回新的资源。
这一页解决什么问题
Fill 解决的是「给我一个正好这么大的框,把图铺满,别留白、别变形」:它先等比缩放图像直到能盖住目标尺寸,再把多出来的部分按锚点裁掉,所以结果一定是你写的尺寸,而且宽高比没有被拉伸。
典型场景:封面图、卡片图、og:image 缩略图——这些位置的容器尺寸固定,宁可裁掉边缘也不能留白或压扁。
什么时候用,什么时候别用
四个变换方法的分工:
| 方法 | 缩放? | 裁剪? | 会放大吗? | 一句话 |
|---|---|---|---|---|
Fill |
是 | 是(裁掉溢出) | 会 | 铺满目标框后裁边 |
Fit |
是(等比缩小) | 否 | 不会 | 缩到装得进为止 |
Crop |
否 | 是(按矩形取一块) | 不会 | 只裁不缩 |
Resize |
是 | 否 | 会 | 直接缩到指定尺寸(可能变形) |
该用:容器尺寸固定、图片内容允许裁边(人像/风景的边缘裁掉不影响表达);需要「缩略图墙」那样整齐的网格。
别用:
- 图上有不能裁的内容(图表、含文字的海报)→ 用
Resize等比缩或Fit(不改内容,最多留白); - 要保留整张图又要固定尺寸 →
Fit; - 只要局部、不要重采样 →
Crop; - 还要顺带转 WebP、调质量 →
Process。
用法
填充时必须在规格中同时给出宽度和高度(例如 500x200)。Fill 会缩放图像以覆盖目标区域,再按给出的锚点裁掉溢出的像素,从而保持原始宽高比。
{{ with resources.Get "images/original.jpg" }}
{{ with .Fill "500x200 TopRight" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}上面的示例中,"500x200 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 .Fill "500x200 TopRight" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}英文原文此处用示例照片演示 fill 500x200 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 .Fill "500x200 TopRight" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}Hugo 渲染为:
<img src="/images/original_hu_8c177808e0a3bfcc.jpg" width="500" height="200" alt="">你应当看到什么:输出一定是 500×200——源图是 600×400(3:2),目标 500×200(5:2)更扁,Fill 先把图放大到「高度铺满 200」所需的宽度(600×400 → 约 750×200),再按 TopRight 裁掉左边多出来的部分。所以边缘会被裁掉,这正是 Fill 与你写 Resize "500x200" 的区别:后者会横向压扁,不会裁。
越界与放大的边界实测(同一张 600×400 源图):
.Fill "500x200 TopRight" → 500x200(放大到铺满后裁边)
.Fill "500x" → 构建失败:error calling Fill: failed to fill image "…": must provide Width and Height返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
规格正常(500x200 TopRight) |
images.ImageResource,尺寸即所写 |
否 |
只写一个维度(500x、x200) |
—— | 是:error calling Fill: failed to fill image "…": must provide Width and Height |
| 目标尺寸大于源图 | 会放大到目标尺寸再裁边(与 Fit 相反) |
否 |
| 源图本身就是目标宽高比 | 无像素被裁,等价于一次等比缩放 | 否 |
| 目标格式不支持透明(如 JPEG)而源图有 alpha | 透明区按背景色填充,默认取成像配置的 bgColor |
否 |
| 对非图像资源调用 | —— | 是:does not support this method: use reflect.IsImageResource… |
resources.Get 找不到文件(nil) |
—— | 是:nil pointer evaluating resource.Resource.Fill |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 图片边缘的内容被切掉了 | Fill 的语义就是裁边铺满 |
改 Fit(不裁、整张装入)或 Resize(可能变形) |
| 没报错但结果不对 | 人物脸被裁掉一半 | 默认锚点(成像配置的 anchor)不在人脸上 |
显式写 Top、Smart 等锚点,Smart 会找主体 |
| 没报错但结果不对 | 小图被放大后变糊 | 目标尺寸大于源图,Fill 会放大 |
换 Fit(绝不放大),或提供更大的源图 |
| 报错看不懂 | must provide Width and Height |
填充必须同时给出宽和高 | 写成 500x200,不能只写 500x |
更多排查入口见故障排查。