Filter
返回应用了一个或多个图像滤镜后的新图像资源。
Filter 方法对一张processable image(可处理的图像)应用一个或多个图像滤镜后返回新的资源。
这一页解决什么问题
Filter 解决「在不改尺寸的前提下改变画面的样子」:灰度、模糊、锐化、像素化、叠色、加水印文字都算滤镜。它接收一个滤镜,也接收滤镜切片(按从左到右依次应用),返回一个新图像资源。
典型场景:给文章配图统一做去色处理、给头像加圆角/遮罩、给截图打码(images.Pixelate)、给封面图叠标题文字(images.Text)。
什么时候用,什么时候别用
该用:
- 视觉效果的叠加,且尺寸不变(滤镜本身不改宽高,实测传入
Grayscale前后都是 600×400); - 多个效果串联:
slice里按顺序放滤镜,如先Grayscale再GaussianBlur; - 与变换组合:先
Resize再Filter(或反过来),把结果继续当普通资源用。
别用:
- 只想改尺寸 →
Resize/Fit/Fill/Crop; - 要旋转、转格式、调质量 →
Process;Filter只负责像素效果,images.Process滤镜可以把整套变换塞进滤镜链; - 需要在管道里一次性串联多个图像操作 → 用
images.Filter函数,写法更顺手。
用法
用 Filter 方法应用模糊、锐化、灰度转换等效果。可以传入单个滤镜,也可以传入滤镜切片。传入切片时,Hugo 从左到右依次应用这些滤镜。
应用单个滤镜:
go-html-template
{{ with resources.Get "images/original.jpg" }}
{{ with .Filter images.Grayscale }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}应用多个滤镜:
go-html-template
{{ $filters := slice
images.Grayscale
(images.GaussianBlur 8)
}}
{{ with resources.Get "images/original.jpg" }}
{{ with .Filter $filters }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}也可以用 images.Filter 函数应用图像滤镜。
示例
go-html-template
{{ with resources.Get "images/original.jpg" }}
{{ with .Filter images.Grayscale }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}英文原文此处用示例照片演示 Grayscale 滤镜的前后对比效果;本站未收录该示例图。
图像滤镜
以下滤镜都可以配合 Filter 方法使用。
- images.AutoOrient
- images.Brightness
- images.ColorBalance
- images.Colorize
- images.Contrast
- images.Dither
- images.Gamma
- images.GaussianBlur
- images.Grayscale
- images.Hue
- images.Invert
- images.Mask
- images.Opacity
- images.Overlay
- images.Padding
- images.Pixelate
- images.Process
- images.Saturation
- images.Sepia
- images.Sigmoid
- images.Text
- images.UnsharpMask
完整示例(实测)
测量条件:Hugo 0.167.0 extended,Windows;assets/images/original.jpg 是一张 600×400 的 JPEG。放进 layouts/_default/single.html:
layouts/_default/single.htmlgo-html-template
{{ $filters := slice
images.Grayscale
(images.GaussianBlur 8)
}}
{{ with resources.Get "images/original.jpg" }}
{{ with .Filter images.Grayscale }}
<p>单滤镜:{{ .RelPermalink }} {{ .Width }}x{{ .Height }}</p>
{{ end }}
{{ with .Filter $filters }}
<p>双滤镜:{{ .RelPermalink }} {{ .Width }}x{{ .Height }}</p>
{{ end }}
{{ end }}Hugo 渲染为:
html
<p>单滤镜:/images/original_hu_e9cc708b5d920c7d.jpg 600x400</p>
<p>双滤镜:/images/original_hu_31ead45f613460c3.jpg 600x400</p>你应当看到什么:
- 两个 URL 不同(滤镜链不同 → 缓存键不同),但宽高与源图完全一致——滤镜不改尺寸;
- 单滤镜 URL 与双滤镜 URL 的哈希不同,说明「同一个滤镜链」才会命中同一份缓存:把
GaussianBlur的 8 改成 6,就会生成第三个文件。
滤镜拼错时的实测行为:
{{ .Filter "not-a-filter" }}
→ error calling Filter: string is not an image filter返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
单个滤镜(images.Grayscale) |
images.ImageResource,宽高不变 |
否 |
| 滤镜切片 | 按从左到右应用,宽高不变 | 否 |
传空切片 slice |
未实测(上游未说明);不传滤镜时改用原资源更清楚 | —— |
| 传字符串而不是滤镜 | —— | 是:error calling Filter: string is not an image filter |
| 图像本身不支持 alpha 而滤镜需要 | 由具体滤镜决定,未实测 | —— |
| 对非图像资源调用 | —— | 是:does not support this method: use reflect.IsImageResource… |
resources.Get 找不到文件(nil) |
—— | 是:nil pointer evaluating resource.Resource.Filter |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 报错看不懂 | string is not an image filter |
把滤镜名写成了字符串("images.Grayscale") |
写函数调用本身:images.Grayscale,带参数的要加括号 (images.GaussianBlur 8) |
| 没报错但结果不对 | 生成了一堆内容相同的图片 | 滤镜链稍有不同就是另一个缓存键 | 把滤镜链提取成 $filters 变量,全站复用 |
| 没报错但结果不对 | 想改尺寸却发现尺寸没变 | Filter 只做像素效果 |
尺寸交给 Resize/Fit/Fill/Crop |
| 构建失败 | does not support this method |
对文本等非图像资源用了 Filter |
先用 reflect.IsImageResourceProcessable 判断 |
更多排查入口见故障排查。