本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Go 的範本語言
****
本文件主題專為支援 Grafana **9.x 版的 Grafana** 工作區而設計。
如需支援 Grafana 10.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 10 版](using-grafana-v10.md)。
如需支援 Grafana 8.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 8 版](using-grafana-v8.md)。
您使用 Go 的範本語言[文字/範本撰寫通知範本](https://pkg.go.dev/text/template)。
本節提供 Go 的範本語言和以文字/範本撰寫範本的概觀。
## 點
在文字/範本中，有一個稱為點的特殊游標，並寫入為 `.`。您可以將此游標視為變數，其值會根據使用的範本中的位置而變更。例如，在通知範本的開頭`.`是指 `ExtendedData` 物件，其中包含多個欄位，包括 `Alerts`、`Status`、`GroupLabels`、 `CommonLabels``CommonAnnotations`和 `ExternalURL`。不過，當在`range`清單上使用 時、在 內使用時，或寫入要用於其他範本的功能範本時`with`，點可能會參照其他項目。您可以在 中看到此範例[建立通知範本](v9-alerting-create-templates.md)，以及 中的所有資料和函數[範本參考](v9-alerting-template-reference.md)。
## 開啟和關閉標籤
在文字/範本中，無論範本`}}`是否列印變數或執行控制結構，例如 if 陳述式，範本都會以 開頭`{{`和結尾。這與其他範本語言不同，例如 Jinja，其中列印變數使用 `{{`和 `}}`，控制結構使用 `{%`和 `%}`。
## Print (列印)
若要列印某個項目的值，請使用 `{{`和 `}}`。您可以列印點的值、點的欄位、函數的結果，以及[變數](#v9-go-variables)的值。例如，若要列印 點所指`Alerts`的欄位`ExtendedData`，您需要撰寫以下內容：
```
{{ .Alerts }}
```
## 重複提醒
若要只列印每個提醒的標籤，而不是有關提醒的所有資訊，您可以使用 `range`來重複 中的提醒`ExtendedData`：
```
{{ range .Alerts }}
{{ .Labels }}
{{ end }}
```
範圍內的點不再是指 `ExtendedData`，而是 `Alert`。您可以使用 `{{ .Labels }}`來列印每個提醒的標籤。這是因為`{{ range .Alerts }}`變更點指向提醒清單中的目前提醒。當範圍完成時，點會重設為範圍開始之前的值，在此範例中為 `ExtendedData`：
```
{{ range .Alerts }}
{{ .Labels }}
{{ end }}
{{/* does not work, .Labels does not exist here */}}
{{ .Labels }}
{{/* works, cursor was reset */}}
{{ .Status }}
```
## 逐一查看註釋和標籤
讓我們編寫範本，以 格式列印每個提醒的標籤`The name of the label is $name, and the value is $value`，其中 `$name`和 `$value`包含每個標籤的名稱和值。
如同上一個範例，使用範圍來逐一查看提醒，`.Alerts`讓點參照提醒清單中的目前提醒，然後在排序的標籤上使用第二個範圍，讓點再次更新以參照目前的標籤。在第二個範圍內，使用 `.Name` 和 `.Value`來列印每個標籤的名稱和值：
```
{{ range .Alerts }}
{{ range .Labels.SortedPairs }}
The name of the label is {{ .Name }}, and the value is {{ .Value }}
{{ end }}
{{ range .Annotations.SortedPairs }}
The name of the annotation is {{ .Name }}, and the value is {{ .Value }}
{{ end }}
{{ end }}
```
## 如果陳述式
您可以在範本中使用 if 陳述式。例如，`There are no alerts`若要在 中沒有提醒時列印`.Alerts`，您會撰寫下列項目：
```
{{ if .Alerts }}
There are alerts
{{ else }}
There are no alerts
{{ end }}
```
## 使用
使用 與 if 陳述式類似，但與使用 陳述式不同， 會以下列方式`with`更新點來參考 的值：
```
{{ with .Alerts }}
There are {{ len . }} alert(s)
{{ else }}
There are no alerts
{{ end }}
```
## Variables
文字/範本中的變數必須在範本中建立。例如，若要建立名為 `$variable`且目前值為點的變數，您需要撰寫下列項目：
```
{{ $variable := . }}
```
您可以在範圍 或 `$variable`內使用 ，`with`它會在定義變數時參考點的值，而不是點的目前值。
例如，您無法撰寫`{{ .Labels }}`在第二個範圍內使用的範本，因為這裡的點是指目前的標籤，而不是目前的提醒：
```
{{ range .Alerts }}
{{ range .Labels.SortedPairs }}
{{ .Name }} = {{ .Value }}
{{/* does not work because in the second range . is a label not an alert */}}
There are {{ len .Labels }}
{{ end }}
{{ end }}
```
您可以透過在第一個範圍`$alert`和第二個範圍之前定義名為 的變數來修正此問題：
```
{{ range .Alerts }}
{{ $alert := . }}
{{ range .Labels.SortedPairs }}
{{ .Name }} = {{ .Value }}
{{/* works because $alert refers to the value of dot inside the first range */}}
There are {{ len $alert.Labels }}
{{ end }}
{{ end }}
```
## 具有索引的範圍
您可以在範圍的開頭定義索引和值變數，以取得範圍內每個提醒的索引：
```
{{ $num_alerts := len .Alerts }}
{{ range $index, $alert := .Alerts }}
This is alert {{ $index }} out of {{ $num_alerts }}
{{ end }}
```
## 定義範本
您可以使用 `define`和雙引號中的範本名稱，定義可在其他範本中使用的範本。您不應定義與其他範本同名的範本，包括預設範本，例如 `__subject`、`__text_alert_list`、 `__text_values_list``default.title`和 `default.message`。如果已建立與預設範本同名的範本，或另一個通知範本中的範本，Grafana 可能會使用任一個範本。當有兩個或多個具有相同名稱的範本時，Grafana 不會阻止或顯示錯誤訊息。
```
{{ define "print_labels" }}
{{ end }}
```
## 內嵌範本
您可以使用 `template`、雙引號中的範本名稱，以及應該傳遞給範本的游標，在範本中嵌入定義的範本：
```
{{ template "print_labels" . }}
```
## 將資料傳遞至 範本
在範本點中， 是指傳遞給範本的值。
例如，如果範本通過射擊提醒清單，則點是指射擊提醒清單：
```
{{ template "print_alerts" .Alerts }}
```
如果範本已傳遞警示的排序標籤，則點會參照排序標籤的清單：
```
{{ template "print_labels" .SortedLabels }}
```
這在撰寫可重複使用的範本時非常有用。例如，若要列印所有提醒，您可以撰寫下列項目：
```
{{ template "print_alerts" .Alerts }}
```
然後，若要只列印射擊提醒，您可以編寫以下內容：
```
{{ template "print_alerts" .Alerts.Firing }}
```
這可以運作，因為 `.Alerts`和 `.Alerts.Firing` 都是提醒清單。
```
{{ define "print_alerts" }}
{{ range . }}
{{ template "print_labels" .SortedLabels }}
{{ end }}
{{ end }}
```
## 說明
您可以使用 `{{/*`和 新增註解`*/}}`：
```
{{/* This is a comment */}}
```
若要防止註解新增換行符號，請使用：
```
{{- /* This is a comment with no leading or trailing line breaks */ -}}
```
## 縮排
您可以使用縮排、標籤和空格，以及換行，讓範本更易讀：
```
{{ range .Alerts }}
{{ range .Labels.SortedPairs }}
{{ .Name }} = {{ .Value }}
{{ end }}
{{ end }}
```
不過，範本中的縮排也會出現在文字中。接下來，我們將了解如何移除它。
## 移除空格和換行符號
在文字/範本中，使用 `{{-`和 `-}}` 來移除前後空格和換行符號。
例如，使用縮排和換行讓範本更易讀：
```
{{ range .Alerts }}
{{ range .Labels.SortedPairs }}
{{ .Name }} = {{ .Value }}
{{ end }}
{{ end }}
```
縮排和換行也會出現在文字中：
```
alertname = "Test"
grafana_folder = "Test alerts"
```
您可以從在每個範圍`}}``-}}`開始時變更為 的文字中移除縮排和換行：
```
{{ range .Alerts -}}
{{ range .Labels.SortedPairs -}}
{{ .Name }} = {{ .Value }}
{{ end }}
{{ end }}
```
範本中的縮排和換行現在不存在於文字中：
```
alertname = "Test"
grafana_folder = "Test alerts"
```