Project:模板

来自滚动的天空Wiki

模板(template)可用于多个页面显示相同的或类似的内容,从而节省代码,并便于维护。模板中也可以包含模板。为方便编辑者使用,模板页面会显示其文档内容,用来说明该模板的用途、用法、用例等,模板分类也会置于模板文档。此外,有时候维基文本无法满足模板需求,因此使用Lua编程语言编写模板。

随着网站发展,模板数量也越来越多,从而导致内容杂乱,不易维护,甚至不同的模板实现相同或类似的功能也会有截然不同的用法。为避免出现这种情况,本站建立了如下标准,供编辑者参考。

文档

模板页面的源代码中,除了包含模板本身之外,还应包含文档(document)。模板的用法等信息应该写在文档中。一般来说,文档应该放在单独的页面:该模板页面的/doc子页面。例如,Template:Fullurl模板的文档应该位于Template:Fullurl/doc。这样,文档被修改后不影响模板本身,而且如果模板被保护了,无权编辑模板的用户通常仍能编辑文档。

文档的使用方式

在模板中使用{{文档}}模板嵌入包含该文档,该模板会自动载入文档内容并进行包装。模板的代码应该如下:

一大堆模板代码<noinclude>{{文档}}</noinclude>

注意:

  • {{文档}}模板有不同的别称,如“doc”“documentation”,这些都是可以使用的。
  • 避免在<noinclude>前换行,也就是说<noinclude>直接接在模板代码后面,不要换行。即使模板代码自身就有很多行,也应该将<noinclude>紧接在模板最后一行代码的后面,不要换行。
  • </noinclude>(noinclude标签的结束标记)一般是可以省略的。省略该结束标签还可以避免末尾因为多余空行而导致嵌入包含模板时出现错误。

对于临时使用、使用率不高的模板,为了方便,可以不将文档放在单独的页面,而是将文档置于模板代码中,因此这种情况下的模板代码如下:

模板代码<noinclude>{{文档|content=文档内容}}</noinclude>

关于{{doc}}模板的其他用法,请参考Template:文档

文档的内容

文档应该清晰地阐明此模板的用途、用法、用例。比如,该模板用来干什么,在什么情况下使用,参数怎样使用,会进行些什么操作等等。

对于单独页面的文档,模板自身所属的分类(通常为Category:模板的子分类)也应该加入在文档中,并用<includeonly>...</includeonly>包含,这样模板页面本身会加入此分类,而模板文档页面不会加入此分类。

为什么不将分类直接放在模板代码中呢?这是为了便于维护。如需修改模板所属的分类,只需要在文档中进行修改即可,不需要修改模板本身。

参数

为了使得模板能够用于不同的情况,往往需要设置模板参数,模板就会根据参数来显示不同的内容。

参数分为三种:位置参数和命名参数。其中位置参数又分为隐式位置参数和显式位置参数,具体技术细节不在此叙述。

参数命名

一般来说,参数应该以小写英文命名,含有多个单词的,如非需要,应直接拼接在一起,不用空格、连字符和下划线分开。但是,与已经约定俗成的代码内文字一致的,可直接使用这些约定的代码文字,例如list-style-typewgConfig

对于有参数名称以数字结尾的,数字应该紧挨着英文,例如参数名称可以是page1page2page3等,而不建议使用page_1page-2这样的参数名称。

不建议使用中文参数名称。

约定命名

有时你可能发现这样的现象:不同的模板提供具有类似功能的参数,但这些参数即使效果类似,用法也存在不同。例如,很多模板都会设置一个参数来避免将调用了此模板的页面加入分类,但不同模板参数用法不同,有的使用nocat=1,有的使用no_category=1,有的使用category=no,五花八门,令人混淆。

为避免不同的模板之间不必要的差别,不同模板的功能相同的参数尽可能使用相同的参数名称。如模板需要设置具有以下功能的参数,请尽量使用约定的参数名称。参数类型仅供参考。

参数名称 参数类型 说明
category 字符串 对于需要自定义设置分类的模板,可设置此参数以设置自定义的分类,一般要自动补充Category:前缀。
class 字符串 可设置此参数,以将模板生成的内容主体HTML元素加入到指定的类(class)中。有时这些元素本身就加入了某个类,至于使用此参数是否会覆盖这个类,视情况设置。
content 维基文本 可设置此参数以指定内容,通常为一段或多段内容。
nocat 布尔值 对于使用了该模板就会加入分类的模板,可设置此参数以让用户可以避免加入分类。
page 字符串 如果一个模板需要使用页面标题,则可以设置此参数。
style 字符串 可设置此参数,以允许设置模板生成的内容的CSS样式(style)。

关于隐式位置参数被等号打断的情况

模板调用的一般语法为{{模板名称|位置参数1|位置参数2|位置参数3……|参数名称1=命名参数|参数名称2=命名参数|……}},这里的位置参数没有显式地指定其位置,因此称为隐式位置参数。当隐式位置参数含有等号(=)时,就会被系统理解为命名参数,从而导致参数不被识别。

但是模板一般不需要考虑这种情况,而是要求调用此模板而遇到这种情况时使用显式位置参数,也就是要求模板的使用者考虑这种情况。比如{{code|lang=lua|1=local x = 1}}中的第一个位次参数就必须使用显式传入,否则参数值中Lua代码的等号会被解析为参数的等号。

参数类型

参数类型是指传入模板的参数的值的类型,而非参数名称(有时称为“键”)的类型。在MediaWiki中,参数类型(包括传入Lua中的)往往会是字符串,但为便于理解和修改,我们仍然会手动规定一些参数类型,这样以便于模板用法的统一。允许一个参数同时担任多个参数类型。

请注意:对软件来说,模板的参数类型一般都会是字符串,所以我们定义的这些参数类型只是来让用户和编辑者使用和理解的。

数字
可视情况规定为整数或浮点数,一般不接受复数,也不接受inf、nan等特殊数字。数字通常要求能够被#expr解析器函数识别,且能被Lua的tonumber函数识别,特殊情况除外。
布尔值
表示“真”“假”或“是”“否”。为便于使用,本Wiki的模板的布尔值参数统一使用1表示“真”,0表示“假”,不使用yes、no、true、false等表示方式。接收布尔值参数的模板,对于缺省值和其他值的处理方式,不做要求。
字符串
通常来说,应该是比较短的字符串,并避免使用维基文本代码。页面名称也是字符串。例如,{{关卡信息}}中的“name”参数就是字符串,它的值可以是“灼热未来”,但不应当是“[[灼热未来]]”或者“'''灼热未来'''”。
维基文本
即允许含有维基文本代码的字符串。这种情况下的文本不应该用来与特定字符串进行比较。
枚举
枚举是指一个参数只允许多个指定的值,值必须是其中的一个。例如,{{关卡信息}}的“type”参数就是枚举,它的值可以是“主线关卡”“奖励关卡”等,但不是任意的。布尔值也可以理解成一种枚举,其值为1或0中的一个,而不应当为其他值。
日期
日期应该使用能够被#time解析器函数识别的格式,例如2010-02-04。而在模板呈现的结果中,建议将日期进行格式化。例如{{版本信息}}模板中,日期会通过{{#time:Y年Mj日|{{{date}}}}}的方式进行格式化,如果传入“2010-02-04”,则模板的呈现中会显示“2010年2月4日”,但如果传入不能够被#time解析器函数识别的格式,例如“2010年2月4日”或者“去年的今天”,则会无法识别。

模板分类

如果没有特殊表明,模板分类指的是模板自身所属的分类,通常为Category:模板的子分类。

模板样式

模板样式是指的该模板包含的CSS样式表,一般使用“TemplateStyles”扩展,有时也可以使用#css解析器函数。部分非常常用的模板的样式是存储在默认启用的小工具(如MediaWiki:Gadget-navbox.css)中的。

对于使用了TemplateStyles模板样式的模板,应在文档中加入{{模板样式|样式表页面标题}}。例如,{{navbox}}模板使用了MediaWiki:Gadget-navbox.cssMediaWiki:Gadget-hlist.css,所以在文档中加入{{模板样式|MediaWiki:Gadget-navbox.css|MediaWiki:Gadget-hlist.css}},如右边所示。

模板重定向

模板重定向用于让模板有多个名称,也就是别称。这样,多个名称的模板实际上是等价的。例如,{{navbox}}和{{导航框}}是等价的,{{documentation}}、{{doc}}、{{文档}}三者也是等价的。

有重定向页面的模板,应该在其文档中使用{{模板重定向|重定向至该模板的模板名称}}以表示重定向至该模板的模板名称。例如,Template:Mbox重定向至Template:消息框,所以在消息框模板的文档页面Template:消息框/doc中加入{{模板重定向|Mbox}},效果如右边所示。

调用Lua

模板可以通过#invoke解析器函数调用Lua代码,从而实现更高级的功能。调用Lua代码后,应在其文档页面中使用{{lua|Lua模块名称}}以表明该模板调用的Lua模块名称。

例如,{{导航框}}模板调用了Lua模块模块:Navbox,所以其文档页面应该使用{{lua|navbox}},效果见右。

模板名称

这里的模板名称是指非重定向的名称。模板名称一般是中文,有时可以是英文。具体规则如下:

  • 消息框类模板的名称应该用中文简短地概括该消息的内容,例如{{维基百科搬运}}(表明该页面是从维基百科搬运的)、{{需要扩展}}(表明该页面或段落内容需要扩展)、{{排版问题}}(表明该页面存在排版问题)。
  • 导航框类模板的名称应该是该集合事物的名称,名称中不含“所有”“列表”“导航”等词汇,如{{关卡}}(包含所有关卡的导航框)、{{版本}}(包含所有游戏版本的导航框)。
  • 信息框类模板的名称以“信息”二字结尾,如{{关卡信息}}、{{版本信息}}。
  • 用于构成代码的文本常使用与代码名称一致或类似的名称,如{{code}}(用来代替<code>...</code>)、{{nowiki}}(用来代替<nowiki>...</nowiki>)。
  • 其他类型的模板应兼顾习惯、用途以及便于理解的程度。例如,模板链接系列的模板就沿袭维基百科的习惯命名为{{tl}}、{{tlx}}、{{tlc}}等。通常来说,同一系列模板或类似模板的名称格式应当一致。