Package template

import "html/template"
Overview
Index
Examples

Overview ▾

包模板(html / template)实现了数据驱动的模板,以生成可防止代码注入的HTML输出. 它提供与包文本/模板相同的界面,并且只要输出为HTML,就应使用该接口代替文本/模板.

此处的文档重点介绍软件包的安全功能. 有关如何对模板本身进行编程的信息,请参见文本/模板文档.

Introduction

该程序包包装了程序包文本/模板,因此您可以共享其模板API来安全地解析和执行HTML模板.

tmpl, err := template.New("name").Parse(...)
// Error checking elided
err = tmpl.Execute(out, data)

如果成功,则tmpl现在将是注射安全的. 否则,err是文档中为ErrorCode定义的错误.

HTML模板将数据值视为纯文本,应对其进行编码,以便可以将其安全地嵌入HTML文档中. 转义是上下文的,因此动作可以出现在JavaScript,CSS和URI上下文中.

此软件包使用的安全模型假定模板作者受信任,而Execute的data参数不受信任. 下面提供了更多详细信息.

Example

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>")

produces

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, &lt;script&gt;alert(&#39;you have been pwned&#39;)&lt;/script&gt;!

Contexts

该软件包可以理解HTML,CSS,JavaScript和URI. 它为每个简单的操作管道添加了清理功能,因此请摘录

<a href="/search?q={{.}}">{{.}}</a>

在解析时,每个{{.}}都会被覆盖以根据需要添加转义功能. 在这种情况下

<a href="/search?q={{. | urlescaper | attrescaper}}">{{. | htmlescaper}}</a>

其中urlescaper,attrescaper和htmlescaper是内部转义函数的别名.

对于这些内部转义函数,如果操作流水线求值为nil接口值,则将其视为空字符串.

Errors

有关详细信息,请参见ErrorCode文档.

A fuller picture

一读可能会跳过此程序包注释的其余部分; 它包含了解转义上下文和错误消息所必需的详细信息. 大多数用户将不需要了解这些详细信息.

Contexts

假设{{.}}是" O'Reilly:<i>您</ i>?",下表显示了{{.}}在左侧上下文中的显示方式.

Context                          {{.}} After
{{.}}                            O'Reilly: How are &lt;i&gt;you&lt;/i&gt;?
<a title='{{.}}'>                O&#39;Reilly: How are you?
<a href="/{{.}}">                O&#39;Reilly: How are %3ci%3eyou%3c/i%3e?
<a href="?q={{.}}">              O&#39;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

If used in an unsafe context, then the value might be filtered out:

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上下文中.

Typed Strings

默认情况下,此程序包假定所有管道均生成纯文本字符串. 它添加了转义管道阶段,以正确,安全地在适当的上下文中嵌入该纯文本字符串.

当数据值不是纯文本时,可以通过将其标记为类型来确保它不会被过度转义.

来自content.go的HTML,JS,URL等类型可以携带安全的内容,这些内容可以免于转义.

模板

Hello, {{.}}!

可以用

tmpl.Execute(out, template.HTML(`<b>World</b>`))

生产

Hello, <b>World</b>!

而不是

Hello, &lt;b&gt;World&lt;b&gt;!

如果{{.}}是常规字符串,则会生成该字符串.

Security Model

https://rawgit.com/mikesamuel/sanitized-jquery-templates/trunk/safetemplate.html#problem_definition定义此包使用的"安全".

该程序包假定模板作者是受信任的,而不是Execute的data参数,并试图在面对不受信任的数据时保留以下属性:

结构保留属性:" ...当模板作者以安全的模板语言编写HTML标记时,浏览器会将输出的相应部分解释为标记,而不管不受信任的数据的值如何,对于其他结构,例如属性边界以及JS和CSS字符串边界."

代码效果属性:" ...将模板输出注入页面后,才应运行模板作者指定的代码,而模板作者所指定的所有代码均应运行.

最不惊讶的特性:"熟悉HTML,CSS和JavaScript的开发人员(或代码审阅者)知道上下文自动转义的发生,应该能够查看{{.}}并正确推断发生了什么消毒."

Example

<!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>

示例(自动转义)

Hello, &lt;script&gt;alert(&#39;you have been pwned&#39;)&lt;/script&gt;!

示例(转义)

&#34;Fran &amp; Freddie&#39;s Diner&#34; &lt;tasty@example.com&gt;
&#34;Fran &amp; Freddie&#39;s Diner&#34; &lt;tasty@example.com&gt;
&#34;Fran &amp; Freddie&#39;s Diner&#34;32&lt;tasty@example.com&gt;
\"Fran & Freddie\'s Diner\" \x3Ctasty@example.com\x3E
\"Fran & Freddie\'s Diner\" \x3Ctasty@example.com\x3E
\"Fran & Freddie\'s Diner\"32\x3Ctasty@example.com\x3E
%22Fran+%26+Freddie%27s+Diner%2232%3Ctasty%40example.com%3E

Index ▾

func HTMLEscape(w io.Writer, b []byte)
func HTMLEscapeString(s string) string
func HTMLEscaper(args ...interface{}) string
func IsTrue(val interface{}) (truth, ok bool)
func JSEscape(w io.Writer, b []byte)
func JSEscapeString(s string) string
func JSEscaper(args ...interface{}) string
func URLQueryEscaper(args ...interface{}) string
type CSS
type Error
    func (e *Error) Error() string
type ErrorCode
type FuncMap
type HTML
type HTMLAttr
type JS
type JSStr
type Srcset
type Template
    func Must(t *Template, err error) *Template
    func New(name string) *Template
    func ParseFiles(filenames ...string) (*Template, error)
    func ParseGlob(pattern string) (*Template, error)
    func (t *Template) AddParseTree(name string, tree *parse.Tree) (*Template, error)
    func (t *Template) Clone() (*Template, error)
    func (t *Template) DefinedTemplates() string
    func (t *Template) Delims(left, right string) *Template
    func (t *Template) Execute(wr io.Writer, data interface{}) error
    func (t *Template) ExecuteTemplate(wr io.Writer, name string, data interface{}) error
    func (t *Template) Funcs(funcMap FuncMap) *Template
    func (t *Template) Lookup(name string) *Template
    func (t *Template) Name() string
    func (t *Template) New(name string) *Template
    func (t *Template) Option(opt ...string) *Template
    func (t *Template) Parse(text string) (*Template, error)
    func (t *Template) ParseFiles(filenames ...string) (*Template, error)
    func (t *Template) ParseGlob(pattern string) (*Template, error)
    func (t *Template) Templates() []*Template
type URL

Package files

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将等同于纯文本数据b的转义HTML写入w.

func HTMLEscapeString

func HTMLEscapeString(s string) string

HTMLEscapeString返回等效于纯文本数据s的转义HTML.

func HTMLEscaper

func HTMLEscaper(args ...interface{}) string

HTMLEscaper返回与其参数的文本表示形式等效的转义HTML.

func IsTrue 1.6

func IsTrue(val interface{}) (truth, ok bool)

IsTrue报告值是否为" true"(不是其类型的零),以及该值是否具有有意义的真值. 这是if和其他此类操作使用的真相定义.

func JSEscape

func JSEscape(w io.Writer, b []byte)

JSEscape将等同于纯文本数据b的转义JavaScript写入w.

func JSEscapeString

func JSEscapeString(s string) string

JSEscapeString返回等效于纯文本数据s的转义JavaScript.

func JSEscaper

func JSEscaper(args ...interface{}) string

JSEscaper返回等效于其参数的文本表示形式的转义JavaScript.

func URLQueryEscaper

func URLQueryEscaper(args ...interface{}) string

URLQueryEscaper以适合嵌入URL查询的形式返回其参数的文本表示形式的转义值.

type CSS

CSS封装了符合以下条件的已知安全内容:

1. The CSS3 stylesheet production, such as `p { color: purple }`.
2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
3. CSS3 declaration productions, such as `color: red; margin: 2px`.
4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.

See https://www.w3.org/TR/css3-syntax/#parsing and https://web.archive.org/web/20090211114933/http://w3.org/TR/css3-syntax#style

使用此类型会带来安全风险:封装的内容应来自受信任的来源,因为它将逐字包含在模板输出中.

type CSS string

type 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:...`

Discussion:

"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"
    // Example:
    //   {{if .C}}<a href="{{end}}{{.X}}
    // Discussion:
    //   Package html/template statically examines each path through an
    //   {{if}}, {{range}}, or {{with}} to escape any following pipelines.
    //   The 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 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
)

type FuncMap

FuncMap是定义从名称到函数的映射的映射类型. 每个函数必须具有单个返回值,或者具有两个返回值,其中第二个具有类型错误. 在这种情况下,如果第二个(错误)参数在执行过程中评估为非零,则执行终止,并且Execute返回该错误. FuncMap在"文本/模板"中具有与FuncMap相同的基本类型,此处已复制到此处,因此客户端无需导入"文本/模板".

type FuncMap map[string]interface{}

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']()"之类的表达式时,不存在语句/表达式的歧义.既是有效的表达式,也是含义完全不同的有效程序.

Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.

使用JS包含有效但不受信任的JSON是不安全的. 一种安全的选择是使用json.Unmarshal解析JSON,然后将结果对象传递到模板中,在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

模板是"文本/模板"中的专用模板,可生成安全的HTML文档片段.

type Template struct {

    // The underlying template's parse tree, updated to be HTML-safe.
    Tree *parse.Tree // Go 1.2
    // contains filtered or unexported fields
}

示例(块)

Names:
- Gamora
- Groot
- Nebula
- Rocket
- Star-Lord
Names: Gamora, Groot, Nebula, Rocket, Star-Lord

示例(全局)

在这里,我们演示了从目录加载一组模板.

T0 invokes T1: (T1 invokes T2: (This is T2))

Example (Helpers)

此示例演示了一种共享模板并在不同上下文中使用它们的方法. 在此变体中,我们将多个驱动程序模板手动添加到现有的模板包中.

Driver 1 calls T1: (T1 invokes T2: (This is T2))
Driver 2 calls T2: (This is T2)

示例(解析文件)

在这里,我们演示了从不同目录中的文件加载一组模板

T1 invokes T2: (This is T2)

示例(分享)

本示例演示如何将一组驱动程序模板与不同的帮助程序模板集一起使用.

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,错误),如果错误为非nil,则会出现恐慌. 它旨在用于变量初始化,例如

var t = template.Must(template.New("name").Parse("html"))

func New

func New(name string) *Template

New使用给定名称分配新的HTML模板.

func ParseFiles

func ParseFiles(filenames ...string) (*Template, error)

ParseFiles创建一个新的模板,并从命名文件中解析模板定义. 返回的模板名称将具有第一个文件的(基本)名称和(解析的)内容. 必须至少有一个文件. 如果发生错误,解析将停止并且返回的* Template为nil.

当在不同目录中解析具有相同名称的多个文件时,最后提到的将是结果文件. 例如,ParseFiles(" a / foo"," b / foo")将" b / foo"存储为名为" foo"的模板,而" a / foo"不可用.

func ParseGlob

func ParseGlob(pattern string) (*Template, error)

ParseGlob创建一个新的模板,并从该模式标识的文件中解析模板定义. 这些文件根据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)

克隆返回模板的副本,包括所有关联的模板. 不会复制实际的表示形式,但是会复制关联模板的名称空间,因此在副本中进一步调用Parse会将模板添加到副本中,而不是原始模板. 克隆可用于准备通用模板,并将其与其他模板的变体定义一起使用,方法是在克隆完成后添加变体.

It returns an error if t has already been executed.

func (*Template) DefinedTemplates 1.6

func (t *Template) DefinedTemplates() string

DefinedTemplates返回一个字符串,该字符串列出了已定义的模板,并以字符串";"作为前缀. 如果没有,则返回空字符串. 用于生成错误消息.

func (*Template) Delims

func (t *Template) Delims(left, right string) *Template

Delims将动作定界符设置为指定的字符串,以在后续对Parse,ParseFiles或ParseGlob的调用中使用. 嵌套模板定义将继承设置. 空分隔符代表相应的默认值:{{或}}. 返回值是模板,因此可以链接调用.

Example

Hello {{.Name}}

func (*Template) Execute

func (t *Template) Execute(wr io.Writer, data interface{}) error

Execute将已解析的模板应用于指定的数据对象,并将输出写入wr. 如果执行模板或写入其输出时发生错误,则执行将停止,但是可能已将部分结果写入输出写入器. 模板可以安全地并行执行,尽管如果并行执行共享一个Writer,则输出可能会交错.

func (*Template) ExecuteTemplate

func (t *Template) ExecuteTemplate(wr io.Writer, name string, data interface{}) error

ExecuteTemplate将与具有给定名称的t关联的模板应用于指定的数据对象,并将输出写入wr. 如果执行模板或写入其输出时发生错误,则执行将停止,但是可能已将部分结果写入输出写入器. 模板可以安全地并行执行,尽管如果并行执行共享一个Writer,则输出可能会交错.

func (*Template) Funcs

func (t *Template) Funcs(funcMap FuncMap) *Template

Funcs将参数映射的元素添加到模板的功能映射. 必须在解析模板之前调用它. 如果映射中的值不是具有适当返回类型的函数,则会发生恐慌. 但是,覆盖地图的元素是合法的. 返回值是模板,因此可以链接调用.

func (*Template) Lookup

func (t *Template) Lookup(name string) *Template

查找将返回具有与t关联的给定名称的模板,如果没有这样的模板,则返回nil.

func (*Template) Name

func (t *Template) Name() string

名称返回模板的名称.

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

选项设置模板的选项. 选项由字符串(简单字符串或"键=值")描述. 选项字符串中最多可以有一个等号. 如果选项字符串无法识别或无效,则选项会出现紧急情况.

已知选项:

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)

解析将文本解析为t的模板主体. 文本中的命名模板定义({{define ...}}或{{block ...}}语句)定义了与t关联的其他模板,并从t本身的定义中删除.

在首次使用Execute on t或任何相关模板之前,可以在对Parse的连续调用中重新定义模板. 具有仅包含空白和注释的主体的模板定义被认为是空的,不会替换现有模板的主体. 这允许使用Parse添加新的命名模板定义,而不会覆盖主模板主体.

func (*Template) ParseFiles

func (t *Template) ParseFiles(filenames ...string) (*Template, error)

ParseFiles解析命名的文件,并将生成的模板与t关联. 如果发生错误,则分析停止,返回的模板为nil; 否则为t. 必须至少有一个文件.

当在不同目录中解析具有相同名称的多个文件时,最后提到的将是结果文件.

如果t或任何关联的模板已经执行,则ParseFiles返回错误.

func (*Template) ParseGlob

func (t *Template) ParseGlob(pattern string) (*Template, error)

ParseGlob解析由模式标识的文件中的模板定义,并将结果模板与t关联. 这些文件根据filepath.Match的语义进行匹配,并且该模式必须匹配至少一个文件. ParseGlob等效于使用模式匹配的文件列表调用t.ParseFiles.

当在不同目录中解析具有相同名称的多个文件时,最后提到的将是结果文件.

如果t或任何关联的模板已经执行,则ParseGlob返回错误.

func (*Template) Templates

func (t *Template) Templates() []*Template

模板返回与t关联的模板的一部分,包括t本身.

type URL

URL封装了一个已知的安全URL或URL子字符串(请参阅RFC 3986). 来自受信任来源的URL,例如" javascript:checkThatFormNotEditedBeforeLeavingPage()",应该放在页面中,但是默认情况下,动态Javascript URL被过滤掉,因为它们是经常被利用的注入向量.

使用此类型会带来安全风险:封装的内容应来自受信任的来源,因为它将逐字包含在模板输出中.

type URL string

by  ICOPY.SITE