Extension:TemplateData
 发行状态： 稳定版 |
|
|---|---|
 |
|
| 实现 | 标签, API |
| 描述 | 允许存储、检索和可视化关于模板的信息 |
| 作者 | Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ... |
| 最新版本 | 0.1.2 (持續更新) |
| 兼容性政策 | 快照跟随MediaWiki发布。 master分支不向后兼容。 |
| PHP | 5.4+ |
| 数据库更改 | 否 |
| 许可协议 | GNU通用公眾授權條款2.0或更新版本 |
| 下載 | |
|
|
<templatedata> |
|
| 季度下載量 | 275 (Ranked 16th) |
| 正在使用的公开wiki数 | 6,971 (Ranked 24th) |
| 前往translatewiki.net翻譯TemplateData扩展 | |
| 問題 | 开启的任务 · 报告错误 |
TemplateData扩展引入 <templatedata> 標籤和 API，它们共同允许编辑者指定应如何调用模板并使用对应的参数。
这些信息以格式良好的表格形式提供给终端用户，并以 JSON API 的形式提供给其他系统（例如 VisualEditor），使其能够建立接口，以处理模板。
有关深入的帮助，请参阅TemplateData。
安裝
- 下载文件，并将解压后的
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在使用模板时不能被正确解析。
请避免使用{{#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" |
参数的类型，用于（软）类型提示。其中之一：
→ 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”.
| 鍵 | 類型 | 默认 | 描述 |
|---|---|---|---|
| 读取机制的名称 | 对象 | {} | 将读取机制的名称映射到对象，从而将读取机制的名称映射到一个或者多个对应的模板参数的名称。
模板参数的名称可以指定为一个字符串（一个名称）、字符串的数组（多个名称），或者字符串的数组的数组（名称的多个集合）；每个字符串都必要是 一个特定的模板参数可以在多个映射中，可以用于指定映射的多个值，但是并非每个模板参数都必须要在一个映射中。 英文维基百科的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.
| 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) |
參見
- Extension:模板精灵 – 用于选择和插入模板的wikitext的用户界面，基于它们的TemplateData。
- GitHub: jeblad/TemplateData – 具有一些Lua功能的替代版本。
- Translatable template
- Wikibase/Maps TemplateData
| 此扩展用于一个或多个维基媒体项目。 这可能意味着扩展足够稳定、运作足够良好，可以用在这样的高流量的网站上。 请在维基媒体的CommonSettings.php和InitialiseSettings.php配置文件中查找此扩展的名称以查看哪些网站安装了该扩展。 特定wiki上的已安装的扩展的完整列表位于Special:Version页面。 |
| 此扩展在以下wiki农场/托管网站和/或软件包中提供： 這不是一份權威名單。 即使某些wiki农场/托管网站和/或软件包未在这里列出，它们也可能提供此扩展。 请检查你的wiki农场/托管网站或软件包以确认提供情况。 |