维基百科

维基百科:模板数据/教学

< Wikipedia:模板数据
快捷方式
可视化编辑器的界面
可视化编辑器的界面
关于
幫助我們启用
研究
  • 即時統計
其他
参见：mw:Help:TemplateData/zh

模板數據（TemplateData）是一種儲存各參數名稱、功用等模板資訊的方式，視覺化編輯器（VisualEditor）可讀取這些資訊並將之呈現給編輯者。模板數據是由MediaWiki的模板數據延伸組件（TemplateData extension）控制，可讓使用者在模板頁中寫入小量的組織化數據，也可透過嵌入的方式加入模板中（例如經由標準的模板說明文件頁面）。當模板中包含了這樣的組織化數據後，就可以將之顯示在視覺化編輯器中。這一切聽起來可能很複雜，但其實做起來非常簡單。

如何使用模板數據

编辑

模板數據的架構

编辑

模板數據的架構是基於「JSON」標準，其內容十分簡潔。第一步是在模板原始碼中 <noinclude></noinclude> 標籤範圍內加入一對 <TemplateData> 標籤，這組標籤也可加入在模板的說明文件子頁面中的任一處。範例如下： 

<TemplateData>
此處為模板數據內容
</TemplateData>

這將能讓系統知道在兩個標籤之間的內容為模板數據，當模板被使用時即可調出其中的數據資料。而模板數據的內容有固定的格式，將被用來列出可在模板中使用的參數。

模板數據

编辑

模板數據是被加入在模板原始碼中 <noinclude></noinclude> 標籤的範圍內，或是模板說明文件子頁面中的任何一處。在某些情況下，模板的原始碼可能會被保護以防止未授權的用戶編輯。在這時模板數據將僅能被加入到模板的/doc子頁面。

模板數據通常是被放置在模板的說明文檔主要資訊的下方，位於「參見」章節之上。

提示：建議您在 <templatedata> 標籤之前加入 {{TemplateDataHeader}} 模板，這將可讓該頁面被自動標示為模板數據文件，並可將之加入適當的頁面分類中。

指出模板中的參數

编辑

若模板沒有參數，您可以使用一行簡單的代碼  "params": {} 來完成模板數據的內容。如果您沒有輸入這行代碼，頁面將會無法儲存。

然而，大多數的模板都有可輸入的參數，例如日期、網址、條目名稱、圖片、數字或字串等。參數可透過等於（=）符號傳送。舉例來說，{{cite web}} 模板透過傳送參數來完成引用，包括網址 url=、標題 title=、查閱日期 accessdate=等。參數的指定也可使用其所在之順序，而不需使用參數名稱，例如 1、2 等，模板的主頁面或子頁面中可能會有其適用參數的說明。

完成模板數據資訊

编辑

第一個需要填寫的資訊為 "description" 項目，也就是模板的簡要說明。內容包括模板的功用以及使用的時機。您可以使用模板說明文件中的簡介，並將之放在西式雙引號（" "）中。請注意，說明內容中不可使用維基語法（wikitext）。

接著創建一個 "params" 區塊，並加上花括號（{ 和 }）區隔。在這個區塊內，您需要使用以下提供的資訊，為模板中的每一個參數創建一個區塊。大多數的項目都為選填，但提供更詳細的資訊可讓模板更容易使用：

  • 在西式雙引號間輸入參數的名稱，並在後方加上花括號（{ 和 }）來創建一個區塊。
  • "label" 是該參數的人類可判讀中文名稱，這個名稱將會在視覺化編輯器中顯示。請在前後加上引號。
  • 接著輸入參數的敘述說明 "description"。此處輸入的是該特定參數的說明，而非整個模板的說明。模板的說明頁面中可能會提供這項資訊。請在前後加上引號。
  • 除了上面的基本資料外，您也可以為參數的狀態設定更詳細的資訊：
    • "required" 是用來表示該項參數是否為必須填寫。當參數為必須填寫，且若不填寫則為導致模板無法使用時（例如 {{cite web}} 的 URL 參數），請將本項目設定為 true。
    • "suggested" 是用來表示該項參數是大多數使用者會填寫的（例如引用模板中的來源日期）。您應至少將一項參數標示為建議填寫。
    • "deprecated" 是用來表示該項參數基本上已經不再被使用，此時可將之設定為 true。您可以附加說明建議使用者改填寫其他參數。
  • "aliases" 代稱群組是用來列出同樣功能的不同名稱參數，例如："aliases": [ "2", "Caption", "imagecaption" ]，代表其中包含的三種參數都是同樣的作用。請將各參數的代稱列於此處，避免將代稱分別列於不同的區塊中。
  • "default" 可讓您設定該項參數在未指定時的預設內容（或是留空）；這裡設定的內容將會在模板編輯器中該項參數的文字框內以灰色字體顯示。
  • "type" 控制模板編輯器將如何解讀該項參數，可設定為以下數值之一：

設定值

參數類型

"unknown" 未設定參數類型
"number" 任何數字（numerical value），不含小數點和分隔號
"string" 任何文字串
"line" 簡短的文字欄位，適用於名稱、標籤和其他較短的內容
"wiki-page-name" 一個有效的條目頁面名稱。不需要是已存在的條目，但必須是能夠被創建的條目名稱
"wiki-file-name" 一個有效的檔案名稱。不需要是已存在的檔案名稱，但必須是能夠被上傳的檔案名稱。不可包含名字空間（ 例如：Foo.svg 而非 File:Foo.svg 或 Bild:Foo.svg）
"wiki-user-name" 一個有效的用戶名。不需要是已存在的用戶名，但必須是能夠被創建的用戶名。不可包含名字空間（例如：Foo 而非 User:Foo 或 Usario:Foo）
"content" 用維基語法（wikitext）編寫的內容，包括文字風格、連結、圖片等
"unbalanced-wikitext" 不完整的原始維基語法（wikitext），適用於該模板是為了搭配其他維基語法同時使用時，例如 {{echo|before=<u>|after=</u>}}
  • "inherits" 代表該參數將會繼承另一參數的內容。非常少用。

當模板有一項以上的參數時，在關閉區塊的花括號後方加上逗號 },。

儲存

编辑

當您完成編輯後，請按下「保存編輯」。若您輸入的模板數據有錯誤，將無法儲存。當無法儲存時，請先確認模板數據是否有以下的常見錯誤：

  • 每個開啟引號（"）是否都有搭配一個關閉引號？
  • 是否有任何敘述性字串中包含了引號（"）？如果有，請將之替換為（'）。
  • 每個開啟括號（{）是否都有搭配一個關閉括號（}）？
  • 在每個參數 params 區塊之間是否有用逗點分隔？（應該要使用逗點分隔）

在儲存後，可能需要數分鐘的時間才能讓模板數據在視覺化編輯器中出現。若一段時間後仍未出現，您可對模板本身做出一個零編輯（null edit），這將可讓系統強制更新暫存資料庫。由於許多模板受到編輯保護，您可能需要使用 {{editprotected}} 模板請求零編輯。

實際應用範例

编辑

{{str left}} 是一個簡單的模板，使用方式為 {{Str left|文字串|數字}}，可用來顯示一串文字中的前幾個字（可自行設定）。模板中有兩項參數，參數皆無正式的名稱，僅透過其在模板中的位置來辨認，而兩項參數皆為必填。該模板的模板數據如下： 

<templatedata>
{
	"description": "顯示一串文字中的前幾個字",
	"params": {
		"1": {
			"label": "文字串",
			"description": "需要計算字數裁切的文字內容",
			"required": true,
			"type": "string"
		},
		"2": {
			"label": "長度",
			"description": "希望顯示的字數",
			"required": true,
			"type": "number"
		}
	}
}
</templatedata>

⋯⋯產生的結果如下：

顯示一串文字中的前幾個字

模板参数

参数描述类型状态
文字串1

需要計算字數裁切的文字內容

字符串必需
長度2

希望顯示的字數

数字必需

完整的空白代碼

编辑

您可以複製以下的空白代碼來創建新的模板數據： 

<templatedata>
{
	"description": "模板簡要說明",
	"params": {
		"第一項參數名稱": {
			"label": "標示",
			"description": "說明",
			"required": false,
			"suggested": false,
			"deprecated": false,
			"aliases": [],
			"default": "default value",
			"type": "string",
			"inherits": ""
		},
		"第二項參數名稱": {
			"label": "標示",
			"description": "參數說明",
			"required": false,
			"suggested": false,
			"deprecated": false,
			"aliases": [],
			"default": "default value",
			"type": "number",
			"inherits": ""
		}
	},
    "sets": { }
}
</templatedata>

幫助

编辑

當您在編輯或創建模板數據遇到問題時，歡迎到視覺化編輯器反饋頁面中提出。

其他範例

编辑

一個不含任何參數的模板：{{fixed}}。請注意，即使沒有參數，也必須輸入 "params" 來建立一個空的表格：

代码 效果 
<templatedata>{
  "description": "顯示一個打勾符號和「已修復」的文字。本模板沒有參數需要輸入。",
  "params": { }
}</templatedata>

顯示一個打勾符號和「已修復」的文字。本模板沒有參數需要輸入。

模板参数

参数描述类型状态
未指定参数

一個參數有其他代稱的模板 {{quote}}：

代码 效果 
<templatedata>{
  "description": "在條目中加入一個引言框。",
  "params": {
    "text": {
      "label": "文字",
      "description": "引言的內文",
      "type": "string",
      "required": false,
      "aliases": [ "1", "quote" ]
    },
    "sign": {
      "label": "作者",
      "description": "引言內容的作者",
      "type": "string",
      "required": false,
      "aliases": [ "2", "cite" ]
    },
    "source": {
      "label": "出處",
      "description": "引言的來源出處",
      "type": "string",
      "required": false,
      "aliases": [ "3" ]
    }
  }
}</templatedata>

在條目中加入一個引言框。

模板参数

参数描述类型状态
文字text 1 quote

引言的內文

字符串可选
作者sign 2 cite

引言內容的作者

字符串可选
出處source 3

引言的來源出處

字符串可选

一個參數有預設數值的模板 {{col-6}}。當參數未指定時模板將會自動使用預設的數值。

代码 效果 
<templatedata>
{
    "description": "建立一個新的欄位，必須與 {{col-begin}} 模板配合使用，適用於建立六個欄位。",
    "params": {
        "width": {
            "label": "寬度",
            "description": "欄位的寬度",
            "type": "string",
            "default": "16.66%",
            "aliases": ["w"],
            "required": false
        },
        "align": {
            "label": "對齊",
            "description": "水平對齊方式。",
            "type": "string",
            "default": "left",
            "required": false
        },
        "valign": {
            "label": "垂直對其",
            "description": "垂直對齊方式。",
            "default": "top",
            "type": "string",
            "required": false
        }
    }
}
</templatedata>

建立一個新的欄位，必須與 {{col-begin}} 模板配合使用，適用於建立六個欄位。

模板参数

参数描述类型状态
寬度width w

欄位的寬度

默认值
16.66%
字符串可选
對齊align

水平對齊方式。

默认值
left
字符串可选
垂直對其valign

垂直對齊方式。

默认值
top
字符串可选

技術限制與問題

编辑

模板數據對於編輯現有模板來說是十分優秀的工具，但目前無法在創建新模板時自動調出其中的參數。這項功能現在正在開發中。此外，編輯完模板數據後到在視覺化編輯器中出現為止需要一些時間，這可能會讓除錯變得有些困難。

模板數據的大小上限為65,535位元組（bug 51740）。對於某些使用大量參數的模板來說，可能會讓模板數據超過此一上限（例如 {{Infobox officeholder}}）。

工具

编辑
 
模板數據編輯器

外部連結

编辑
 
MediaWiki有相關项目：Extension:TemplateData#Defining a TemplateData block
  • Jsonlint 一個JSON的除錯器，可找出模板數據原始碼中的錯誤
检索自“https://zh.wiki.x.io/w/index.php?title=Wikipedia:模板数据/教学&oldid=64842990”