滚动的天空Wiki:格式规范/模板

来自滚动的天空Wiki

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

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

文档[编辑]

模板页面的源代码中,除了包含模板本身之外,还应包括文档(document)。在模板代码中,文档应该使用<noinclude>...</noinclude>包围,这样,访问模板页面时,文档会显示在模板页面中,而调用模板时,则不会在调用结果中显示文档。

文档的使用方式[编辑]

一般来说,文档应该放在单独的页面:该模板页面的/doc子页面。例如,Template:Fullurl模板的文档应该位于Template:Fullurl/doc。然后,在模板中嵌入包含文档,方法就是使用{{doc}}模板。

因此,模板的代码应该如下:

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

注意:

  • {{文档}}模板有不同的别称,如“doc”“documentation”,这些都是可以使用的。
  • 避免在<noinclude>前换行,也就是说<noinclude>直接接在模板代码后面,不要换行。即使模板代码自身就有很多行,也应该将<noinclude>紧接在模板最后一行代码的后面,不要换行。
  • </noinclude>(noinclude标签的结束标记)一般是可以省略的。

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

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

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

文档的内容[编辑]

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

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

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

参数[编辑]

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

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

参数命名[编辑]

一般来说,参数应该以小写英文命名,含有多个单词的,如非需要,应直接拼接在一起,不用空格、连字符和下划线分开

对于有参数名称以数字结尾的,数字也应该紧挨着英文,例如参数名称可以是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=命名参数|……}},这里的位置参数没有显式地指定其位置,因此称为隐式位置参数。当隐式位置参数含有等号(=)时,就会被系统理解为命名参数,从而导致参数不被识别。

但是模板一般不需要考虑这种情况,而是要求调用此模板而遇到这种情况时使用显式位置参数,也就是要求模板的使用者考虑这种情况。

参数类型[编辑]

参数类型是指传入模板的参数的值的类型,而非参数名称(有时称为“键”)的类型。在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}},效果见右。

模板名称[编辑]

待填。