帮助:模板
一个模板 只是一个为包含在其他页面上而设计的页面。如果模板被更改,这通常会反映在使用该模板的每个页面上。正如你可能开始想象的那样,模板是一个强大的工具,如果使用得当,可以减少工作量并提高可维护性。在本页中,你将学习如何使用模板以及如何制作自己的模板。
一般
模板可以包含任何所需的维基文本,包括对其他模板的调用。它们具有一些有限的编程能力:可定制的值(称为参数)、计算和分支(使用解析器函数)以及对维基特定变量的访问,例如日期、时间和页面名称。
要在页面中使用模板,模板标签(形式为{{模板名称}},即模板名称用双花括号括起来)将被添加到你想让模板出现的地方。当读者想要查看页面时,服务器会获取模板页面上的内容,处理与页面相关的任何变量,并将结果显示在模板标签的位置。
模板适用于任何希望在两个或多个页面中复制文本的文本,并且不需要每个副本都独立编辑,以适应它所在的页面。由于可以使用参数,版本在一定程度上甚至可以不同,并且参数值可以针对每个版本独立编辑。模板不仅方便,而且还可以“强制”有用的统一性,例如,某种“样式”。
典型应用是
- 消息 用于显示信息({{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}}。
模板页面本身可能包括不与模板一起转包容的材料(例如文档或模板本身所属的分类),或者仅在页面被转包容时使用的材料(例如分类 应用于转包容页面,但不应用于模板)。请参见下面对includeonly 和 noinclude 标签的讨论。
尝试转包容一个不存在的模板会产生一个红链接,就像链接到任何其他不存在的页面一样。点击链接可以创建该特定模板。
基本模板用法示例
如果你想尝试任何这些,请使用模板沙箱.
没有参数的模板
要查看一个非常简单的模板示例,请查看Template:Tc。此模板仅将字母“in”转入其他页面。例如,将以下短语编辑到任何页面将产生相关结果
描述 | 输入文本 | 处理后的结果 |
---|---|---|
{{Tc}} 自身 | {{tc}} | in |
单次使用 {{tc}} | {{tc}} 2009年,随着巴拉克·奥巴马入主白宫,我们发现…… | 在2009年,随着巴拉克·奥巴马入主白宫,我们发现…… |
多次使用 {{tc}} | {{tc}} 2009年,随着巴拉克·奥巴马入主白宫,我们发现…… | 在2009年,随着巴拉克·奥巴马入主白宫,我们发现…… |
你会注意到,模板在转入时只包含字母“in”,尽管模板页面上的解释文字(“此模板用于...” 点击上面的模板链接查看)。如果你编辑模板页面,(点击此链接),你会看到除了字母“in”之外的所有内容都包含在 'noinclude' 标签中,这将在后面讨论。
带有未命名参数的模板
带有参数的转入只是稍微复杂一点。举个简单的例子,著名的死人手可以通过以下模板使用未命名参数来重现
描述 | 输入文本 | 处理后的结果 |
---|---|---|
使用三个模板(Template:Clubs、Template:Diamonds 和 Template: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(用于一些关于博弈论的书籍)给出了一个简单的 2x2 网格,它具有可调整的值,使用 UL、UR、DL 和 DR 来表示左上、右上、左下和右下,以及一个 Name 参数来在矩阵底部添加名称。
描述 | 代码 | 结果 | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
支付矩阵 | {{payoff matrix | UL = 5 | UR = 7 | DL = 2 | DR = 9 | Name = Example usage }} |
| ||||||||||||
显示缺失参数的默认值和不同排序的支付矩阵 | {{payoff matrix | DR = 9 | Name = Example usage | DL = 2 | UR = 7 }} |
|
在第二种情况下,参数的顺序已更改,但结果没有改变——这是命名参数优于未命名参数的优点之一——并且其中一个值(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. John 和 Mary 拥有一只名叫 Fido 的小狗,它已经 6 岁了。
- B. Bill 和 Susan 拥有一只名叫 Queenie 的胖猫,它已经 7 岁了。
需要注意的事项
- 位置参数的编号会跳过命名参数(如上面的“age”)。
- 模板标记中命名参数值的开头和结尾空格将被模板剥离。
- 这对于未命名参数不适用,未命名参数会保留尾随和前导空格。但是,浏览器会将多个空格字符渲染为单个空格,因此“Fido”、“fat”和其他未命名参数值的周围额外空格不会立即显示。如果未命名参数用于显示以外的其他目的,例如链接,这可能会令人困惑。
- 命名参数值在模板中使用的顺序无关紧要。
- 位置参数的编号被视为名称:{{ peoplepets | John | ... }} 可以写成 {{ peoplepets | 1 = John | ... }}。当需要按相反顺序输入位置参数或位置参数值包含等号时,这很有用。
- 值可以为空。这里,第二个位置参数和“age”参数的值为空
- 模板标记:{{ peoplepets | John || age = | Fido | small | kind = dog }}
- 生成(注意缺少的单词):John 和 拥有一只名叫 Fido 的小狗,它已经 岁了。
- 值可以保持未提供。这里省略了“kind”参数
- 模板标记:{{ peoplepets | John | Mary | age = 6 | Fido | small }}
- 生成(这将显示缺少的参数):John 和 Mary 拥有一只名叫 Fido 的小 {{{kind}}},它已经 6 岁了。
参数默认值
可以使用竖线字符:| 为参数指定默认值。上面的示例模板可以改写如下(其中“friend”是位置参数 2 的默认值,第四个位置参数默认为空,宠物的“kind”默认为“dog”——参见Template:Peoplepetsd)。
- {{{1}}} 和 {{{2|friend}}} 拥有一只 {{{4|}}} {{{kind|dog}}} 叫做 {{{3}}},它已经 {{{age}}} 岁了。
像这样的模板标记:{{ peoplepetsd | Bill | age = 7 | 3=Queenie }} 然后会生成短语Bill 和 friend 拥有一只名叫 Queenie 的狗,它已经 7 岁了。
请注意,狗名前面的“3=”是必需的,因为未指定第二个位置参数。
参数的空值将覆盖默认值,生成一个空空格。换句话说,{{ peoplepetsd | Bill || kind=| age = 7 | 3=Queenie }} 然后会生成短语 Bill 和 拥有一只名叫 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 |
由于 {{t3d}} 不使用参数 {{{4}}}、{{{8}}} 或 {{{12}}},“行号”值不会影响生成的维基文本。虚拟命名参数可以在任何模板标记中使用;只需选择一个未使用的参数名称并将其添加为“unusedname = value”即可。虚拟命名参数的一种特殊情况是使用空字符串作为参数名称。
参数和参数值的限制
- 未命名参数不能分配包含等号(=)的值;解析器将等号视为命名参数的分配。有一些间接方法可以解决此限制
- 参数值不能包含竖线(|)字符;解析器会将竖线字符视为分隔符,而不是文本。竖线可以在维基链接(country=[[United States|USA]])或嵌套模板(例如,volume= {{convert|30|acre.ft|m3}})内使用。解决此限制的间接方法如下
- 使用特殊模板 {{!}},它会返回有效的竖线字符。如果您需要将某些内容作为实际竖线字符读取(例如,如果您正在使用参数修改维基文本表格的结构),请使用此方法。
- 使用竖线的 HTML 实体:|。这仅适用于文本表示;如果竖线需要作为实际竖线进行处理,则此方法无效。
- 参数值不能包含不匹配的连续花括号 - }} 或 {{。解析器会尝试将其解析为模板标记或参数的开头或结尾,并在某个地方抛出错误。但是,参数可以包含其他参数、魔术字或模板标记。
- 同样,这可以使用“nowiki”标记或 HTML 实体来解决。
嵌套模板
模板可以包含其他模板——通常称为“嵌套”。在处理模板时,任何嵌套模板生成的维基文本都会转入嵌套模板,因此最终产品本质上是从最深层嵌套的模板开始处理的。虽然在应用方面相当简单,但它涉及一些值得注意的怪癖和技巧。
要将参数值传递给嵌套模板,请将参数标记作为嵌套模板的某个参数的值放置。
- 示例
- Template:A 包含“the quick brown {{B|{{{3}}} }} jumped over...”。这将传递给 Template:A 的第三个位置参数的值作为 Template:B 的第一个位置参数传递,然后返回 B 生成的维基文本作为短语的一部分。
- Template:A 包含“the quick brown {{B|waldo={{{3}}} jumped over...”。与上面一样,只是 Template:A 的第三个位置参数传递给 Template: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 }} | 讨论 |
获取 Wikibooks 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 ° |
其他编辑信息
- 如果模板的第一个包含字符是 Wiki 标记字符 :;*# 之一,那么它将被处理为好像它位于一行的开头(即使模板标签不在正确的位置)。这允许在模板中创建各种类型的列表,其中模板可能并不总是位于列表的正确位置。为了避免这种效果,使用<nowiki>#</nowiki>或 HTML 实体,例如:表示冒号。这在与定义 列表 结合使用时也很有用。
- 当一个页面被调用以转入时,该页面是一个重定向页面,则将包含重定向目标。
包含模板的页面的修订历史
存储在 页面历史 中的页面包含维基文本,其中可能包含对模板和图像的引用。当查看页面的旧版本时,这些引用将指向模板和图像的当前版本(如果它们仍然存在)。因此,以前组合的页面不会被重建。
另请参见