维基百科

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

< 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”