Extension:TemplateData/zh

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

安裝


-{zh-hans:编辑数据; zh-hant:編輯資料;}-
TemplateData扩展会在模板页面的wikitext中定义标签（当然也可以是从其他页面嵌入包含的），从而实现效果. 这种设计是为了兼容很多wiki都有的常见布局，即嵌入包含一个单独的文档页面（但不是必需的）. 的内容必须是有效的JSON，其格式如下所示，注意所有的描述必须是纯文本（模板数据中不接受wikitext）.

页面包含块时，TemplateData会在页面保存时，做出以下检查：


 * 1) 内容必须是有效的JSON；
 * 2) JSON结构中的每一项必须是下文指定的预设类型（例如对象、数组或原始类型）；
 * 1) 对于那些具有指定的可能的值的列表（例如 ）的项，JSON对象中的值必须与这些值中的某一种相匹配.

如果这些检查中的任何一项失败，服务器将不允许用户保存，并且将在编辑页面的上方显示错误消息.

对于自动值的像，bug 2700使得 无法在任何添加到$3（包括和标签）的模板中生效. TemplateData在这种情况下不会阻止保存，但最终的wikitext在使用模板时不能被正确解析.

注意不能使用 替代Special:MyLanguage/Help:TemplateData#Template data editor method.

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



-{zh-hans:TemplateData对象; zh-hant:TemplateData物件;}-
TemplateData对象是一个“JSON根元素”，包含在模板页面的元素中.



-{zh-hans:param对象; zh-hant:param物件;}-


-{zh-hans:set对象; zh-hant:set物件;}-


-{zh-hans:Maps对象; zh-hant:Maps物件;}-


-{zh-hans:InterfaceText（字符串或对象）; zh-hant:InterfaceText（字符或物件）;}-
自由格式的纯文本字符串（即没有wikitext或HTML），语言为wiki的内容语言，或包含这些字符串的对象，以语言代码为键.

所有InterfaceText字段的默认值是.



-{zh-hans:字符串类型; zh-hant:字串類型;}-
如果是字符串，则必须包含以本地wiki内容语言编写的非本地化的字符串.



-{zh-hans:对象类型; zh-hant:物件類型;}-
如果它是一个对象，该对象必须有这个映射：

-{zh-hans:示例; zh-hant:範例;}-
在模板页面的wikitext中指定的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": "" },       "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" ]       }    } }

API
见Special:ApiHelp/templatedata生成的帮助. 一个调用示例（为便于人类阅读而格式化）：

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



从API接收的JSON的添加和更改
响应API HTTP获取请求所提供的JSON结构与块中定义的结构有很大不同. 作为对API请求的回应，TemplateData扩展对JSON对象做了如下修改：


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



API返回的TemplateData JSON对象中的可视化差异
<span id="Example_of_JSON_object_provided_by_API">

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

-{zh-hans:配置; zh-hant:組態;}-
<span id="See_also">

參見

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