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}}等。通常來說,同一系列模板或類似模板的名稱格式應當一致。