求闻百科:格式手册/模板

本页使用了标题或全文手工转换,现处于中国大陆简体模式
页面被全保护
求闻百科,共笔求闻

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

由于求闻百科模板众多,为避免模板内容杂乱,便于维护,同时避免不同的模板实现相同或类似的功能也会有截然不同的用法的情况,求闻百科确立此方针。此外,若模板或模块由Lua编写,则需额外遵守《Lua格式手册》。

文档

模板页面的源代码中,除了包含模板本身之外,还应包括文档(document)。文档内容放在模板的/doc子页面,然后在模板代码中,通过模板链接:{{文档}}模板来展示文档,并使用<noinclude>...</noinclude>包围。这样,访问模板页面时,文档会显示在模板页面中,而调用模板时,则不会在调用结果中显示文档。

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

模板代码<noinclude>{{documentation}}</noinclude>

注意:

  • 模板链接:{{documentation}}模板有不同的重定向名称,如“doc”,这些都是可以使用的,依照用户习惯而定。
  • 避免在<noinclude>前换行,也就是说<noinclude>直接接在模板代码后面,不要换行。即使模板代码自身就有很多行,也应该将<noinclude>紧接在模板最后一行代码的后面,不要换行。
  • </noinclude>(noinclude标签的结束标记)一般可以省略,不会影响解析。

模板自身所属的分类(这些分类通常为Category:模板的子分类)也应该加入在文档中,并用<includeonly>...</includeonly>包含,这样模板页面本身会加入此分类,而模板文档页面不会加入此分类。如需修改模板所属的分类,只需要在文档中进行修改即可,不需要修改模板本身,即使模板被保护了,只要有编辑文档页面的权限,便有权修改模板分类。

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

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

缺失足够的文档说明的模板可能会被删除,即使这些文档已经有了一定的使用量。此外,对于从其他网站导入的模板,如果文档不是中文的,应当翻译成中文,未能及时将文档翻译成中文的,模板不得导入

关于模板链接:{{doc}}模板在技术上的用法,请参考Template:Documentation

参数

模板的参数分为位置参数和命名参数。其中位置参数又分为隐式位置参数和显式位置参数,具体技术细节不在此叙述。模板参数的设置应当遵循以下规范。

参数命名

一般来说,参数应该以小写英文命名,含有多个单词的,如非需要,应直接拼接在一起,不用空格、连字符或下划线分开。参数名称与CSS属性(如list-style-type)、JavaScript字段名称(如wgAction)等固定名称同名且确实表示这些意思的,可以直接使用这些名称,无需遵守此条命名规范。

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

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

约定命名

有时存在这样一种现象:不同的模板提供具有类似功能的参数,但这些参数即使效果类似,用法也存在不同。例如,很多模板都会设置一个参数来避免将调用了此模板的页面加入分类,但不同模板参数用法不同,有的使用|nocat=1,有的使用|no_category=1,有的使用|category=no,五花八门。为避免不同的模板之间不必要的差别,不同模板的功能相同的参数尽可能使用相同的参数名称和格式

以下为求闻百科暂时约定的一些参数名称。如模板需要设置具有以下功能的参数,请尽量使用这些约定的参数名称。参数类型仅供参考。

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

参数类型

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

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

数字
可视情况规定为整数或浮点数,一般不接受复数,也不接受inf、nan等特殊数字。数字要求能够被#expr解析器函数识别,且能被Lua的tonumber函数识别,特殊情况除外。
布尔值
表示true或false。本站各模板对布尔值类型的参数读取方法不一致,是否使用模板链接:{{yesno}}来判断参数是自愿的,唯要求能将0视为false、1视为true。使用模块的,推荐使用Module:Yesno来解析布尔值类型的参数。
字符串
通常来说,应该是比较短的字符串,并避免使用wikitext代码。页面名称也是字符串。
wikitext
即允许含有wikitext代码的字符串。
日期
日期应该使用能够被#time解析器函数识别的格式,例如2010-02-04。而在模板呈现的结果中,建议将日期进行格式化。

模板命名

模板的命名需注意以下事项:

  • 元模板一般使用英文命名,且遵从社区习惯,如模板链接:{{navbox}}、模板链接:{{mbox}}。
  • 若使用代码中的固定词语或有关属性,且模板本身确实表示这个意思的,则直接使用这个词作为模板名。例如模板链接:{{color}}对应的是CSS中的“color”属性,因而命名为“color”而非“颜色”;模板链接:{{red}}对应的是color的属性值“red”,因而命名为“red”而非“红”或者“红色”。
  • 消息框模板使用消息内容的简短语句命名。如模板链接:{{需要扩展}}、模板链接:{{没有任何参考来源}}、模板链接:{{原创研究}}。可做英文重定向到中文。
  • 导航框模板一般使用其集合的中文名命名,名称中不再加“导航”“列表”“全部”等词语。例如模板链接:{{苏州轨道交通3号线车站}}、模板链接:{{氢氧化物}}、模板链接:{{虹桥综合交通枢纽}}。
  • 信息框模板以“Infobox”开头,空一格后接上英文。可做中文重定向到英文页面。
  • 用户框模板以“User”开头,空一格后接上中文或英文。注意还需要符合Qiuwen:用户框方针
  • 其他模板可按照社区惯例酌情处理。