转自:https://gohugo.io/content-management/image-processing/
内容管理基础 知识
图像处理
调整图像大小、裁剪、旋转、过滤和转换图像。
图片资源
要处理图像,您必须将文件作为页面资源、全局资源或远程资源进行访问。
页面资源
页面资源是页面束中的文件。页面束是一个目录,其根目录下有一个index.md
或_index.md
文件。
content/
└── posts/
└── post-1/ <-- page bundle
├── index.md
└── sunset.jpg <-- page resource
要将图像作为页面资源访问:
{{ $image := .Resources.Get "sunset.jpg" }}
全球资源
assets
全局资源是目录内或安装到该目录的任何目录内的文件assets
。
assets/
└── images/
└── sunset.jpg <-- global resource
要将图像作为全局资源访问:
{{ $image := resources.Get "images/sunset.jpg" }}
远程资源
远程资源是远程服务器上的文件,可通过 HTTP 或 HTTPS 访问。要将图像作为远程资源访问:
{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
图像渲染
将图像作为页面资源或全局资源访问后,请使用Permalink
、RelPermalink
、Width
和Height
属性在模板中呈现它。
示例 1:如果找不到资源,则抛出错误。
{{ $image := .Resources.GetMatch "sunset.jpg" }}
<img src="{{ $image.RelPermalink }}">
示例 2:如果未找到资源,则跳过图像渲染。
{{ $image := .Resources.GetMatch "sunset.jpg" }}
{{ with $image }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}
示例 3:如果找不到资源,则跳过图像渲染的更简洁方法。
{{ with .Resources.GetMatch "sunset.jpg" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}
示例 4:如果访问远程资源出现问题,则跳过渲染。
{{ $u := "https://gohugo.io/img/hugo-logo.png" }}
{{ with resources.GetRemote $u }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $u }}
{{ end }}
图像处理方法
该image
资源实现Process
、Resize
、Fit
、Fill
、Crop
、Filter
和方法Colors
。Exif
图像转换期间不会保留元数据(EXIF、IPTC、XMP 等)。使用原始Exif
图像的方法从 JPEG 或 TIFF 图像中提取 EXIF 元数据。
过程
v0.119.0 中的新功能
该Process
方法还可以用作过滤器,如果您需要对图像应用多个过滤器,则该方法更有效。请参阅过程过滤器。
Process 按照给定的规格处理图像。该规范可以包含可选操作, resize
、crop
或之一fit
。fill
这意味着您可以使用此方法来代替Resize
、Fit
、Fill
或Crop
。
请参阅选项了解可用选项。
您还可以使用此方法应用不需要任何缩放的图像处理,例如格式转换:
{{/* Convert the image from JPG to PNG. */}}
{{ $png := $jpg.Process "png" }}
更多示例:
{{/* Rotate the image 90 degrees counter-clockwise. */}}
{{ $image := $image.Process "r90" }}
{{/* Scaling actions. */}}
{{ $image := $image.Process "resize 600x" }}
{{ $image := $image.Process "crop 600x400" }}
{{ $image := $image.Process "fit 600x400" }}
{{ $image := $image.Process "fill 600x400" }}
调整大小
将图像大小调整为给定的宽度和/或高度。
如果同时指定宽度和高度,则生成的图像将不成比例地缩放,除非原始图像具有相同的纵横比。
{{/* Resize to a width of 600px and preserve aspect ratio */}}
{{ $image := $image.Resize "600x" }}
{{/* Resize to a height of 400px and preserve aspect ratio */}}
{{ $image := $image.Resize "x400" }}
{{/* Resize to a width of 600px and a height of 400px */}}
{{ $image := $image.Resize "600x400" }}
合身
缩小图像以适应给定尺寸,同时保持纵横比。您必须提供宽度和高度。
{{ $image := $image.Fit "600x400" }}
充满
裁剪图像并调整其大小以匹配给定的尺寸。您必须提供宽度和高度。使用该anchor
选项更改裁剪框锚点。
{{ $image := $image.Fill "600x400" }}
庄稼
裁剪图像以匹配给定尺寸而不调整大小。您必须提供宽度和高度。使用该anchor
选项更改裁剪框锚点。
{{ $image := $image.Crop "600x400" }}
筛选
对一张图像应用一个或多个滤镜。
{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
使用管道以更实用的方式编写此代码。 Hugo 按给定的顺序应用过滤器。
{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
有时,创建一次过滤器链然后重复使用它可能很有用。
{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }}
{{ $image1 := $image1.Filter $filters }}
{{ $image2 := $image2.Filter $filters }}
颜色
v0.104.0 中的新功能
.Colors
使用简单的直方图方法返回具有图像中主色的十六进制字符串切片。
{{ $colors := $image.Colors }}
此方法速度很快,但如果您还缩小图像,从缩小的图像中提取颜色将有利于性能。
EXIF
提供包含图像元数据的EXIF对象。
您可以访问 JPEG 和 TIFF 图像中的 EXIF 数据。为了防止在处理没有 EXIF 数据的图像时出现错误,请将访问包装在with
语句中。
{{ with $image.Exif }}
Date: {{ .Date }}
Lat/Long: {{ .Lat }}/{{ .Long }}
Tags:
{{ range $k, $v := .Tags }}
TAG: {{ $k }}: {{ $v }}
{{ end }}
{{ end }}
您还可以单独访问 EXIF 字段,使用该lang.FormatNumber
函数根据需要格式化字段。
{{ with $image.Exif }}
<ul>
{{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
{{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
{{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
{{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
{{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
{{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
{{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
{{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
</ul>
{{ end }}
EXIF 方法
日期
( time.Time
) 返回图像创建日期/时间。使用[ ]功能进行格式化time.Format
。
纬度
( float64
) 返回 GPS 纬度(以度为单位)。
长的
( float64
) 返回 GPS 经度(以度为单位)。
标签
( exif.Tags
) 返回该图像的可用 EXIF 标签的集合。您可以在站点配置中包含或排除此集合中的特定标签。</dd>
</dl>
图像处理选项
、、和方法接受Resize
以空格分隔、不区分大小写的选项列表。列表中选项的顺序无关。Fit
Fill
Crop
方面
使用该Resize
方法,您必须指定宽度、高度或两者。 、Fit
、Fill
和Crop
方法需要宽度和高度。所有尺寸均以像素为单位。
{{ $image := $image.Resize "600x" }}
{{ $image := $image.Resize "x400" }}
{{ $image := $image.Resize "600x400" }}
{{ $image := $image.Fit "600x400" }}
{{ $image := $image.Fill "600x400" }}
{{ $image := $image.Crop "600x400" }}
回转
将图像逆时针旋转给定角度。 Hugo 在缩放之前执行旋转。例如,如果原始图像为 600×400,并且您希望将图像逆时针旋转 90 度,同时缩放 50%:
{{ $image = $image.Resize "200x r90" }}
在上例中,宽度表示旋转后所需的宽度。
要旋转图像而不缩放,请使用原始图像的尺寸:
{{ with .Resources.GetMatch "sunset.jpg" }}
{{ with .Resize (printf "%dx%d r90" .Height .Width) }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}
{{ end }}
在上面的示例中,在第二行,我们反转了宽度和高度以反映旋转后所需的尺寸。
锚
使用Crop
orFill
方法时,锚点确定裁剪框的位置。您可以指定TopLeft
、Top
、TopRight
、Left
、Center
、Right
、BottomLeft
、Bottom
、BottomRight
或Smart
。
默认值为Smart
,它使用Smartcrop图像分析来确定裁剪框的最佳位置。您可以覆盖站点配置中的默认值。
例如,如果您有一张 400×200 的图像,左上象限中有一只鸟,则可以创建包含该鸟的 200×100 缩略图:
{{ $image.Crop "200x100 TopLeft" }}
如果在使用or方法时应用旋转,请指定相对于旋转图像的锚点。Crop
Fill
目标格式
默认情况下,Hugo 以源格式对图像进行编码。您可以通过指定bmp
、gif
、jpeg
、jpg
、png
、tif
、tiff
或 来将图像转换为其他格式webp
。
{{ $image.Resize "600x webp" }}
要转换图像而不缩放,请使用原始图像的尺寸:
{{ with .Resources.GetMatch "sunset.jpg" }}
{{ with .Resize (printf "%dx%d webp" .Width .Height) }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}
{{ end }}
质量
适用于JPEG和WebP图像,该q
值决定转换后图像的质量。较高的值会产生更好质量的图像,而较低的值会产生较小的文件。将此值设置为 1 到 100 之间的整数(含 1 和 100)。
默认值为 75。您可以覆盖站点配置中的默认值。
{{ $image.Resize "600x webp q50" }}
暗示
适用于WebP图像,该选项对应一组预定义的编码参数,相当于编码器-preset
的标志cwebp
。
价值 | 例子 |
---|---|
drawing |
具有高对比度细节的手绘或线条画 |
icon |
小彩色图像 |
photo |
自然光下的户外照片 |
picture |
室内照片,例如肖像 |
text |
主要是文本的图像 |
默认值为photo
。您可以覆盖站点配置中的默认值。
{{ $image.Resize "600x webp picture" }}
背景颜色
将图像从支持透明度的格式(例如 PNG)转换为不支持透明度的格式(例如 JPEG)时,您可以指定结果图像的背景颜色。
使用 3 位或 6 位十六进制颜色代码(例如#00f
或#0000ff
)。
默认值为#ffffff
(白色)。您可以覆盖站点配置中的默认值。
{{ $image.Resize "600x jpg #b31280" }}
重采样滤波器
您可以指定调整图像大小时使用的重采样过滤器。常用的重采样滤波器包括:
筛选 | 描述 |
---|---|
Box |
简单快速的平均滤波器适合缩小范围 |
Lanczos |
用于摄影图像的高质量重采样滤波器可产生清晰的结果 |
CatmullRom |
Sharp 立方滤波器比 Lanczos 滤波器更快,同时提供相似的结果 |
MitchellNetravali |
立方滤波器可产生比 CatmullRom 更平滑的结果,振铃伪影更少 |
Linear |
双线性重采样滤波器,产生平滑输出,比三次滤波器更快 |
NearestNeighbor |
最快的重采样滤波器,无抗锯齿 |
默认值为Box
。您可以覆盖站点配置中的默认值。
{{ $image.Resize "600x400 Lanczos" }}
有关重采样过滤器的完整列表,请参阅github.com/disintegration/imaging 。如果您希望以牺牲性能为代价来提高图像质量,您可能希望尝试使用替代滤镜。
图像处理示例
以下示例中使用的日落照片版权所有Bjørn Erik Pedersen(知识共享署名-相同方式共享 4.0 国际许可)
[图片上传失败…(image-eab6c-1715141167669)]
调整大小 300 倍
[图片上传失败…(image-3bff64-1715141167669)]
向左填充 90×120
[图片上传失败…(image-632c44-1715141167669)]
填充 90×120 右
[图片上传失败…(image-5a7642-1715141167669)]
适合90×90
[图片上传失败…(image-427a9d-1715141167669)]
裁剪 250×250 中心
[图片上传失败…(image-3cd9c3-1715141167669)]
调整大小 300x q10
这是用于生成上述示例的简码:
{{- /*
Renders the given image using the given process specification.
@param {string} (positional parameter 0) The path to the image, relative to the current page. The image must be a page resource.
@param {string}} (positional parameter 1) The image processing specification.
@returns template.HTML
@example {{< imgproc "sunset.jpg" "resize 300x" />}}
*/}}
{{- with $.Get 0 }}
{{- with $i := $.Page.Resources.Get . }}
{{- with $spec := $.Get 1 }}
{{- with $i.Process . }}
<figure style="padding: 0.25rem; margin: 2rem 0; background-color: #cccc">
<img style="max-width: 100%; width: auto; height: auto;" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
<figcaption>
<small>
{{- with $.Inner }}
{{ . }}
{{- else }}
{{ $spec }}
{{- end }}
</small>
</figcaption>
</figure>
{{- end }}
{{- else }}
{{- errorf "The %q shortcode requires a positional parameter (1) containing the image processing specification. See %s" $.Name $.Position }}
{{- end }}
{{- else }}
{{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
{{- end }}
{{- else }}
{{- errorf "The %q shortcode requires a positional parameter (0) indicating the image path, relative to the current page. See %s" $.Name $.Position }}
{{- end }}
从 Markdown 中调用短代码,如下所示:
{{< imgproc "sunset.jpg" "resize 300x" />}}
请注意上面的自关闭短代码语法。您可以调用imgproc
带有或不带有内部内容的短代码。
成像配置
加工选项
imaging
在站点配置中定义一个部分来设置默认图像处理选项。
imaging:
bgColor: '#ffffff'
hint: photo
quality: 75
resampleFilter: box
锚
请参阅图像处理选项:anchor。
背景颜色
请参阅图像处理选项:背景颜色。
暗示
请参阅图像处理选项:提示。
质量
请参阅图像处理选项:质量。
重采样过滤器
请参阅图像处理选项:重采样过滤器。
EXIF 数据
在站点配置中定义一个imaging.exif
部分来控制 EXIF 数据的可用性。
imaging:
exif:
disableDate: false
disableLatLong: false
excludeFields: ""
includeFields: ""
禁用日期
Hugo 将图像创建日期/时间提取到.Date
.将其设置为true
禁用。默认为false
.
禁用经纬度
Hugo 将 GPS 纬度和经度提取到.Lat
和中.Long
。将其设置为true
禁用。默认为false
.
排除字段
与要从集合中排除的 EXIF 标记匹配的正则表达式.Tags
。默认为 ""
.
包含字段
与要包含在集合中的 EXIF 标记相匹配的正则表达式.Tags
。默认为 ""
.要包含所有可用标签,请将此值设置为 ".*"
。
为了提高性能并减少缓存大小,Hugo 排除了以下标签:ColorSpace
、Contrast
、Exif
、Exposure[M|P|B]
、Flash
、GPS
、JPEG
、Metering
、Resolution
、Saturation
、Sensing
、Sharp
、 和WhiteBalance
。
要控制标签可用性,请按上述方式更改excludeFields
或设置。includeFields
智能裁剪图像
默认情况下,Hugo在使用或方法裁剪图像时使用Smartcrop库。您可以手动设置锚点,但在大多数情况下,该选项将是一个不错的选择。Crop``Fill``Smart
使用上面的日落图像的示例:
[图片上传失败…(image-fcc295-1715141167669)]
填充 200×200 智能
[图片上传失败…(image-1eaec2-1715141167669)]
裁剪 200×200 智能
图像处理性能考虑
Hugo 将处理后的图像缓存在resources
目录中。如果您将此目录包含在源代码管理中,Hugo 将不必在 CI/CD 工作流程中重新生成图像(例如,GitHub Pages、GitLab Pages、Netlify 等)。这会导致更快的构建。
如果更改图像处理方法或选项,或者重命名或删除图像,该resources
目录将包含未使用的图像。要删除未使用的图像,请使用以下命令执行垃圾收集:
hugo --gc