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

快捷方式

可视化编辑器的界面

主页（或在MediaWiki）
反馈（或在MediaWiki）
沙盒（不要求账户）

关于

帮助我们启用

研究

研究主页

即时统计

Hourly edits, VisualEditor vs. wikitext
按用户类型，以所有编辑的百分比计数
Hourly edits, VisualEditor vs. wikitext
按用户类型，以所有按用户类型区分的
Hourly edits, VisualEditor vs. wikitext
以所有编辑的百分比计数
Hourly edits, VisualEditor vs. wikitext
编辑次数的绝对值
Hourly edits, VisualEditor vs. wikitext
按用户类型区分的编辑次数的绝对值
Daily unique editors by UI
按用户类型
Hourly reverted revisions
按回复类型
（所有指示牌）

其他

模板数据（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}}）。

工具

TemplateDataEditor — 可让编辑模板数据变得较简单的工具
另一个模板数据编辑工具
TemplateData Skeleton — 可读取模板的原始码，并找出其中使用的参数，将之输出成一个模板数据的框架文件，并在其中列出所有参数。
Module:TemplateDataGenerator‎ - 另一个框架文件产生工具。

外部链接

Jsonlint 一个JSON的除错器，可找出模板数据原始码中的错误