求聞百科:格式手冊/模板

本页使用了标题或全文手工转换,现处于香港繁体模式
頁面被全保護
求聞百科,共筆求聞

本方針主要記載模板(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:用戶框方針
  • 其他模板可按照社區慣例酌情處理。