跳转到内容

帮助:模板

This page is semi-protected.
来自维基教科书,开放世界中的开放书籍

一个模板只是一个为包含在其他页面上而设计的页面。如果模板发生更改,这通常会反映在使用该模板的每个页面上。正如您可能开始想象的那样,模板是一个强大的工具,如果使用得当,可以减少工作量并提高可维护性。在本页中,您将学习如何使用模板以及如何制作自己的模板。

模板 B 可以包含在页面 A、P 和 Q 上以显示其内容。更新模板将改变使用它的页面上显示的内容。


概述

模板可能包含任何所需的维基文本,包括对其他模板的调用。它们具有一些有限的编程能力:可自定义的值(称为参数)、计算和分支(使用解析器函数)以及访问维基特定的变量,例如日期、时间和页面名称。

要在页面中使用模板,模板标签(形式为{{模板名称}},即包含在双花括号中的模板名称)将添加到您希望模板出现的位置。当读者想要查看页面时,服务器会获取模板页面的内容,处理与页面相关的任何变量,并将结果显示在模板标签的位置。

模板对于任何希望在两个或多个页面中复制的文本很有用,并且不需要独立编辑每个副本以适应它所在的页面。由于可以使用参数,版本在一定程度上甚至可能有所不同,并且可以独立编辑每个参数值。模板不仅方便,而且还可以“强制”有用的统一性,例如,某种“样式”。

典型应用是

  • 消息 用于显示信息 ({{split}})
  • 导航 在书籍的页面或章节之间,以便在线更容易阅读 ({{chapter navigation}})
  • 用于显示视觉信息的占位符。例如表格、图形、图表、插图等。
  • 由显示更复杂想法的简单图像表组成的复合材料 ({{chess diagram}}

模板页面和命名空间

模板有自己的命名空间,它使用前缀“Template:”(类似于熟悉的“User:”、“Help:”和“Talk:”命名空间)。

大多数模板存在于模板命名空间中,因此可以在标题为“Template:模板名称”的页面上找到。但是,有时用户会在其他命名空间(例如 User: 命名空间)中创建模板。模板的正常使用(称为转包容)可以在任何命名空间中进行,但模板命名空间的优势在于转包容时不需要“Template:”前缀。相比之下,为了从除了主命名空间(书籍所在的命名空间)之外的任何其他命名空间转包容内容,需要完整的名称,包括命名空间前缀。如果从主命名空间转包容(这很少见),则必须在模板语法中添加冒号,否则软件会将代码视为未创建的模板。因此

命名空间 编码示例 结果
模板 {{模板名称}} 模板内容的转包容
模板外部和主命名空间 {{Wikibooks talk:页面名称}} 页面内容的转包容
主命名空间 {{:书籍标题}} 书籍内容的转包容
没有冒号的主命名空间 {{书籍标题}} 红链接 到未创建的模板

模板名称与其他页面名称完全相同:区分大小写,除了第一个字母外,空格与下划线不可区分。如果符号 #(通常用于链接到页面的部分)出现在花括号内,那么它以及跟随它的任何字符都将被忽略。

模板页面,就像大多数其他页面一样,有与其相关的讨论页面,编辑人员可以在那里讨论与模板相关的任何问题。(因此,模板不应放在“Talk:”命名空间中,即使它们是为在讨论页面上使用而设计的;因为讨论页面本身没有讨论页面,所以将没有页面来讨论模板。)

模板用法

要将模板转包容到另一个页面,请使用以下语法(称为模板标签

{{ 模板名称 | 参数 | 参数 | ... }}

这包括模板名称和传递给模板的各种参数,其中每个参数由一个竖线(或管道)分隔,并且整体由双花括号 {{...}} 包围。模板标签应放置在要显示模板的页面上的任何位置。“Template:”前缀永远不需要用于转包容,只需要用于查找和编辑模板本身(尽管如果模板是在不同的命名空间中创建的,则需要该前缀)。并非所有模板都有参数,并非所有具有参数的模板都需要提供值,因此有时 {{模板名称}} 就足以使用模板。如果需要参数,但用户未提供值,则模板可能会呈现为 {{{...}}} 在文本中,其中“...”可能是数字或参数名称。这是为了告知用户缺少命名参数或无名参数,可以通过使用参数默认值 来避免这种情况。

参数有两种基本形式

  • 无名参数(有时称为“位置”参数):按其出现的顺序放入模板中的值
    {{模板名称|参数 1|参数 2|... }}
  • 命名参数:与模板中特定命名键关联的值
    {{模板名称| 参数名称 1 = 参数 1 | 参数名称 2 = 参数 2 | ... }}

这些可以混合使用

{{模板名称|参数 1|参数 2| 参数名称 1 = 参数 3 | 参数名称 2 = 参数 4 | ... }}

按照惯例,命名参数列在最后,但这并不是必需的。空白字符(空格、制表符、回车符)将从命名参数值的开头和结尾剥离(无名参数不受影响),但不会从中间剥离:因此 {{ ... | myparam = this is a test }} 将被视为用户输入了 {{ ... |myparam=this is a test}}。

模板页面本身可能包含在转包容模板时不会被转包容的材料(例如模板本身所属的文档或分类),或者在转包容页面时使用的材料(例如分类,适用于转包容页面,但不适用于模板)。请参阅以下对includeonlynoinclude 标签的讨论。

尝试转包容不存在的模板会产生红链接,就像链接到任何其他不存在的页面一样。遵循链接允许用户创建该特定模板。

基本模板用法示例

如果您想尝试使用这些示例中的任何一个,请使用模板沙盒

没有参数的模板

要查看一个非常简单的模板示例,请查看Template:Tc。此模板只是将字母“in”转入其他页面。例如,将以下短语编辑到任何页面将产生相关的结果

使用模板 {{tc}}
描述 输入文本 处理后的结果
{{Tc}} 自身 {{tc}} in
{{tc}} 的单次使用 {{tc}} 2009年,随着巴拉克·奥巴马入主白宫,我们发现... in 2009, with Barack Obama settling into the White House, we find the beginning of...
{{tc}} 的多次使用 {{tc}} 2009年,随着巴拉克·奥巴马 settl{{tc}}g {{tc}}to the White House, we f{{tc}}d the beg{{tc}}n{{tc}}g of... in 2009, with Barack Obama settling into the White House, we find the beginning of...

您会注意到,尽管模板页面上的说明文字(“此模板用于...”单击上面的模板链接查看),但模板在转入时只包含字母“in”。如果编辑模板页面(单击此链接),您会看到除了字母“in”之外的所有内容都包含在“noinclude”标签中,稍后将讨论。

带有未命名参数的模板

使用参数进行转入只稍微复杂一些。为了便于说明,著名的dead man's hand 可以通过以下模板使用未命名的参数来复制

制作死人手牌
描述 输入文本 处理后的结果
使用三个模板(Template:ClubsTemplate:DiamondsTemplate:Spades {{clubs|A}} {{clubs|8}} {{spades|A}} {{spades|8}} {{diamonds|9}} A 8 A 8 9
使用(Template:BridgeHandInline);不太漂亮,但只有一个模板,有四个参数。 {{BridgeHandInline|A8||9|A8}} ♠A8 9 ♣A8
使用(Template:BridgeHandInline),但缺少“管道”分隔符 {{BridgeHandInline|A8|9|A8}} ♠A8 9 A8 ♣{{{4}}}

在第二个示例中,模板标签中参数的位置决定了它属于哪个花色。因此,第一个 A8(第一个位置)属于黑桃,空位置(第二个位置)属于红心,9(第三个位置)属于方块,第二个 A8(第四个位置)属于梅花。请注意,空参数位置会被计算在内;如果忘记了额外的管道,如第三个示例所示,结果是卡片会出现在错误的位置,并且会显示 {{{4}}},这意味着模板正在等待第四个位置参数的值,但没有提供。

带有命名参数的模板

使用命名参数类似于使用未命名参数。例如,Template:Payoff matrix(用于某些关于博弈论的书籍)使用 UL、UR、DL 和 DR 来表示左上、右上、左下和右下,并使用 Name 参数在矩阵底部添加名称,从而提供了一个简单的 2x2 网格,并具有可调整的值。

描述 代码 结果
收益矩阵 {{payoff matrix | UL = 5 | UR = 7 | DL = 2 | DR = 9 | Name = Example usage }}
5 7
2 9
Example usage
显示缺失参数的默认值和不同顺序的收益矩阵 {{payoff matrix | DR = 9 | Name = Example usage | DL = 2 | UR = 7 }}
0, 0 7
2 9
Example usage

在第二种情况下,参数的顺序已更改,但结果未改变——这是命名参数相对于未命名参数的优势之一——并且其中一个值(UL)已被完全删除,允许模板插入默认值“0, 0”。

参数名称区分大小写,即使是第一个字符也是如此。例如,使用“dr = 9”“Dr = 9”“dR = 9” 代替 “DR = 9” 将导致右下单元格显示默认值“0, 0”。大小写不同的版本被视为不同的参数,会被模板忽略。

替换

通常,当用户浏览页面时,模板会被处理成可读的文本。这是模板的正常目的:由于模板每次使用时都会重新计算,因此模板的更改可以快速轻松地传播到许多页面。但是,在某些情况下,这并不合适。例如,用户可能希望使用一个模板返回一个固定日期或时间,而不是每次浏览页面时都发生变化。对于这些情况,可以使用替换,方法是在模板标签中添加subst:,并在模板名称之前。替换正是其名称所暗示的那样:不是每次浏览页面时都处理模板,而是替换在保存编辑时处理模板,并将模板标签替换为处理后的结果。

例如,模板 {{tc}}(如上所示)会在任何放置它的地方添加字母“in”。因此,维基文本 bra{{tc}} 将产生单词 brain。但是,维基文本将始终保持为 bra{{tc}},因此,如果 {{tc}} 被更改为添加字母“wn”,维基文本将产生 brawn 而不是 brain。像这样进行替换——bra{{subst:tc}}——将永久更改维基文本以读取 brain,以后对模板 {{tc}} 的更改将不会影响替换后的文本。

常见错误

URL 问题

URL 可以包含等号(=),例如 http://some.page.org?key=value&key2=value2。但是,模板参数列表中的第一个等号始终被视为设置一个命名的模板参数。因此,{{some template|http://some.page.org?key=value&key2=value2}} 将被视为 http://some.page.org?key 是一个参数名称,而不是 URL 的开始。解决此问题有两种方法

  • 使用显式的位置参数引用:{{some template|1=http://some.page.org?key=value&key2=value2}}。'1=' 明确地引用第一个位置参数,并将消除后续的等号
  • 使用特殊模板 {{=}}:{{some template|http://some.page.org?key{{=}}value&key{{=}}value2}}。此模板返回一个不被维基软件解析或解释的等号。

空白问题

命名 参数会自动去除参数中的空白——空格、制表符、回车符和换行符,或其他不可见字符。未命名 参数将保留所有空白。这会导致意外的格式问题,因为预期行为不符。

垂直管道问题

垂直管道字符 (|) 用于模板(和解析器函数)中以分隔参数。如果您需要向模板参数提供管道字符,则使用特殊模板 {{!}},它返回一个未解析的管道字符,或者使用HTML 实体 | 表示管道字符。

创建和编辑模板

模板的创建和编辑方式与其他页面类似:选择一个合适的名称,导航到该页面,然后单击“编辑”选项卡或根据需要创建新页面。唯一的真正区别是,模板通常放在“Template:”命名空间中,而不是(没有前缀的)主命名空间中。任何可以在普通页面上包含的内容都可以包含在模板中,包括其他模板。除此之外,模板还可以访问编程功能——参数解析器函数变量——这些功能允许根据上下文进行使用,以及帮助控制哪些信息被转入,哪些信息不被转入的特殊标签。

创建模板时,最好遵循以下几个简单的原则

  • 选择一个简短、描述性的名称。有些人建议通用的模板名称全部使用小写字母,而特定书籍的模板名称使用 Template:Book Name/Template Name 的形式,但目前还没有硬性规定。
  • 快速搜索 模板空间或浏览模板 以确保您要创建的模板尚未存在。有时,增强现有模板比从头开始创建新模板更容易更好。
  • 确保您的模板已正确记录并在正确的类别中。 (见下文)
  • 尽量使您的模板模块化:即能够独立存在并适应各种不同的页面环境,不会出错、产生不良输出或影响页面的布局。一般来说,您希望您的模板对其他编辑者透明有效——他们需要投入的精力越多来理解如何使用您的模板,他们就越不愿意使用它。

模板文档

对您的模板进行分类和记录将使其他编辑更容易找到和使用它。

  • 要添加文档,将 {{documentation}} 模板放在模板页面上的“noinclude”标签中。这将创建一个文档子页面,您可以对其进行编辑
  • 适用于模板本身的类别应添加到模板页面(在“noinclude”标签中,使用 {{documentation}} 模板)。应转入到转入页面的类别应放在模板页面上的“includeonly”标签中。

参数

参数是允许将维基文本馈送到模板的特殊代码;可以构造模板以根据接收到的参数值产生不同的结果。参数可以有名称,也可以通过模板标签中提供的值的顺序来引用(模板代码中参数的顺序无关紧要)。模板中的参数采用 {{{...}}} 的形式,其中三重的花括号包围着命名参数的名称或位置参数的编号。输入的参数值可以很长,如果需要,可以将整个页面的转入用作参数的值。

为了了解参数的工作原理,请考虑以下示例。假设有一个名为“peoplepets”的模板,它产生一些关于人和宠物的文本。此模板的模板标签可能如下所示

A. {{ peoplepets | John | Mary | age = 6 | Fido | small | kind = dog }}
B. {{ peoplepets | Bill | Susan | age = 7 | Queenie | fat | kind = cat }}

模板本身的内容,位于页面 Template:Peoplepets 上,如下所示

{{{1}}}{{{2}}} 拥有一只 {{{4}}} {{{kind}}},名叫 {{{3}}},它今年 {{{age}}} 岁。

因此,上面的两个模板标签将分别转入以下文本。

A. 约翰和玛丽养了一只名叫菲多的小狗,它今年 6 岁。
B. 比尔和苏珊养了一只名叫奎妮的肥猫,它今年 7 岁。

注意事项

  • 位置参数的编号会跳过命名参数(例如上面的 "age")。
  • 模板标签中命名参数的值前后边的空格会被模板移除。
    • 这并不适用于未命名的参数,它们会保留前后边的空格。但是,浏览器会将多个空格字符渲染为一个空格,因此 "菲多"、"肥" 和其他未命名参数值周围的额外空格并不明显。如果未命名参数用于显示之外的其他用途(例如链接),这可能会造成混淆。
  • 命名参数值在模板中使用的顺序无关紧要。
  • 位置参数的编号被视为名称:{{ peoplepets | John | ... }} 可以写成 {{ peoplepets | 1 = John | ... }}。这在需要按不同顺序输入位置参数或位置参数值包含等号时非常有用。
  • 值可以为空。这里第二个位置参数和 "age" 参数的值为空。
    模板标签:{{ peoplepets | John || age = | Fido | small | kind = dog }}
    产生(注意缺少的单词):约翰和 拥有一只小狗,名叫菲多,它 岁。
  • 值可以保持未提供。这里 "kind" 参数被省略了。
    模板标签:{{ peoplepets | John | Mary | age = 6 | Fido | small }}
    产生(这会显示缺少的参数):约翰和玛丽 拥有一只小 {{{kind}}},名叫菲多,它 6 岁。

参数默认值

可以使用竖线字符 (|) 为参数指定默认值。上面的示例模板可以改写如下(其中 "friend" 是位置参数 2 的默认值,第 4 个位置参数默认为空,宠物的 "kind" 默认为 "dog"——参见 模板:Peoplepetsd)。

{{{1}}}{{{2|friend}}} 拥有一只 {{{4|}}} {{{kind|dog}}},名叫 {{{3}}},它今年 {{{age}}} 岁。

像下面这样的模板标签:{{ peoplepetsd | Bill | age = 7 | 3=Queenie }} 就会产生短语 "比尔和朋友拥有一只名叫奎妮的狗,它 7 岁"。

注意,在狗的名字前面需要加上 "3=",因为没有指定第二个位置参数。

参数的空值将覆盖默认值,产生一个空空格。换句话说,{{ peoplepetsd | Bill || kind=| age = 7 | 3=Queenie }} 就会产生短语 "比尔和 拥有一只 名叫奎妮的,它 7 岁"。

虚拟参数和标签布局

如果模板标签提供了模板中未使用的参数,则会忽略这些参数。这样做是为了防止模板在更改后删除参数时,转入内容出现问题;没有必要到每个转入模板的页面上去修改标签。然而,这样做还有额外的好处,可以使一些模板标签更易读,通过空格或添加注释。使用 {{t3d}}。

虚拟参数
描述 输入文本 结果
使用模板 {{t3d}} 添加注释
{{t3d |a|b|c| row 1
      |d|e|f| row 2
      |g|h|i| row 3
}}
a b c

d e f
g h i

由于 {{t3d}} 不使用参数 {{{4}}}{{{8}}}{{{12}}},因此 "行号" 值对产生的维基文本没有影响。虚拟命名参数可以在任何模板标签中使用;只需选择一个未使用的参数名称,并将其作为 "unusedname = value" 添加到标签中。命名虚拟参数的一种特殊情况是使用空字符串作为参数名称。

参数和参数值的限制

  • 未命名的参数不能分配包含等号 (=) 的值;解析器会将等号视为命名参数的赋值。有多种间接方法可以解决此限制。
    • 在模板中,将值写为未定义参数的默认值。
      • {{{0}}},其中省略号可以是未使用的位置参数的编号,也可以是空字符串(空参数)。
    • 在页面中,使用以下方法之一将值分配给模板参数。
      • {{templatename| 1= a=b }},其中 "1=" 符号明确命名了第一个未命名的参数。
      • 使用特殊模板 {{=}},例如,{{template name| a{{=}}b }}。
      • 使用等号的 HTML 实体:=。这仅适用于文本表示;如果等号需要被处理为实际的等号(如在另一个模板中),这种方法将不起作用。
  • 参数值不能包含竖线字符 (|);解析器会将竖线字符视为分隔符而不是文本。竖线可以在维基链接(country=[[United States|USA]]) 或嵌套模板(例如,volume= {{convert|30|acre.ft|m3}})中使用。解决此限制的间接方法如下。
    • 使用特殊模板 {{!}},它会返回一个有效的竖线字符。如果需要将某个东西读作实际的竖线字符(例如,如果正在使用参数修改维基文本表格的结构),请使用这种方法。
    • 使用竖线的 HTML 实体:|。这仅适用于文本表示;如果竖线需要被处理为实际的竖线,这种方法将不起作用。
  • 参数值不能包含不匹配的连续花括号 - }} 或 {{。解析器会尝试将它们解析为模板标签或参数的开头或结尾,并在某处抛出错误。但是,参数可以包含其他参数、魔术词或模板标签。
    • 同样,可以使用 "nowiki" 标签或 HTML 实体来解决这个问题。

嵌套模板

模板可以包含其他模板——通常称为 "嵌套"。在处理模板时,任何嵌套模板产生的维基文本都会被转入到嵌套模板中,因此最终产品实际上是从最深层嵌套的模板开始处理的。虽然在应用中相当简单,但它涉及一些值得注意的怪癖和技巧。

要将参数值传递给嵌套模板,请将参数标签作为嵌套模板参数之一的值放置。

  • 示例
    • 模板:A 包含 "the quick brown {{B|{{{3}}} }} jumped over..."。这会将传递给模板:A 的第三个位置参数的值作为模板:B 的第一个位置参数传递,然后将 B 产生的维基文本作为短语的一部分返回。
    • 模板:A 包含 "the quick brown {{B|waldo={{{3}}} jumped over..."。如上所述,但将模板:A 的第三个位置参数传递给模板:B 的命名参数 "waldo"。

模板可以调用自身,但会在一轮后停止,以防止无限循环。

Noinclude、includeonly 和 onlyinclude

有多个标签可用于控制从模板中转入什么内容,以及不转入什么内容。这三个标签分别是 noinclude、includeonly 和 onlyinclude。

noinclude

"noinclude" 标签用于防止模板页面上的文本被转入到其他页面。这通常用于

  • 文档
  • 应用于模板本身的分类
  • 跨维基链接 到其他维基上的相关模板。

它的使用很简单

如果这段文本在模板页面中,这部分会被转入
<noinclude>但这段文本不会被转入</noinclude>

includeonly

"includeonly" 标签与 "noinclude" 标签相反。includeonly 块中的文本仅在页面被转入时才会被包含,它不会出现在模板页面本身。这经常用于

  • 应用于转入页面的分类
  • 隐藏模板页面本身出现的混乱文本或错误消息(通常是因为需要值的参数未定义)。

它的使用很简单

如果这段文本在模板页面中,这部分会出现在模板页面和转入页面
<includeonly>但这段文本只会出现在转入页面</includeonly>

onlyinclude

"onlyinclude" 标签只包含标签之间的内容;页面上的其他任何内容——即使是 "includeonly" 标签中的文本——都会出现在模板页面上,但不会被包含。这并不经常使用,但可能在需要转入一个大页面中间一小段文本时有用。

它像这样使用

如果这段文本在模板页面中,这部分会在那里可见,但不会被转入
<includeonly>这段文本在模板页面上不可见,也不会被转入</includeonly>
<onlyinclude>这部分文本是唯一会被转入的</onlyinclude>

变量

系统变量采用 {{...}} 格式,其中包含的文本始终全部大写。这些变量直接从系统本身提供信息:本地日期和时间、有关当前页面的信息,甚至有关维基本身的信息。

系统变量示例
描述 输入文本 结果(对于此帮助页面)
页面名称 {{PAGENAME}}
{{FULLPAGENAME}}
模板
帮助:模板
当前命名空间的名称 {{NAMESPACE}} 帮助
注册用户数量 {{NUMBEROFUSERS}} 3,477,764
上次修订的时间戳 {{REVISIONTIMESTAMP}} 20211117190007

PAGENAME 和 NAMESPACE 变量特别有用,而且经常使用,用于根据上下文更改模板行为。例如,如果模板包含一个 分类(例如清理模板,它将页面分类为需要清理的页面),它通常会检查 NAMESPACE 变量,以确保讨论页面、用户页面或标签可能意外放置的任何地方都不会被归类为需要清理的页面。

解析器函数和模块

解析函数是用于执行简单分支和文本操作的工具。它们接受一个或多个参数,并根据参数返回一个维基文本值。解析函数有两种基本形式(区别在于左括号后面是否跟着井号)

  • 核心解析函数,格式为 {{functionName: parameter | parameter | ... }}。
  • 来自软件扩展的解析函数,格式为 {{#functionName: parameter | parameter | ... }}。

解析函数主要用于评估 参数变量,以便在不同的上下文中产生不同的结果。

核心解析函数通常处理文本操作和特定项目任务。

核心解析函数示例
描述 输入文本 结果
将文本转换为大写 {{uc: Heavens to BETSY! }} HEAVENS TO BETSY!
将文本转换为小写 {{lc: Heavens to BETSY! }} heavens to betsy!
获取命名空间名称 {{NS: 1 }} 讨论
获取维基教科书 URL {{fullurl: pagename }} //wikibooks.cn/wiki/Pagename

扩展功能提供了更多面向编程的解析函数。

扩展解析函数示例
描述 输入文本 结果
在选项之间进行测试 {{#ifeq: yes | yes | Hooray...! | Darn...! }}
{{#ifeq: yes | no | Hooray...! | Darn...! }}
Hooray...!
Darn...!
测试参数是否已设置 {{#if: {{{param|}}} | Hooray...! | Darn...! }} Darn...!
进行计算 {{#expr: ( 27 * 46 / pi ) round 2 }} 395.34

其他类型的计算和字符串操作函数,如查找和替换,可以通过 模块:字符串其他模块 执行。这些模块也同样接受一个或多个参数。

使用 模块:字符串 进行字符串替换的示例
描述 输入文本 结果
字符串替换 {{#invoke:String|replace| 90 degrees | degrees | ° }} 90 °

其他编辑信息

  • 如果模板的第一个包含字符是维基标记字符中的一个 :;*#,那么它将被处理为好像它位于一行的开头(即使模板标签不在正确的位置)。这允许在模板中创建各种类型的列表,其中模板可能并不总是在列表的正确位置。为了避免这种效果,请使用<nowiki>#</nowiki>或一个 HTML 实体,例如&#58;对于冒号。这对于与定义 列表 结合使用也很有用。
  • 当一个名为转录的页面是一个重定向页面时,将包含重定向目标。

包含模板的页面的修订历史

存储在 页面历史记录 中的页面由维基文本组成,其中可能包含对模板和图像的引用。当查看页面的旧版本时,这些引用会指向模板和图像的当前版本(如果这些版本仍然存在)。因此,以前的组合页面不会被重建。

另请参见


华夏公益教科书