Пакет template
Обзор
Пакет template (html/template) реализует шаблоны, управляемые данными, для генерации HTML-вывода, защищённого от внедрения кода. Он предоставляет тот же интерфейс, что и text/template, и его следует использовать вместо text/template во всех случаях, когда вывод является HTML.
В этой документации основное внимание уделяется функциям безопасности пакета. Сведения о том, как программировать сами шаблоны, см. в документации по text/template.
Введение
Этот пакет обёртывает text/template, позволяя использовать его API шаблонов для безопасного разбора и выполнения HTML-шаблонов.
tmpl, err := template.New("name").Parse(...)
// Error checking elided
err = tmpl.Execute(out, data)
При успешном выполнении tmpl теперь будет защищён от внедрения кода. В противном случае err — это ошибка, описанная в документации для ErrorCode.
HTML-шаблоны рассматривают значения данных как обычный текст, который следует кодировать, чтобы его можно было безопасно встроить в HTML-документ. Экранирование зависит от контекста, поэтому действия могут находиться в контекстах JavaScript, CSS и URI.
Комментарии удаляются из вывода, за исключением комментариев, переданных через типы HTML, CSS и JS для соответствующих контекстов.
Модель безопасности, используемая этим пакетом, предполагает, что авторам шаблонов можно доверять, а параметру данных Execute — нет. Дополнительные сведения приведены ниже.
Пример
import "text/template"
...
t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>")
даёт результат
Hello, <script>alert('you have been pwned')</script>!
но контекстное автоматическое экранирование в html/template
import "html/template"
...
t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>")
создаёт безопасный экранированный HTML-вывод
Hello, <script>alert('you have been pwned')</script>!
Контексты
Этот пакет распознаёт HTML, CSS, JavaScript и URI. Он добавляет функции очистки в каждый конвейер простых действий, поэтому для приведённого фрагмента
<a href="/search?q={{.}}">{{.}}</a>
Во время разбора каждый {{.}} переопределяется, чтобы добавить необходимые функции экранирования. В данном случае он становится
<a href="/search?q={{. | urlescaper | attrescaper}}">{{. | htmlescaper}}</a>
где urlescaper, attrescaper и htmlescaper являются псевдонимами внутренних функций экранирования.
Для этих внутренних функций экранирования, если конвейер действия вычисляется в значение интерфейса nil, оно рассматривается как пустая строка.
Атрибуты с пространствами имён и атрибуты data-
Атрибуты с пространством имён рассматриваются так, как если бы у них не было пространства имён. Для приведённого фрагмента
<a my:href="{{.}}"></a>
Во время разбора атрибут будет рассматриваться так, как если бы это был просто "href". Поэтому после разбора шаблон становится таким:
<a my:href="{{. | urlescaper | attrescaper}}"></a>
Как и атрибуты с пространствами имён, атрибуты с префиксом "data-" рассматриваются так, как если бы у них не было префикса "data-". Таким образом, для
<a data-href="{{.}}"></a>
Во время разбора это становится
<a data-href="{{. | urlescaper | attrescaper}}"></a>
Если у атрибута есть и пространство имён, и префикс "data-", при определении контекста будет удалено только пространство имён. Например,
<a my:data-href="{{.}}"></a>
Это обрабатывается так, как если бы "my:data-href" было просто "data-href", а не "href", как было бы, если бы префикс "data-" также игнорировался. Поэтому во время разбора это становится просто
<a my:data-href="{{. | attrescaper}}"></a>
В особом случае атрибуты с пространством имён "xmlns" всегда рассматриваются как содержащие URL. Для приведённых фрагментов
<a xmlns:title="{{.}}"></a>
<a xmlns:href="{{.}}"></a>
<a xmlns:onclick="{{.}}"></a>
Во время разбора они становятся такими:
<a xmlns:title="{{. | urlescaper | attrescaper}}"></a>
<a xmlns:href="{{. | urlescaper | attrescaper}}"></a>
<a xmlns:onclick="{{. | urlescaper | attrescaper}}"></a>
Ошибки
Подробности см. в документации по ErrorCode.
Более подробное описание
Остальную часть комментария к этому пакету можно пропустить при первом чтении; она содержит сведения, необходимые для понимания контекстов экранирования и сообщений об ошибках. Большинству пользователей эти подробности знать не потребуется.
Контексты
Предположим, что {{.}} — это `O'Reilly: How are <i>you</i>?`; в таблице ниже показано, как выглядит {{.}} при использовании в контексте слева.
Context {{.}} After
{{.}} O'Reilly: How are <i>you</i>?
<a title='{{.}}'> O'Reilly: How are you?
<a href="/{{.}}"> O'Reilly: How are %3ci%3eyou%3c/i%3e?
<a href="?q={{.}}"> O'Reilly%3a%20How%20are%3ci%3e...%3f
<a onx='f("{{.}}")'> O\x27Reilly: How are \x3ci\x3eyou...?
<a onx='f({{.}})'> "O\x27Reilly: How are \x3ci\x3eyou...?"
<a onx='pattern = /{{.}}/;'> O\x27Reilly: How are \x3ci\x3eyou...\x3f
При использовании в небезопасном контексте значение может быть отфильтровано:
Context {{.}} After
<a href="{{.}}"> #ZgotmplZ
поскольку "O'Reilly:" не является допустимым протоколом, например "http:".
Если {{.}} — это безобидное слово `left`, его можно использовать в большем числе контекстов,
Context {{.}} After
{{.}} left
<a title='{{.}}'> left
<a href='{{.}}'> left
<a href='/{{.}}'> left
<a href='?dir={{.}}'> left
<a style="border-{{.}}: 4px"> left
<a style="align: {{.}}"> left
<a style="background: '{{.}}'> left
<a style="background: url('{{.}}')> left
<style>p.{{.}} {color:red}</style> left
В контекстах JavaScript можно использовать значения, не являющиеся строками. Если {{.}} — это
struct{A,B string}{ "foo", "bar" }
в экранированном шаблоне
<script>var pair = {{.}};</script>
тогда вывод шаблона будет таким
<script>var pair = {"A": "foo", "B": "bar"};</script>
Сведения о том, как пакет json маршалит содержимое, не являющееся строкой, для встраивания в контексты JavaScript, см. в документации пакета.
Строки с типом
По умолчанию этот пакет предполагает, что все конвейеры возвращают обычную текстовую строку. Он добавляет этапы экранирования, необходимые для правильного и безопасного встраивания этого обычного текста в соответствующий контекст.
Если значение данных не является обычным текстом, можно предотвратить его чрезмерное экранирование, указав его тип.
Типы HTML, JS, URL и другие из content.go могут содержать безопасное содержимое, которое не подвергается экранированию.
Шаблон
Hello, {{.}}!
можно вызвать с помощью
tmpl.Execute(out, template.HTML(`<b>World</b>`))
чтобы получить
Hello, <b>World</b>!
вместо
Hello, <b>World<b>!
который был бы получен, если бы {{.}} являлся обычной строкой.
Модель безопасности
В документе https://web.archive.org/web/20160501113828/http://js-quasis-libraries-and-repl.googlecode.com/svn/trunk/safetemplate.html#problem_definition определено значение термина "безопасный", используемого этим пакетом.
Этот пакет предполагает, что авторам шаблонов можно доверять, а параметру данных Execute — нет, и стремится сохранять перечисленные ниже свойства при наличии недоверенных данных:
Свойство сохранения структуры: "... когда автор шаблона записывает HTML-тег на безопасном языке шаблонов, браузер будет интерпретировать соответствующую часть вывода как тег независимо от значений недоверенных данных; то же относится и к другим структурам, таким как границы атрибутов и границы строк JavaScript и CSS."
Свойство эффекта кода: "... в результате внедрения вывода шаблона в страницу должен выполняться только код, указанный автором шаблона, и должен выполняться весь код, указанный автором шаблона."
Свойство минимальной неожиданности: "Разработчик (или проверяющий код), знакомый с HTML, CSS и JavaScript и знающий о контекстном автоматическом экранировании, должен иметь возможность посмотреть на {{.}} и правильно определить, какая очистка будет выполнена."
Ранее шаблонные литералы ECMAScript 6 были отключены по умолчанию, и их можно было включить с помощью переменной окружения GODEBUG=jstmpllitinterp=1. Теперь шаблонные литералы поддерживаются по умолчанию, и установка jstmpllitinterp не оказывает никакого эффекта.
Пример
Код:
const tpl = `
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>{{.Title}}</title>
</head>
<body>
{{range .Items}}<div>{{ . }}</div>{{else}}<div><strong>no rows</strong></div>{{end}}
</body>
</html>`
check := func(err error) {
if err != nil {
log.Fatal(err)
}
}
t, err := template.New("webpage").Parse(tpl)
check(err)
data := struct {
Title string
Items []string
}{
Title: "My page",
Items: []string{
"My photos",
"My blog",
},
}
err = t.Execute(os.Stdout, data)
check(err)
noItems := struct {
Title string
Items []string
}{
Title: "My another page",
Items: []string{},
}
err = t.Execute(os.Stdout, noItems)
check(err)
Вывод:
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>My page</title> </head> <body> <div>My photos</div><div>My blog</div> </body> </html> <!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>My another page</title> </head> <body> <div><strong>no rows</strong></div> </body> </html>
Пример (автоматическое экранирование)
Код:
check := func(err error) {
if err != nil {
log.Fatal(err)
}
}
t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
check(err)
err = t.ExecuteTemplate(os.Stdout, "T", "<script>alert('you have been pwned')</script>")
check(err)
Вывод:
Hello, <script>alert('you have been pwned')</script>!
Пример (экранирование)
Код:
const s = `"Fran & Freddie's Diner" <tasty@example.com>`
v := []any{`"Fran & Freddie's Diner"`, ' ', `<tasty@example.com>`}
fmt.Println(template.HTMLEscapeString(s))
template.HTMLEscape(os.Stdout, []byte(s))
fmt.Fprintln(os.Stdout, "")
fmt.Println(template.HTMLEscaper(v...))
fmt.Println(template.JSEscapeString(s))
template.JSEscape(os.Stdout, []byte(s))
fmt.Fprintln(os.Stdout, "")
fmt.Println(template.JSEscaper(v...))
fmt.Println(template.URLQueryEscaper(v...))
Вывод:
"Fran & Freddie's Diner" <tasty@example.com> "Fran & Freddie's Diner" <tasty@example.com> "Fran & Freddie's Diner"32<tasty@example.com> \"Fran \u0026 Freddie\'s Diner\" \u003Ctasty@example.com\u003E \"Fran \u0026 Freddie\'s Diner\" \u003Ctasty@example.com\u003E \"Fran \u0026 Freddie\'s Diner\"32\u003Ctasty@example.com\u003E %22Fran+%26+Freddie%27s+Diner%2232%3Ctasty%40example.com%3E
Указатель
Примеры
Файлы пакета
attr.go attr_string.go content.go context.go css.go delim_string.go doc.go element_string.go error.go escape.go html.go js.go jsctx_string.go state_string.go template.go transition.go url.go urlpart_string.go
func HTMLEscape
func HTMLEscape(w io.Writer, b []byte)
HTMLEscape записывает в w эквивалент данных обычного текста b, экранированный для HTML.
func HTMLEscapeString
func HTMLEscapeString(s string) string
HTMLEscapeString возвращает эквивалент данных обычного текста s, экранированный для HTML.
func HTMLEscaper
func HTMLEscaper(args ...any) string
HTMLEscaper возвращает эквивалент текстового представления аргументов, экранированный для HTML.
func IsTrue 1.6
func IsTrue(val any) (truth, ok bool)
IsTrue сообщает, является ли значение «истинным» в смысле отличия от нулевого значения своего типа, а также имеет ли оно осмысленное логическое значение. Это определение истинности используется в if и других подобных действиях.
func JSEscape
func JSEscape(w io.Writer, b []byte)
JSEscape записывает в w эквивалент данных обычного текста b, экранированный для JavaScript.
func JSEscapeString
func JSEscapeString(s string) string
JSEscapeString возвращает эквивалент данных обычного текста s, экранированный для JavaScript.
func JSEscaper
func JSEscaper(args ...any) string
JSEscaper возвращает эквивалент текстового представления аргументов, экранированный для JavaScript.
func URLQueryEscaper
func URLQueryEscaper(args ...any) string
URLQueryEscaper возвращает значение, представленное текстовым видом аргументов и экранированное в форме, подходящей для встраивания в запрос URL.
type CSS
CSS содержит заведомо безопасное содержимое, соответствующее одному из следующих вариантов:
- Производство таблицы стилей CSS3, например `p { color: purple }`.
- Производство правила CSS3, например `a[href=~"https:"].foo#bar`.
- Производство объявления CSS3, например `color: red; margin: 2px`.
- Производство значения CSS3, например `rgba(0, 0, 255, 127)`.
См. https://www.w3.org/TR/css3-syntax/#parsing и https://web.archive.org/web/20090211114933/http://w3.org/TR/css3-syntax#style
Использование этого типа создаёт угрозу безопасности: заключённое в него содержимое должно поступать из доверенного источника, поскольку оно будет включено в вывод шаблона без изменений.
type CSS string
type Error
Error описывает проблему, возникшую при экранировании шаблона.
type Error struct {
// ErrorCode describes the kind of error.
ErrorCode ErrorCode
// Node is the node that caused the problem, if known.
// If not nil, it overrides Name and Line.
Node parse.Node // Go 1.4
// Name is the name of the template in which the error was encountered.
Name string
// Line is the line number of the error in the template source or 0.
Line int
// Description is a human-readable description of the problem.
Description string
}
func (*Error) Error
func (e *Error) Error() string
type ErrorCode
ErrorCode — это код типа ошибки.
type ErrorCode int
Мы определяем коды для каждой ошибки, возникающей при экранировании шаблонов, однако экранированные шаблоны также могут завершиться ошибкой во время выполнения.
Вывод: "ZgotmplZ" Пример:
<img src="{{.X}}">
where {{.X}} evaluates to `javascript:...`
Обсуждение:
"ZgotmplZ" is a special value that indicates that unsafe content reached a CSS or URL context at runtime. The output of the example will be <img src="#ZgotmplZ"> If the data comes from a trusted source, use content types to exempt it from filtering: URL(`javascript:...`).
const (
// OK indicates the lack of an error.
OK ErrorCode = iota
// ErrAmbigContext: "... appears in an ambiguous context within a URL"
// Example:
// <a href="
// {{if .C}}
// /path/
// {{else}}
// /search?q=
// {{end}}
// {{.X}}
// ">
// Discussion:
// {{.X}} is in an ambiguous URL context since, depending on {{.C}},
// it may be either a URL suffix or a query parameter.
// Moving {{.X}} into the condition removes the ambiguity:
// <a href="{{if .C}}/path/{{.X}}{{else}}/search?q={{.X}}">
ErrAmbigContext
// ErrBadHTML: "expected space, attr name, or end of tag, but got ...",
// "... in unquoted attr", "... in attribute name"
// Example:
// <a href = /search?q=foo>
// <href=foo>
// <form na<e=...>
// <option selected<
// Discussion:
// This is often due to a typo in an HTML element, but some runes
// are banned in tag names, attribute names, and unquoted attribute
// values because they can tickle parser ambiguities.
// Quoting all attributes is the best policy.
ErrBadHTML
// ErrBranchEnd: "{{if}} branches end in different contexts"
// Examples:
// {{if .C}}<a href="{{end}}{{.X}}
// <script {{with .T}}type="{{.}}"{{end}}>
// Discussion:
// Package html/template statically examines each path through an
// {{if}}, {{range}}, or {{with}} to escape any following pipelines.
// The first example is ambiguous since {{.X}} might be an HTML text node,
// or a URL prefix in an HTML attribute. The context of {{.X}} is
// used to figure out how to escape it, but that context depends on
// the run-time value of {{.C}} which is not statically known.
// The second example is ambiguous as the script type attribute
// can change the type of escaping needed for the script contents.
//
// The problem is usually something like missing quotes or angle
// brackets, or can be avoided by refactoring to put the two contexts
// into different branches of an if, range or with. If the problem
// is in a {{range}} over a collection that should never be empty,
// adding a dummy {{else}} can help.
ErrBranchEnd
// ErrEndContext: "... ends in a non-text context: ..."
// Examples:
// <div
// <div title="no close quote>
// <script>f()
// Discussion:
// Executed templates should produce a DocumentFragment of HTML.
// Templates that end without closing tags will trigger this error.
// Templates that should not be used in an HTML context or that
// produce incomplete Fragments should not be executed directly.
//
// {{define "main"}} <script>{{template "helper"}}</script> {{end}}
// {{define "helper"}} document.write(' <div title=" ') {{end}}
//
// "helper" does not produce a valid document fragment, so should
// not be Executed directly.
ErrEndContext
// ErrNoSuchTemplate: "no such template ..."
// Examples:
// {{define "main"}}<div {{template "attrs"}}>{{end}}
// {{define "attrs"}}href="{{.URL}}"{{end}}
// Discussion:
// Package html/template looks through template calls to compute the
// context.
// Here the {{.URL}} in "attrs" must be treated as a URL when called
// from "main", but you will get this error if "attrs" is not defined
// when "main" is parsed.
ErrNoSuchTemplate
// ErrOutputContext: "cannot compute output context for template ..."
// Examples:
// {{define "t"}}{{if .T}}{{template "t" .T}}{{end}}{{.H}}",{{end}}
// Discussion:
// A recursive template does not end in the same context in which it
// starts, and a reliable output context cannot be computed.
// Look for typos in the named template.
// If the template should not be called in the named start context,
// look for calls to that template in unexpected contexts.
// Maybe refactor recursive templates to not be recursive.
ErrOutputContext
// ErrPartialCharset: "unfinished JS regexp charset in ..."
// Example:
// <script>var pattern = /foo[{{.Chars}}]/</script>
// Discussion:
// Package html/template does not support interpolation into regular
// expression literal character sets.
ErrPartialCharset
// ErrPartialEscape: "unfinished escape sequence in ..."
// Example:
// <script>alert("\{{.X}}")</script>
// Discussion:
// Package html/template does not support actions following a
// backslash.
// This is usually an error and there are better solutions; for
// example
// <script>alert("{{.X}}")</script>
// should work, and if {{.X}} is a partial escape sequence such as
// "xA0", mark the whole sequence as safe content: JSStr(`\xA0`)
ErrPartialEscape
// ErrRangeLoopReentry: "on range loop re-entry: ..."
// Example:
// <script>var x = [{{range .}}'{{.}},{{end}}]</script>
// Discussion:
// If an iteration through a range would cause it to end in a
// different context than an earlier pass, there is no single context.
// In the example, there is missing a quote, so it is not clear
// whether {{.}} is meant to be inside a JS string or in a JS value
// context. The second iteration would produce something like
//
// <script>var x = ['firstValue,'secondValue]</script>
ErrRangeLoopReentry
// ErrSlashAmbig: '/' could start a division or regexp.
// Example:
// <script>
// {{if .C}}var x = 1{{end}}
// /-{{.N}}/i.test(x) ? doThis : doThat();
// </script>
// Discussion:
// The example above could produce `var x = 1/-2/i.test(s)...`
// in which the first '/' is a mathematical division operator or it
// could produce `/-2/i.test(s)` in which the first '/' starts a
// regexp literal.
// Look for missing semicolons inside branches, and maybe add
// parentheses to make it clear which interpretation you intend.
ErrSlashAmbig
// ErrPredefinedEscaper: "predefined escaper ... disallowed in template"
// Example:
// <div class={{. | html}}>Hello<div>
// Discussion:
// Package html/template already contextually escapes all pipelines to
// produce HTML output safe against code injection. Manually escaping
// pipeline output using the predefined escapers "html" or "urlquery" is
// unnecessary, and may affect the correctness or safety of the escaped
// pipeline output in Go 1.8 and earlier.
//
// In most cases, such as the given example, this error can be resolved by
// simply removing the predefined escaper from the pipeline and letting the
// contextual autoescaper handle the escaping of the pipeline. In other
// instances, where the predefined escaper occurs in the middle of a
// pipeline where subsequent commands expect escaped input, e.g.
// {{.X | html | makeALink}}
// where makeALink does
// return `<a href="`+input+`">link</a>`
// consider refactoring the surrounding template to make use of the
// contextual autoescaper, i.e.
// <a href="{{.X}}">link</a>
//
// To ease migration to Go 1.9 and beyond, "html" and "urlquery" will
// continue to be allowed as the last command in a pipeline. However, if the
// pipeline occurs in an unquoted attribute value context, "html" is
// disallowed. Avoid using "html" and "urlquery" entirely in new templates.
ErrPredefinedEscaper
// ErrJSTemplate: "... appears in a JS template literal"
// Example:
// <script>var tmpl = `{{.Interp}}`</script>
// Discussion:
// Package html/template does not support actions inside of JS template
// literals.
//
// Deprecated: ErrJSTemplate is no longer returned when an action is present
// in a JS template literal. Actions inside of JS template literals are now
// escaped as expected.
ErrJSTemplate
) type FuncMap
type FuncMap = template.FuncMap
type HTML
HTML содержит заведомо безопасный фрагмент HTML-документа. Этот тип не следует использовать для HTML-кода сторонних источников, а также для HTML-кода с незакрытыми тегами или комментариями. Результаты работы надёжного санитайзера HTML и шаблон, экранированный этим пакетом, можно безопасно использовать с HTML.
Использование этого типа создаёт угрозу безопасности: заключённое в него содержимое должно поступать из доверенного источника, поскольку оно будет включено в вывод шаблона без изменений.
type HTML string
type HTMLAttr
HTMLAttr содержит HTML-атрибут из доверенного источника, например ` dir="ltr"`.
Использование этого типа создаёт угрозу безопасности: заключённое в него содержимое должно поступать из доверенного источника, поскольку оно будет включено в вывод шаблона без изменений.
type HTMLAttr string
type JS
JS содержит заведомо безопасное выражение EcmaScript5, например `(x + y * z())`. Авторы шаблонов должны следить за тем, чтобы выражения с указанным типом не нарушали предполагаемый приоритет операций и не допускали неоднозначности между инструкцией и выражением, как при передаче выражения вида "{ foo: bar() }\n['foo']()", которое является и допустимым выражением, и допустимой программой, но имеет совершенно разный смысл.
Использование этого типа создаёт угрозу безопасности: заключённое в него содержимое должно поступать из доверенного источника, поскольку оно будет включено в вывод шаблона без изменений.
Использовать JS для включения корректного, но недоверенного JSON небезопасно. Безопасная альтернатива — разобрать JSON с помощью json.Unmarshal, а затем передать полученный объект в шаблон; при выводе в контексте JavaScript он будет преобразован в очищенный JSON.
type JS string
type JSStr
JSStr содержит последовательность символов, предназначенную для встраивания между кавычками в выражение JavaScript. Строка должна соответствовать последовательности StringCharacters:
StringCharacter :: SourceCharacter but not `\` or LineTerminator
| EscapeSequence
Обратите внимание, что продолжения строк LineContinuations не допускаются. JSStr("foo\\nbar") допустимо, а JSStr("foo\\\nbar") — нет.
Использование этого типа создаёт угрозу безопасности: заключённое в него содержимое должно поступать из доверенного источника, поскольку оно будет включено в вывод шаблона без изменений.
type JSStr string
type Srcset 1.10
Srcset содержит заведомо безопасный атрибут srcset (см. https://w3c.github.io/html/semantics-embedded-content.html#element-attrdef-img-srcset).
Использование этого типа создаёт угрозу безопасности: заключённое в него содержимое должно поступать из доверенного источника, поскольку оно будет включено в вывод шаблона без изменений.
type Srcset string
type Template
Template — это специализированный шаблон из "text/template", который создаёт безопасный фрагмент HTML-документа.
type Template struct {
// The underlying template's parse tree, updated to be HTML-safe
// after the first execution.
Tree *parse.Tree // Go 1.2
// contains filtered or unexported fields
}
Пример (блок)
Код:
const (
master = `Names:{{block "list" .}}{{"\n"}}{{range .}}{{println "-" .}}{{end}}{{end}}`
overlay = `{{define "list"}} {{join . ", "}}{{end}} `
)
var (
funcs = template.FuncMap{"join": strings.Join}
guardians = []string{"Gamora", "Groot", "Nebula", "Rocket", "Star-Lord"}
)
masterTmpl, err := template.New("master").Funcs(funcs).Parse(master)
if err != nil {
log.Fatal(err)
}
overlayTmpl, err := template.Must(masterTmpl.Clone()).Parse(overlay)
if err != nil {
log.Fatal(err)
}
if err := masterTmpl.Execute(os.Stdout, guardians); err != nil {
log.Fatal(err)
}
if err := overlayTmpl.Execute(os.Stdout, guardians); err != nil {
log.Fatal(err)
}
Вывод:
Names: - Gamora - Groot - Nebula - Rocket - Star-Lord Names: Gamora, Groot, Nebula, Rocket, Star-Lord
Пример (glob)
Здесь показано, как загрузить набор шаблонов из каталога.
Код:
// Here we create a temporary directory and populate it with our sample
// template definition files; usually the template files would already
// exist in some location known to the program.
dir := createTestDir([]templateFile{
// T0.tmpl is a plain template file that just invokes T1.
{"T0.tmpl", `T0 invokes T1: ({{template "T1"}})`},
// T1.tmpl defines a template, T1 that invokes T2.
{"T1.tmpl", `{{define "T1"}}T1 invokes T2: ({{template "T2"}}){{end}}`},
// T2.tmpl defines a template T2.
{"T2.tmpl", `{{define "T2"}}This is T2{{end}}`},
})
// Clean up after the test; another quirk of running as an example.
defer os.RemoveAll(dir)
// pattern is the glob pattern used to find all the template files.
pattern := filepath.Join(dir, "*.tmpl")
// Here starts the example proper.
// T0.tmpl is the first name matched, so it becomes the starting template,
// the value returned by ParseGlob.
tmpl := template.Must(template.ParseGlob(pattern))
err := tmpl.Execute(os.Stdout, nil)
if err != nil {
log.Fatalf("template execution: %s", err)
}
Вывод:
T0 invokes T1: (T1 invokes T2: (This is T2))
Пример (вспомогательные шаблоны)
В этом примере показан один из способов совместного использования шаблонов и их применения в разных контекстах. В этом варианте мы вручную добавляем несколько управляющих шаблонов к существующему набору шаблонов.
Код:
// Here we create a temporary directory and populate it with our sample
// template definition files; usually the template files would already
// exist in some location known to the program.
dir := createTestDir([]templateFile{
// T1.tmpl defines a template, T1 that invokes T2.
{"T1.tmpl", `{{define "T1"}}T1 invokes T2: ({{template "T2"}}){{end}}`},
// T2.tmpl defines a template T2.
{"T2.tmpl", `{{define "T2"}}This is T2{{end}}`},
})
// Clean up after the test; another quirk of running as an example.
defer os.RemoveAll(dir)
// pattern is the glob pattern used to find all the template files.
pattern := filepath.Join(dir, "*.tmpl")
// Here starts the example proper.
// Load the helpers.
templates := template.Must(template.ParseGlob(pattern))
// Add one driver template to the bunch; we do this with an explicit template definition.
_, err := templates.Parse("{{define `driver1`}}Driver 1 calls T1: ({{template `T1`}})\n{{end}}")
if err != nil {
log.Fatal("parsing driver1: ", err)
}
// Add another driver template.
_, err = templates.Parse("{{define `driver2`}}Driver 2 calls T2: ({{template `T2`}})\n{{end}}")
if err != nil {
log.Fatal("parsing driver2: ", err)
}
// We load all the templates before execution. This package does not require
// that behavior but html/template's escaping does, so it's a good habit.
err = templates.ExecuteTemplate(os.Stdout, "driver1", nil)
if err != nil {
log.Fatalf("driver1 execution: %s", err)
}
err = templates.ExecuteTemplate(os.Stdout, "driver2", nil)
if err != nil {
log.Fatalf("driver2 execution: %s", err)
}
Вывод:
Driver 1 calls T1: (T1 invokes T2: (This is T2)) Driver 2 calls T2: (This is T2)
Пример (разбор файлов)
Здесь показано, как загрузить набор шаблонов из файлов, находящихся в разных каталогах.
Код:
// Here we create different temporary directories and populate them with our sample
// template definition files; usually the template files would already
// exist in some location known to the program.
dir1 := createTestDir([]templateFile{
// T1.tmpl is a plain template file that just invokes T2.
{"T1.tmpl", `T1 invokes T2: ({{template "T2"}})`},
})
dir2 := createTestDir([]templateFile{
// T2.tmpl defines a template T2.
{"T2.tmpl", `{{define "T2"}}This is T2{{end}}`},
})
// Clean up after the test; another quirk of running as an example.
defer func(dirs ...string) {
for _, dir := range dirs {
os.RemoveAll(dir)
}
}(dir1, dir2)
// Here starts the example proper.
// Let's just parse only dir1/T0 and dir2/T2
paths := []string{
filepath.Join(dir1, "T1.tmpl"),
filepath.Join(dir2, "T2.tmpl"),
}
tmpl := template.Must(template.ParseFiles(paths...))
err := tmpl.Execute(os.Stdout, nil)
if err != nil {
log.Fatalf("template execution: %s", err)
}
Вывод:
T1 invokes T2: (This is T2)
Пример (совместное использование)
В этом примере показано, как использовать одну группу управляющих шаблонов с разными наборами вспомогательных шаблонов.
Код:
// Here we create a temporary directory and populate it with our sample
// template definition files; usually the template files would already
// exist in some location known to the program.
dir := createTestDir([]templateFile{
// T0.tmpl is a plain template file that just invokes T1.
{"T0.tmpl", "T0 ({{.}} version) invokes T1: ({{template `T1`}})\n"},
// T1.tmpl defines a template, T1 that invokes T2. Note T2 is not defined
{"T1.tmpl", `{{define "T1"}}T1 invokes T2: ({{template "T2"}}){{end}}`},
})
// Clean up after the test; another quirk of running as an example.
defer os.RemoveAll(dir)
// pattern is the glob pattern used to find all the template files.
pattern := filepath.Join(dir, "*.tmpl")
// Here starts the example proper.
// Load the drivers.
drivers := template.Must(template.ParseGlob(pattern))
// We must define an implementation of the T2 template. First we clone
// the drivers, then add a definition of T2 to the template name space.
// 1. Clone the helper set to create a new name space from which to run them.
first, err := drivers.Clone()
if err != nil {
log.Fatal("cloning helpers: ", err)
}
// 2. Define T2, version A, and parse it.
_, err = first.Parse("{{define `T2`}}T2, version A{{end}}")
if err != nil {
log.Fatal("parsing T2: ", err)
}
// Now repeat the whole thing, using a different version of T2.
// 1. Clone the drivers.
second, err := drivers.Clone()
if err != nil {
log.Fatal("cloning drivers: ", err)
}
// 2. Define T2, version B, and parse it.
_, err = second.Parse("{{define `T2`}}T2, version B{{end}}")
if err != nil {
log.Fatal("parsing T2: ", err)
}
// Execute the templates in the reverse order to verify the
// first is unaffected by the second.
err = second.ExecuteTemplate(os.Stdout, "T0.tmpl", "second")
if err != nil {
log.Fatalf("second execution: %s", err)
}
err = first.ExecuteTemplate(os.Stdout, "T0.tmpl", "first")
if err != nil {
log.Fatalf("first: execution: %s", err)
}
Вывод:
T0 (second version) invokes T1: (T1 invokes T2: (T2, version B)) T0 (first version) invokes T1: (T1 invokes T2: (T2, version A))
func Must
func Must(t *Template, err error) *Template
Must — это вспомогательная функция, обёртывающая вызов функции, которая возвращает (*Template, error), и вызывающая панику, если ошибка не равна nil. Она предназначена для использования при инициализации переменных, например:
var t = template.Must(template.New("name").Parse("html"))
func New
func New(name string) *Template
New создаёт новый HTML-шаблон с заданным именем.
func ParseFS 1.16
func ParseFS(fs fs.FS, patterns ...string) (*Template, error)
ParseFS подобна ParseFiles или ParseGlob, но читает из файловой системы fs, а не из файловой системы хостовой операционной системы. Она принимает список шаблонов glob. (Обратите внимание, что большинство имён файлов выступают в роли шаблонов glob, соответствующих только самим себе.)
func ParseFiles
func ParseFiles(filenames ...string) (*Template, error)
ParseFiles создаёт новый Template и разбирает определения шаблонов из файлов с указанными именами. Имя возвращённого шаблона будет совпадать с именем (без пути) первого файла, а его содержимое — с разобранным содержимым этого файла. Должен быть указан хотя бы один файл. При возникновении ошибки разбор прекращается, а возвращённый *Template равен nil.
При разборе нескольких файлов с одинаковыми именами в разных каталогах будет использован последний указанный файл. Например, ParseFiles("a/foo", "b/foo") сохраняет "b/foo" как шаблон с именем "foo", а "a/foo" становится недоступным.
func ParseGlob
func ParseGlob(pattern string) (*Template, error)
ParseGlob создаёт новый Template и разбирает определения шаблонов из файлов, найденных по шаблону. Файлы выбираются в соответствии с семантикой filepath.Match; шаблон должен соответствовать хотя бы одному файлу. ParseGlob эквивалентна вызову ParseFiles со списком файлов, найденных по шаблону.
При разборе нескольких файлов с одинаковыми именами в разных каталогах будет использован последний указанный файл.
func (*Template) AddParseTree
func (t *Template) AddParseTree(name string, tree *parse.Tree) (*Template, error)
AddParseTree создаёт новый шаблон с указанными именем и деревом разбора и связывает его с t.
Функция возвращает ошибку, если t или любой связанный с ним шаблон уже был выполнен.
func (*Template) Clone
func (t *Template) Clone() (*Template, error)
Clone возвращает копию шаблона, включая все связанные шаблоны. Фактическое представление не копируется, но копируется пространство имён связанных шаблонов, поэтому последующие вызовы Template.Parse для копии добавят шаблоны к копии, но не к оригиналу. Template.Clone можно использовать для подготовки общих шаблонов и их применения с вариантами определений других шаблонов, добавив эти варианты после создания копии.
Функция возвращает ошибку, если t уже был выполнен.
func (*Template) DefinedTemplates 1.6
func (t *Template) DefinedTemplates() string
DefinedTemplates возвращает строку со списком определённых шаблонов, перед которой стоит строка "; defined templates are: ". Если таких шаблонов нет, возвращается пустая строка. Используется для формирования сообщения об ошибке.
func (*Template) Delims
func (t *Template) Delims(left, right string) *Template
Delims задаёт разделители действий указанными строками для последующих вызовов Template.Parse, ParseFiles или ParseGlob. Вложенные определения шаблонов наследуют эти настройки. Пустой разделитель означает соответствующее значение по умолчанию: {{ или }}. Возвращаемое значение — сам шаблон, поэтому вызовы можно объединять в цепочку.
Пример
Код:
const text = "<<.Greeting>> {{.Name}}"
data := struct {
Greeting string
Name string
}{
Greeting: "Hello",
Name: "Joe",
}
t := template.Must(template.New("tpl").Delims("<<", ">>").Parse(text))
err := t.Execute(os.Stdout, data)
if err != nil {
log.Fatal(err)
}
Вывод:
Hello {{.Name}}
func (*Template) Execute
func (t *Template) Execute(wr io.Writer, data any) error
Execute применяет разобранный шаблон к указанному объекту данных и записывает вывод в wr. Если при выполнении шаблона или записи его вывода возникает ошибка, выполнение прекращается, однако часть результата уже может быть записана в средство записи вывода. Шаблон можно безопасно выполнять параллельно, хотя при совместном использовании одного Writer вывод может перемешиваться.
func (*Template) ExecuteTemplate
func (t *Template) ExecuteTemplate(wr io.Writer, name string, data any) error
ExecuteTemplate применяет связанный с t шаблон с указанным именем к заданному объекту данных и записывает вывод в wr. Если при выполнении шаблона или записи его вывода возникает ошибка, выполнение прекращается, однако часть результата уже может быть записана в средство записи вывода. Шаблон можно безопасно выполнять параллельно, хотя при совместном использовании одного Writer вывод может перемешиваться.
func (*Template) Funcs
func (t *Template) Funcs(funcMap FuncMap) *Template
Funcs добавляет элементы карты аргумента в карту функций шаблона. Любую функцию, используемую в шаблоне, необходимо добавить до разбора шаблона. Funcs можно вызывать несколько раз, в том числе после разбора (например, после Template.Clone), чтобы заменить функцию с тем же именем; замена будет использоваться при выполнении шаблона. Функция вызывает панику, если значение в карте не является функцией с подходящим типом возвращаемого значения. Возвращаемое значение — сам шаблон, поэтому вызовы можно объединять в цепочку.
func (*Template) Lookup
func (t *Template) Lookup(name string) *Template
Lookup возвращает связанный с t шаблон с указанным именем или nil, если такого шаблона нет.
func (*Template) Name
func (t *Template) Name() string
Name возвращает имя шаблона.
func (*Template) New
func (t *Template) New(name string) *Template
New создаёт новый HTML-шаблон, связанный с указанным шаблоном и использующий те же разделители. Эта транзитивная связь позволяет одному шаблону вызывать другой с помощью действия {{template}}.
Если шаблон с указанным именем уже существует, новый HTML-шаблон заменит его. Существующий шаблон будет сброшен и отвязан от t.
func (*Template) Option 1.5
func (t *Template) Option(opt ...string) *Template
Option задаёт параметры шаблона. Параметры описываются строками: либо простой строкой, либо строкой вида "key=value". В строке параметра может быть не более одного знака равенства. Если строка параметра не распознана или содержит другую ошибку, Option вызывает панику.
Известные параметры:
missingkey: управляет поведением при выполнении, если для доступа к элементу карты используется ключ, отсутствующий в карте.
"missingkey=default" or "missingkey=invalid" The default behavior: Do nothing and continue execution. If printed, the result of the index operation is the string "<no value>". "missingkey=zero" The operation returns the zero value for the map type's element. "missingkey=error" Execution stops immediately with an error.
func (*Template) Parse
func (t *Template) Parse(text string) (*Template, error)
Parse разбирает text как тело шаблона для t. Именованные определения шаблонов (инструкции {{define ...}} или {{block ...}}) в text задают дополнительные шаблоны, связанные с t, и удаляются из определения самого t.
Шаблоны можно переопределять в последовательных вызовах Parse до первого вызова Template.Execute для t или любого связанного шаблона. Определение шаблона с телом, содержащим только пробелы и комментарии, считается пустым и не заменяет тело существующего шаблона. Это позволяет использовать Parse для добавления новых именованных определений шаблонов, не перезаписывая основное тело шаблона.
func (*Template) ParseFS 1.16
func (t *Template) ParseFS(fs fs.FS, patterns ...string) (*Template, error)
ParseFS подобна Template.ParseFiles или Template.ParseGlob, но читает из файловой системы fs, а не из файловой системы хостовой операционной системы. Она принимает список шаблонов glob. (Обратите внимание, что большинство имён файлов выступают в роли шаблонов glob, соответствующих только самим себе.)
func (*Template) ParseFiles
func (t *Template) ParseFiles(filenames ...string) (*Template, error)
ParseFiles разбирает файлы с указанными именами и связывает полученные шаблоны с t. При возникновении ошибки разбор прекращается и возвращённый шаблон равен nil; в противном случае возвращается t. Должен быть указан хотя бы один файл.
При разборе нескольких файлов с одинаковыми именами в разных каталогах будет использован последний указанный файл.
ParseFiles возвращает ошибку, если t или любой связанный с ним шаблон уже был выполнен.
func (*Template) ParseGlob
func (t *Template) ParseGlob(pattern string) (*Template, error)
ParseGlob разбирает определения шаблонов в файлах, найденных по шаблону, и связывает полученные шаблоны с t. Файлы выбираются в соответствии с семантикой filepath.Match; шаблон должен соответствовать хотя бы одному файлу. ParseGlob эквивалентна вызову t.ParseFiles со списком файлов, найденных по шаблону.
При разборе нескольких файлов с одинаковыми именами в разных каталогах будет использован последний указанный файл.
ParseGlob возвращает ошибку, если t или любой связанный с ним шаблон уже был выполнен.
func (*Template) Templates
func (t *Template) Templates() []*Template
Templates возвращает срез шаблонов, связанных с t, включая сам t.
type URL
URL содержит заведомо безопасный URL или его фрагмент (см. RFC 3986). URL вида `javascript:checkThatFormNotEditedBeforeLeavingPage()` из доверенного источника можно включать в страницу, но по умолчанию динамические URL `javascript:` фильтруются, поскольку они часто используются для внедрения кода.
Использование этого типа создаёт угрозу безопасности: заключённое в него содержимое должно поступать из доверенного источника, поскольку оно будет включено в вывод шаблона без изменений.
type URL string
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/html/template/
