Extension:TemplateData

**MediaWiki扩展手册**
TemplateData; 发行状态：稳定版
实现	标签, API
描述	允许存储、检索和可视化关于模板的信息
作者	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
最新版本	0.1.2 (持續更新)
兼容性政策	快照跟随MediaWiki发布。 master分支不向后兼容。
MediaWiki	>= 1.42
PHP	5.4+
数据库更改	否
许可协议	GNU通用公眾授權條款2.0或更新版本
下載	下載扩展 ; Git [?]: 下载Git master; 浏览存储库 (Phabricator · GitHub); 提交历史; 存储库貢獻者 (GitHub); 代码复核;
	参数 $wgTemplateDataUseGUI;
	标签 ‎<templatedata>
	使用的函数钩 EditPage::showEditForm:fields; EditPage::showEditForm:initial; MultiContentSave; OutputPageBeforeHTML; ParserFetchTemplateData; ParserFirstCallInit; ResourceLoaderRegisterModules;
季度下載量	266 (Ranked 26th)
正在使用的公开wiki数	6,971 (Ranked 24th)
	前往translatewiki.net翻譯TemplateData扩展
問題	开启的任务 · 报告错误

This page is a translated version of the page Extension:TemplateData and the translation is 97% complete.

Outdated translations are marked like this.

此扩展随附于MediaWiki 1.35及更高版本。因此您无需另外下载。但是，您仍需遵循此页面提供的其他使用说明。

TemplateData扩展引入 ‎<templatedata> 標籤和 API，它们共同允许编辑者指定应如何调用模板并使用对应的参数。这些信息以格式良好的表格形式提供给终端用户，并以 JSON API 的形式提供给其他系统（例如 VisualEditor ），使其能够建立接口，以处理模板。有关深入的帮助，请参阅TemplateData 。

安裝

下载文件，并将其放置在您extensions/文件夹中的TemplateData目录内。
开发者和代码贡献人员应从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在使用模板时不能被正确解析。

请避免使用{{#tag:templatedata}}语法，因为其会导致无法使用模板数据编辑器。

格式

以下内容是JSON数据的视觉化版本，正如包含在‎<templatedata>‎</templatedata>标签的模板页面定义的。格式规定可参考TemplateData。有关最新版本，请参考Specification.md。

TemplateData对象

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等）的简化的名称，映射一个对象，从而将读取机制参数的名称映射到模板参数的一个或者多个对应的名称中。

param对象

鍵类型默认描述

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"

参数的类型，用于（软）类型提示。其中之一：

字符串值	参数类型
"unknown"	没有设置时的假定类型 → For more details see: value ‘unknown’
"number"	任何数值（不含小数点或千位分隔符） → For more details see: value ‘number’
"string"	任何文本值。可包含换行符。 → For more details see: value ‘string’
"line"	短文本字段——用于名称、标签和其他短格式字段。这应该是不期望包含换行符的文本。 → For more details see: value ‘line’
"boolean"	一个布尔值（1代表true，0代表false，''代表未知），见三值逻辑。 → For more details see: value ‘boolean’
"date"	一个ISO 8601格式的日期，如2014-05-09或2014-05-09T16:01:12Z。 → For more details see: value ‘date’
"url"	一个URL，包括协议，如"http://www.example.org", "https://example.org",或"//example.org"。 → For more details see: value ‘url’
"wiki-page-name"	当前wiki的一个有效的MediaWiki页面名称。不一定要存在，但如果不存在，应该是一个有效的页面名称，可以创建。 → For more details see: value ‘wiki-page-name’
"wiki-file-name"	当前wiki的一个有效的MediaWiki文件名。不一定要存在，但如果不存在，应该是一个有效的文件名，可以上传。不应包括命名空间（如"Foo.svg"而非"File:Foo.svg"或"Bild:Foo.svg"）。 → For more details see: value ‘wiki-file-name’
"wiki-template-name"	当前wiki的一个有效的MediaWiki模板名称。 → For more details see: value ‘wiki-template-name’
"wiki-user-name"	当前wiki的一个有效的MediaWiki用户名。不一定要存在，但如果不存在，应该是一个有效的用户名，可以创建。不应包括命名空间（如"Foo"而非"User:Foo"或"Usario:Foo"）。 → For more details see: value ‘wiki-user-name’
"content"	wikitext格式的页面内容，如文本样式、链接、图像等。 → For more details see: value ‘content’
"unbalanced-wikitext"	不应作为独立内容处理的原始wikitext，因为它是不平衡的——例如，模板将不完整的wikitext串联成一个更大的整体，如`{{echo\|before=<u>\|after=</u>}}`。 → For more details see: value ‘unbalanced-wikitext’

→ 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

set对象

鍵	对象或原始类型	描述
`label`	InterfaceText	参数集的（非常）简短的名称。尽量保持20个字符以下。
`params`	字符串数组	一个或多个要包含在集合中的参数名称（每个参数必须是`params`对象中的一个有效键）。一个参数可以在多个集合中。不是每个参数都必须在一个集合中。

Maps对象

Maps is a single data structure that goes multiple levels deep. It became common to call the second level a “map object”.

鍵	類型	默认	描述
读取机制的名称	对象	{}	将读取机制的名称映射到对象，从而将读取机制的名称映射到一个或者多个对应的模板参数的名称。模板参数的名称可以指定为一个字符串（一个名称）、字符串的数组（多个名称），或者字符串的数组的数组（名称的多个集合）；每个字符串都必要是`params`对象中的可用的键，或者在同一个模板的TemplateData的其他地方。一个特定的模板参数可以在多个映射中，可以用于指定映射的多个值，但是并非每个模板参数都必须要在一个映射中。英文维基百科的Template:Cite_news#TemplateData中有一个简短的例子，展示了这种映射对象的结构。 { "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" ] ] } }

InterfaceText（字符串或对象）

自由格式的纯文本字符串（即没有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.

Template parameters
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. Auto value `{{subst:#time:Y-m-d}}`	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生成的帮助。一个调用示例（为便于人类阅读而格式化）：

api.php?action=templatedata&titles=Template:Cite%20web&format=json [在Api沙盒中尝试]

这将返回Template:Cite web的模板数据。这个模板的‎<templatedata>...‎</templatedata>块在嵌入其中的模板文档页en:Template:Cite web/doc上。

从API接收的JSON的添加和更改

响应API HTTP获取请求所提供的JSON结构与‎<templatedata>...‎</templatedata>块中定义的结构有很大不同。作为对API请求的回应，TemplateData扩展对JSON对象做了如下修改：

添加两个包装对象：
1. 一个总体的Pages对象，包含一个或者多个Page对象
2. 带有数字键的对象：Page对象
对实际的TemplateData对象的添加/更改
1. 加入title键，其值为请求数据的页面名称（如"Template:Cite web"）。
2. 添加sets键
3. 将TemplateText所有以字符串形式出现的地方改为对象，其唯一键为当前wiki的维基百科语言代码。
4. 删除所有inherits键。
  - 添加来自定义了继承关系的参数的所有属性，这些属性没有被继承者的Param对象中明确定义的键所取代。
5. 为每个Param对象中没有明确定义或继承的所有键添加默认值。

API返回的TemplateData JSON对象中的可视化差异

JSON根元素
鍵	類型	描述
`pages`	Page对象	Page对象（包含一个键，这个键为页面序号）。如果一次请求了多个页面，那么会有多个Page对象。

Page对象
鍵	類型	描述
(頁碼)	TemplateData对象	TemplateData对象，包含信息的有效载荷。键是JSON数据请求的模板页面的静态页面序号。

TemplateData对象（由API添加）
下面的键被添加到JSON对象的根元素中，该对象在模板页面上被包裹在`‎<templatedata>`标签中。
鍵	類型	描述
`title`	字符串	模板的页面名称（如"Template:Cite web"）。这个键不包含在模板页面的JSON结构中。它是由MediaWiki软件在通过API交付的过程中添加到结构中的。
`sets`	包含Set对象的数组	一个包含集合规范的数组。一个集合是一组应该一起使用的参数。如果这在模板页面上不存在，它将作为一个空数组添加到API提供的结构中。

来自API的Param对象
鍵	類型	描述
`label`	InterfaceText	转换成InterfaceText对象，如果不是已经是这种格式的话。
`required`	布尔值	如果未定义，则添加默认值false。
`description`	InterfaceText 或 `null`	如果定义为字符串，则转换为InterfaceText对象。如果没有定义，键会被添加，值会被设为`null`。
`deprecated`	布尔值或字符串	如果没有定义，则添加默认值false。
`aliases`	字符串数组	如果没有定义，将分配一个默认的空数组（即[]）。
`default`	字符串	如果未定义，则分配默认值""。
`type`	字符串	如果未定义，则分配默认值"unknown"。
`inherits`	（已移除）	这个键被删除，所有继承的键被添加。为当前参数定义的键优先，任何未在当前参数或其继承的参数上定义的键都被赋予默认值。

InterfaceText（对象或`null`）：
一个对象，其包含的字符串以语言代码为键。
鍵	对象或原始类型	描述
对象（包含以维基百科语言代码为键的本地化字符串）如果模板页面的TemplateData字段包含一个字符串，而不是带有本地化字符串的对象，那么MediaWiki将其转换为一个InterfaceText对象，其键分配到源Wikipedia维基百科语言代码的名称。所有InterfaceText字段的默认值是`null`。
（wiki语言代码）	字符串	对应界面语言用户的本地化字符串。

API提供的JSON对象示例

对于（上面的）示例章节的TemplateData结构，其API请求的响应参见：

配置

变量	默认	描述
`$wgTemplateDataUseGUI`	`true`	实验性对话框界面，用于编辑templatedata JSON

參見

Extension:模板精灵 – 用于选择和插入模板的wikitext的用户界面，基于它们的TemplateData。
GitHub: jeblad/TemplateData – 具有一些Lua功能的替代版本。
Translatable template
Wikibase/Maps TemplateData

此扩展用于一个或多个维基媒体项目。这可能意味着扩展足够稳定、运作足够良好，可以用在这样的高流量的网站上。请在维基媒体的CommonSettings.php和InitialiseSettings.php配置文件中查找此扩展的名称以查看哪些网站安装了该扩展。特定wiki上的已安装的扩展的完整列表位于Special:Version页面。

此扩展在以下wiki农场/托管网站和/或软件包中提供：

這不是一份權威名單。即使某些wiki农场/托管网站和/或软件包未在这里列出，它们也可能提供此扩展。请检查你的wiki农场/托管网站或软件包以确认提供情况。