Extension:TemplateData/zh
TemplateData引入 <templatedata> 標籤和 API，它们共同允许编辑者指定应如何调用模板并使用对应的参数。
这些信息以格式良好的表格形式提供给终端用户，并以 JSON API 的形式提供给其他系统（例如 VisualEditor），使其能够建立接口，以处理模板。
有关深入的帮助，请参阅[[Special:MyLanguage/Help:TemplateData|Category:Pages using LC zh with unknown or deprecated arguments#zh]]。
安裝
- 下载，并将解压后的
TemplateData移动到extensions/目录中。
开发者和代码贡献人员应从Git安装扩展，输入：cd extensions/ git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateData
- 将下列放置在您的LocalSettings.php的底部：
wfLoadExtension( 'TemplateData' );
完成 – 在您的wiki上至Special:Version，以验证已成功安装。
TemplateData扩展会在模板页面的wikitext中定义<templatedata>标签（当然也可以是从其他页面嵌入包含的），从而实现效果。
这种设计是为了兼容很多wiki都有的常见布局，即嵌入包含一个单独的文档页面（但不是必需的）。
<templatedata>的内容必须是有效的JSON，其格式如下所示，注意所有的描述必须是纯文本（模板数据中不接受wikitext）。
页面包含<templatedata>块时，TemplateData会在页面保存时，做出以下检查：
- 内容必须是有效的JSON；
- JSON结构中的每一项必须是下文指定的预设类型（例如对象、数组或原始类型）；
- 对于那些具有指定的可能的值的列表（例如参数中的
type）的项，JSON 对象中的值必须与这些值中的某一种相匹配。
如果这些检查中的任何一项失败，服务器将不允许用户保存，并且将在编辑页面的上方显示错误消息。
对于autovalue项，T4700使得subst:无法在任何添加到标签（包括<ref>和<gallery>标签）的模板中生效。
TemplateData在这种情况下不会阻止保存，但最终的wikitext在使用模板时不能被正确解析。
格式
以下内容是JSON数据的视觉化版本，正如包含在<templatedata></templatedata>标签的模板页面定义的。
格式规定可参考TemplateData。
有关最新版本，请参考Specification.md。
TemplateData对象是一个“JSON根元素”，包含在模板页面的<templatedata>元素中。
| 鍵 | 类型 | 描述 |
|---|---|---|
description |
InterfaceText或null |
模板的简要说明。 必须为纯文本格式。 如果填写了，当编辑单个模板时以及在用户选择其中的一个时搜索结果中会显示为说明文本。 默认设置为null。
→ For more details see: description |
params |
包含参数（Param）对象的对象 | 一个对象，它将模板的每个参数名称映射到描述该参数属性的相应的Param对象上。
→ For more details see: params |
paramOrder |
包含参数名称的字符串的数组 | 应显示的参数的逻辑顺序。 该数组只包含每个参数的键值一次。 每个字符串都必须是 params 对象中的有效键值。
→ For more details see: paramOrder |
sets |
包含Set对象的数组 | 包含集合规范的数组。 集合是应该一起使用的一组参数。 默认值为[]。 请注意，sets功能仍在开发中。 |
format |
字符串，inline 或 block |
模板的wikitext应该如何布局。 默认设置为inline。 有关其他自定义格式，请参阅 #Custom_formats。 |
maps |
包含Maps对象的对象 | 这个对象将模板数据的第三方读取机制（例如Citoid、Special:MyLanguage/Wikidata等）的简化的名称，映射一个对象，从而将读取机制参数的名称映射到模板参数的一个或者多个对应的名称中。 |
| 鍵 | 类型 | 描述 | |||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
label | InterfaceText | null |
参数的（非常）简短的名称。 尽量保持20个字符以下。
→ For more details see: label | ||||||||||||||||||||||||||||
description |
InterfaceText | null |
参数的简短描述，以使用户知道从选项列表中选择哪个。
→ For more details see: description | ||||||||||||||||||||||||||||
required |
false |
模板是否需要该参数才能工作（如果必须指定此参数，则值为 true）。
→ For more details see: required | |||||||||||||||||||||||||||||
suggested |
false |
是否建议该参数使模板有用（如果应指定此参数，则值为 true）。
→ For more details see: suggested | |||||||||||||||||||||||||||||
deprecated |
布尔值或字符串 | false |
该参数是否被弃用。 该值可以是一串指令，指导用户可以做什么，或者只是 true 。
→ For more details see: deprecated | ||||||||||||||||||||||||||||
aliases | 包含字符串的数组 | [] | 别名列表。 别名是参数的替代名称，可以用来代替（而不是附加于）主名称。 别名不记录在单独的参数对象中。 如果它们需要更多信息，它们应该在自己的属性中被标记为“已弃用”。
→ For more details see: aliases | ||||||||||||||||||||||||||||
default | InterfaceText | null | 没有为参数分配值时模板使用的默认值，或其描述。
→ For more details see: default | ||||||||||||||||||||||||||||
autovalue | null | 在wikitext中动态生成的默认值，如今天的日期或编辑用户的名字；这通常涉及wikitext的替换，如{{subst:CURRENTYEAR}}。
→ For more details see: autovalue | |||||||||||||||||||||||||||||
example |
InterfaceText | null |
一份参数的示例文本，以帮助用户填写正确的值。
→ For more details see: example | ||||||||||||||||||||||||||||
type | "unknown" | 参数的类型，用于（软）类型提示。其中之一：
→ For more details see: type | |||||||||||||||||||||||||||||
inherits | 无 被替换 |
另一个参数的名称键（必须是params对象中的一个有效键）。 当前的Param对象将继承指定的Param对象的属性，当前对象的属性将覆盖继承的属性。
→ For more details see: inherits | |||||||||||||||||||||||||||||
suggestedvalues | 包含字符串的数组 | [] |
一个可选的参数属性。 创建一个参数值的列表，以帮助用户选择所需的值。 为了使建议值在可视化编辑器中显示为一个组合框，参数的类型必须设置为以下之一：content、line、string、number、unknown或unbalanced wikitext。
→ For more details see: suggestedvalues |
|
鍵 |
对象或原始类型 |
描述 |
|---|---|---|
label |
InterfaceText | 参数集的（非常）简短的名称。 尽量保持20个字符以下。 |
params |
一个或多个要包含在集合中的参数名称（每个参数必须是params对象中的一个有效键）。 一个参数可以在多个集合中。 不是每个参数都必须在一个集合中。 |
Maps is a single data structure that goes multiple levels deep. It became common to call the second level a “map object”.
| 鍵 | 類型 | 描述 | |
|---|---|---|---|
| 读取机制的名称 | {} | 将读取机制的名称映射到对象，从而将读取机制的名称映射到一个或者多个对应的模板参数的名称。
模板参数的名称可以指定为一个字符串（一个名称）、字符串的数组（多个名称），或者字符串的数组的数组（名称的多个集合）；每个字符串都必要是 一个特定的模板参数可以在多个映射中，可以用于指定映射的多个值，但是并非每个模板参数都必须要在一个映射中。 英文维基百科的Template:Cite_news#TemplateData中的一个简化示例展示了map对象的结构。 {
"proveit": {
"main": "title",
"textarea": [
"quote"
]
},
"citoid": {
"title": "title",
"url": "url",
"publisher": "publisher",
"publicationTitle": "work",
"date": "date",
"ISSN": [
"issn"
],
"ISBN": [
"isbn"
],
"contributor": "others",
"author": [
[
"first",
"last"
],
[
"first2",
"last2"
],
[
"first9",
"last9"
]
],
"editor": [
[
"editor-first",
"editor-last"
]
]
}
}
|
自由格式的纯文本字符串（即没有wikitext或HTML），语言为wiki的内容语言，或包含这些字符串的对象，以语言代码为键。
所有InterfaceText字段的默认值是null。
如果是字符串，则必须包含以本地wiki内容语言编写的非本地化的字符串。
如果它是一个对象，该对象必须有这个映射：
| 鍵 | 類型 | 描述 |
|---|---|---|
| 維基百科語言代碼 | 对应界面语言用户的本地化字符串。 |
对象映射的例子：
| 鍵 | 值 |
|---|---|
| "en" | "Welcome to Wikipedia" |
| "de" | "Willkommen bei Wikipedia" |
| "fr" | "Bienvenue sur Wikipédia" |
| "nl" | "Welkom op Wikipedia" |
| "it" | "Benvenuti su Wikipedia" |
| "es" | "Bienvenidos a Wikipedia" |
| "ru" | "Добро пожаловать в Википедию" |
在模板页面的wikitext中指定的TemplateData结构示例。
<templatedata>
{
"description": "Label unsigned comments in a conversation.",
"params": {
"user": {
"label": "User's name",
"type": "wiki-user-name",
"required": true,
"description": "User name of person who forgot to sign their comment.",
"aliases": ["1"]
},
"date": {
"label": "Date",
"suggested": true,
"description": {
"en": "Timestamp of when the comment was posted, in YYYY-MM-DD format."
},
"aliases": ["2"],
"autovalue": "{{subst:#time:Y-m-d}}"
},
"year": {
"label": "Year",
"type": "number"
},
"month": {
"label": "Month",
"inherits": "year"
},
"day": {
"label": "Day",
"inherits": "year"
},
"comment": {
"required": false
}
},
"sets": [
{
"label": "Date",
"params": ["year", "month", "day"]
}
],
"maps": {
"ExampleConsumer": {
"foo": "user",
"bar": ["year", "month", "day"],
"quux": [
"date",
["day", "month"],
["month", "year"],
"year"
]
}
}
}
</templatedata>
以下是上述例子在模板页面上的显示方式：
Label unsigned comments in a conversation.
| Parameter | Description | Type | Status | |
|---|---|---|---|---|
| User's name | user 1 | User name of person who forgot to sign their comment. | User | required |
| Date | date 2 | Timestamp of when the comment was posted, in YYYY-MM-DD format.
| Unknown | suggested |
| Year | year | no description | Number | optional |
| Month | month | no description | Number | optional |
| Day | day | no description | Number | optional |
| comment | comment | no description | Unknown | optional |
API
见Special:ApiHelp/templatedata生成的帮助。 一个调用示例（为便于人类阅读而格式化）：
这将返回Template:Cite web的模板数据。
这个模板的<templatedata>...</templatedata>块在嵌入其中的模板文档页en:Template:Cite web/doc上。
从API接收的JSON的添加和更改
响应API HTTP获取请求所提供的JSON结构与<templatedata>...</templatedata>块中定义的结构有很大不同。
作为对API请求的回应，TemplateData扩展对JSON对象做了如下修改：
- 添加两个包装对象：
- 对实际的TemplateData对象的添加/更改
API返回的TemplateData JSON对象中的可视化差异
| ||||||
|
| 鍵 | 類型 | 描述 |
|---|---|---|
title |
模板的页面名称（如"Template:Cite web"）。 这个键不包含在模板页面的JSON结构中。 它是由MediaWiki软件在通过API交付的过程中添加到结构中的。 | |
sets |
包含Set对象的数组 | 一个包含集合规范的数组。 一个集合是一组应该一起使用的参数。 如果这在模板页面上不存在，它将作为一个空数组添加到API提供的结构中。 |
| 鍵 | 類型 | 描述 |
|---|---|---|
label | InterfaceText | 转换成InterfaceText对象，如果不是已经是这种格式的话。 |
required | 如果未定义，则添加默认值false。 | |
description | InterfaceText 或 null | 如果定义为字符串，则转换为InterfaceText对象。 如果没有定义，键会被添加，值会被设为null。 |
deprecated | 布尔值或字符串 | 如果没有定义，则添加默认值false。 |
aliases | 如果没有定义，将分配一个默认的空数组（即[]）。 | |
default | 如果未定义，则分配默认值""。 | |
type | 如果未定义，则分配默认值"unknown"。 | |
inherits | （已移除） | 这个键被删除，所有继承的键被添加。 为当前参数定义的键优先，任何未在当前参数或其继承的参数上定义的键都被赋予默认值。 |
| 鍵 | 对象或 原始类型 | 描述 |
|---|---|---|
| （包含以维基百科语言代码为键的本地化字符串） 如果模板页面的TemplateData字段包含一个字符串，而不是带有本地化字符串的对象，那么MediaWiki将其转换为一个InterfaceText对象，其键分配到源Wikipedia维基百科语言代码的名称。 所有InterfaceText字段的默认值是 null。 | ||
| （wiki语言代码） | 对应界面语言用户的本地化字符串。 | |
API提供的JSON对象示例
对于（上面的）示例章节的TemplateData结构，其API请求的响应参见：
- HTML格式：https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData&format=jsonfm
- 由API提供：https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData
| 描述 | ||
|---|---|---|
$wgTemplateDataUseGUI |
true |
实验性对话框界面，用于编辑templatedata JSON |
$wgTemplateDataEditorNamespaces |
[ 10 ] |
The namespaces in which the template data editor appears when creating or editing a page. (T189989) |
$wgTemplateDataMaxFavorites |
50 |
The maximum number of favorite templates that can be stored. (T377460) |
參見
- : – 用于选择和插入模板的wikitext的用户界面，基于它们的TemplateData。
- GitHub: jeblad/TemplateData – 具有一些Lua功能的替代版本。
- Translatable template
- Wikibase/Maps TemplateData
 | 此用于一个或多个维基媒体项目。 这可能意味着足够稳定、运作足够良好，可以用在这样的高流量的网站上。 请在维基媒体的CommonSettings.php和InitialiseSettings.php中查找此的名称以查看哪些网站安装了该。 特定wiki上的已安装的的完整列表位于Special:Version页面。 |
