Help:TemplateData/zh

是一个扩展，用于存储与wikitext模板相关的信息和参数，并使其可用于编辑界面，可以在模板编辑器中检索及呈现——所有这些都有助于用户在页面上添加和编辑模板.

自2019年4月起，模板数据功能已是維基媒體裏所有wiki上的所有用戶在添加模板時，默認的用戶體驗的一部分，即使是未註冊的用戶也一樣. 默认的代碼和可视化编辑器此二者，都以某種型式將其納入其中，如同许多脚本、工具軟體和小工具的做法一樣. 如果你想在自己的wiki上也实现这一功能，请安装.

要将模板数据添加到模板內以供此扩展使用时，需要在模板的文档页面中插入一个小而简单的JSON（會在下文解释）區块. 您可以手动执行此操作，也可以使用模板数据编辑器，这是一个图形用户界面，在安装了TemplateData扩展的wiki中，你可以在模板的「」/「」页面裏访问. JSON包含模板的参数列表，以及关于这些参数以及整个模板的信息（详见下文）.

当用户添加某個模板时，那些包含模板数据的模板将在用户界面中显示此信息. 在某些情况下，当您使用编辑器编辑或插入一個指定的模板时，它将改变编辑器的行为方式，讓用户可以更轻松地执行添加某個指定模板所需的步骤.

歷史
模板数据最初是在2013年初开发的，且已考虑到，当时正处于MediaWiki测试阶段. 可视化编辑器是维基媒体维基的主要的视觉编辑界面，模板数据使其在添加模板时有一个更有用的界面， 它立即被可视化编辑器正式支持. 从2013年到2016年，随着可视化编辑器作为默认功能被推广到各个主要的维基媒体的wiki中，模板数据也成为了它们的一部分.

2016年12月，作为是一项测试功能，可视化编辑器界面可用于编辑源代码， 称为. 这首次将模板数据的特点带到了源代码编辑中.

2018年3月，Sam Wilson开发了，这是默认的维基媒体源码编辑器（也就是2010年的wikitext编辑器）的GUI模板编辑器扩展，旨在通过使用模板数据的信息使添加模板的过程更容易. 在2019年4月，TemplateWizard被列为所有维基媒体的wiki上的2010年wikitext编辑器的默认部分. 这意味着模板数据现在是维基媒体的wiki上可视化编辑器和源码编辑器的一个默认部分.



添加或编辑模板數據
要添加或编辑模板数据，首先导航到模板的页面，它位于「/Template:Templatename」.



检查目前的状态
在添加或编辑模板数据之前，请检查该模板是否有文档子页面. 然后检查模板是否已经包含模板数据，如果是，它是位于模板页面还是在文档子页面上.



文档子页面
大多数维基媒体维基上的模板有两种主要的方式来存储他们的使用说明和其他不应该包含在实际模板本身的数据，比如模板应该包含的类别：


 * 绝大多数模板将使用说明和其他不属于模板页本身的数据放在文档子页上：「/Template:Templatename/doc」. 在这样的页面上，{{}}的模板将所有的/doc页面的内容都嵌入包含在模板页面上，使模板的源代码更加简洁.
 * 在有文档子页面的模板上，「Test Template Info-Icon - Version (2).svg模板文档」标题后面会有[查看]、[编辑]、[历史]和[刷新缓存]等链接.


 * 少数模板页面在模板的主页面上保留了该信息. 在这些页面上，你可以通过寻找标签之间出现的 来发现它.

不同的wiki可能会以不同的方式呈现这一切. 極其罕见的情況，即使你已经检查了上述所有内容，主模板页面仍然包含著文档； 就像这里，一个用户已經在「 」和 「 」之间添加一个自定义的/doc页面标题，然后又在「 」之后添加内容.

你也可以在页面底部寻找类似这样的通知：「上述文档是从Template:Templatename/doc中嵌入的」.



没有文档子页面的模板
如果一个模板没有文档子页，就创建它并将模板的文档移到那里（或一个占位符）. 然后你可以把模板数据添加到文档子页.



创建子页面并移动文档
要创建文档子页，在主模板页面上点击「」/「」；寻找的标签及其内容（通常在底部）.

它应该看起来像这样：

你可能也发现它已经包含了模板数据. 如果是这样，它看起来会像这样：

选择「 」之后、「」之前的所有内容，并将其剪切到剪贴板上或保存在一个临时文件中. 删除「 」，只留下以下内容.

保存模板页面.

现在，要创建新的子页面，请看你的浏览器的地址栏，在URL的末尾加上/doc. 按Enter，然后选择创建一个新页面的选项.

如果这个wiki有一个{{}}的通知模板，把它加在新页面的顶部. 你也可能希望添加其他模板，例如{{}}或{{}}的链接（如果有关的wiki支持的话）. 查看元維基:帮助:模板文档获取更多信息

插入你在前面的文本中剪切或保存的文本（如果有的话，是在通知模板的下面）.

用标签包裹任何类别，使它们只适用于模板的主页面：

许多的wiki都有一个 的模板. 如果你要编辑的模板很可能存在沙盒版本（位于 「Template:Templatename/sandbox」），请在此使用该模板，以防止类别应用于沙盒页面：

最后，发布该页面.

现在你可以使用#方法中所描述的指导，在文档子页上添加和编辑模板数据.



在主模板页面上添加和编辑模板数据
如果你不能创建/doc页面，你可以按照#方法中的指导，在模板的主页面添加和编辑模板数据.

如果一个模板有一个文档子页，则同时检查主页面和文档子页是否存在模板数据（标签后面是一个大括号内的数组： ）.

另一種擇，TemplateData扩展可以幫你执行这一检查. 在任何一页上点击「」或「」. 如果模板在任何一个页面上已经有了模板数据，你会在页面的顶部看到一个黄色的通知，上面写着的，是：



或者

如果模板在其文档子页上有模板数据

如果该模板在其文档子页面上有模板数据，那么你应该去编辑这个文档子页面. 你可以通过点击位于标题「模板文档」（或类似的）之后的 "[编辑] "来实现，或者，如果你已经在/doc页面上，点击顶部的「」或「」. 按照#方法的指导，添加或编辑模板数据.

如果模板在其主页面上有模板数据

如果模板在其主页面上有模板数据，你再次有两个选择：


 * 要麼，你可以移动到它的文档子页. 这是首选方案.


 * 要麼，你可以在主模板页面上编辑它.

将模板数据移至文档子页

要做到这一点，请在主模板页面上点击 「」/「」，并寻找的标签，将其包在的标签中. 它应该看起来像这样：

只把的标签和它们的内容从代码中剪掉，然后保存页面.

接下来，通过点击位于标题「模板文档」（或类似）之后的“[编辑]”来编辑文档子页.

输入一个标题，如「模板数据」，然后在其下方粘贴模板数据.

你现在可以根据#方法的指导编辑模板数据.

在主模板页上编辑模板数据

如果你不希望把模板的数据移动到/doc页面，你可以在模版的主要页面上编辑它 参见#方法以学习如何编辑模板数据.

如果这个模板还没有模板数据但是有一个doc子页面

如果这个模板还没有模板数据，你应该将其添加到文档子页面.

你可以通过点击位于标题“模板文档”（或类似的）之后的 “[编辑] ”来实现，或者，如果你已经在/doc页面上，点击顶部的“”或“”. 输入一个标题，如“模板数据”，然后在其下方粘贴模板数据. #方法章节解释了如何编辑模板数据.

方法


模板數據編輯方法
这是添加或编辑模板数据的一个简单的方法，推荐经验不足的用户使用.

模板数据编辑器是一个图形化的编辑器，可用来添加或编辑模板数据. 这是 TemplateData 拓展的一个片段，点击“”或“”能用于所有的模板页面（或文档子页面）.

点击“”或“”后，你将会看到编辑区上面的一个按钮和标题页面“”.

|453px

點擊該按鈕就可以進入模板數據編輯器. 如果您所在的頁面已經包含了模板數據，則會自動顯示在這裡.

600px|模板数据编辑工具在尚无模板数据的页面.

上述窗口中的功能：


 * 顶部项目选择界面文本的语言. 它允许您输入多种语言的文本内容，根据用户在首选项中的设置向用户显示，不基于wiki的语言；不同的维基有完全不同的模板数据库. 如果不存在语言模板数据，界面将仅向用户提供wiki自己的语言，但用户可以单击“”添加更多输入.  语言代码将会显示在可以应用它的参数旁边的括号中，例如描述和标签.
 * 下一项是模板说明. 这是整个模板的描述;添加模板时，它会在模板编辑器中的许多位置向用户显示. 此参数及其效果概述在此处.
 * 第三项控制模板的维基文本格式. 此参数确定当用户点击“”时wiki文本的布局方式，两种主要类型是 （在一行上）和 （在新行上）. 此参数及其效果概述在此处.
 * 如果用户选择了“”，那么他们可以自定义列出的以下规则，在“”中输入wikitext，然后点击“”，以创建模板的一个自定义的布局.


 * 第4项配置了模板的参数. 如果模板数据中已经定义了参数，那么此区域会以列表显示这些参数.  如果模板的源代码指定了模板数据中还不存在的参数，你可以看到“”按钮.  编辑器会在模板的源代码中寻找 或 ，然后导出这些建议.  点击会添加这些参数，使用其在源代码中定义的名称.  顶部将会出现一个绿色的通知，例如“”
 * 在窗口的底部，你会看到一个“”按钮，这可以让你手动添加一个自定义名称的参数.

点击列表中的任意一个参数，进入下一步，然后就可以编辑参数的信息.

600px

#参数名称内一节会介绍所有这个功能以及其效果.

完成后，点击“”. 这会自动将模板数据插入到页面底部，标签之前，或者，如果已经存在，则会更新其内容而不改变其位置. 点击“”，模板数据文本也会被选中.

模板数据编辑器会在模板数据的底部创建一个 参数（或者，如果已经存在，则更新这个参数）. 包含了当前的模板数据参数，按照在模板数据编辑器中显示的顺序出现. 你哥心在模板数据编辑器中，使用左侧的三个横线图标，将其向上或者向下拖动，以改变. 及其影响记录如下.

然后，点击“”以保存更改.



手动方法
你也可以手动添加和编辑模板数据. 模板数据是用JSON编写的，但你并不需要学习JSON就可以学习如何创建模板数据. 模板数据遵循少量简单的规则，仅接收少量可行的预定义的参数和值，基本上是 的格式.

手动添加模板数据

需要考虑的地方：


 * 如果你是在模板的文档子页面添加模板数据（推荐这么做），你可以添加到页面的任何地方；检查你所使用的语言的维基百科有没有推荐把模板数据存放在哪个地方. 例如，在英语维基百科，模板数据通常接近文档页面的底部，而在德语维基百科，通常在顶部.
 * 如果你是在模板的主页面（不推荐这么做，请看#优先检查），你必须确保其在标签内.

点击“”或“”，然后移到到你需要添加模板数据的地方，添加一个章节标题：“模板数据”.

很多wiki都有个TemplateData header模板，添加一个关于模板数据的短的提示. 如果你有wiki有，可以在标题后添加一个.

要开始添加模板数据，输入一个开头的模板，以及在新的一行上的一组花括号，中间空一行.

然后，在两个花括号之间的空行上添加缩进，开始添加参数. 参数的细节请参见#模板数据参数. 大多数都是可选的，有些是强烈推荐使用的.

参数可以是任何顺序，但是下面的是符合模板数据文档且让读者更加容易使用的顺序.

确保参数，例如在 对象内，保持在这个对象中. 否则，保存时就会触发“”.



下面是个假设的清理模板的一些示例模板数据. 此类模板将显示一条通知，并根据输入的月份和年份将页面放入带有日期的类别中. 这个通知可能还包含一个讨论页章节的链接. 模板数据看上去应该会是这样子：

对应的模板数据看起来会像是这样子：

{	"description": "使用此模板以表示一篇文章需要清理. ", "format": "inline", "params": { "date": { "label": "月份和年", "description": "添加模板的月份和年", "type": "string", "autovalue": " ", "example": "2023年1月", "suggested": true },		"reason": { "aliases": ["1"], "label": "原因", "description": "文章需要清理的原因", "type": "string" },		"talk": { "aliases": ["talksection"], "label": "讨论页章节", "description": "包含有关讨论的讨论页章节", "type": "string" }	},	"paramOrder": [ "date", "reason", "talk" ] }



模板数据参数
下面列举出了所有可用的模板数据参数，以及其描述和示例. 扩展:TemplateData#格式中更新详细地列举出了一些技术细节.



在参数内


在参数名称中
注意：如果对于一个参数， 、 和 都没有设置为 ，那么其状态在模板数据文档中会显示为 （可选）.

一旦您完成，点击“”即可. 如果出现了错误，它将不会让您保存（这或许是破坏，但意思是您不能损坏任何东西）. 如果您遇到错误，在反馈页面介绍您要尝试进行的操作，并且我们将很高兴帮助.

注意：如果你在滥用一个hack模板以动态地生成模板数据，那么保存之前无法检查错误.

请注意：信息的每项都被引号包围（ 和 除外），且并用逗号与下一项分开（除非这是最后一个）.



类型参数
参数控制可视化模板编辑器如何解读参数. 在有些情况下，模板的编辑器被编写为，根据这个模板数据的值，这特定的参数修改用户界面，例如仅允许用户输入符合指定类型的有效值. 这个参数在其模板数据或值上没有实际效果，只控制了模板编辑器在编辑模式中如何看待和对待这个参数.

如何使用

用法就是，添加 参数，然后是冒号和空格，然后在引号中添加下表中列举出的任何一个值.

例如：

效果

在2020年2月，13个类型中只有5个是在可视化编辑器和2017版wikitext编辑器中有可见的效果的，8个在TemplateWizard中有可见的效果.

特定值的效果可能会随模板编辑器的更新以支持而改变. 其中，可视化编辑器和2017版wikitext编辑器的努力可以在Phabricator任务T55613中追踪到. 类似的使TemplateWizard支持布尔值的努力是在T200664中追踪的.

下面列举了当前已知的效果.

自定义格式
编辑 值时，你通过输入一组使用预定义的规则的wikitext符号来创建自定义的格式.


 * - 模板的开始
 * - 内容（例如：字符串、整数或参数）. 下划线用于表示字符的值的最小长度，可以重复，就像 .  如果长度不足，就会用空格填充剩余的字符.  这可以用来将等号对齐于参数后的指定的位置（如果使用了 以表示新行）.
 * - 管道符（分隔参数）
 * - 等号（接参数的值）
 * 或者按下enter键 - 新行（这会在entry字段中显示为 ）
 * - 空格（可以和 一起使用以给新行缩进）
 * - 模板的结束

wikitext至少应该符合最小的 ，否则会是无效字符串错误.



空白样板
您可以复制下面的空白样板来向模板中添加新的模板数据，只包含了最常见的标签.

错误


/糟糕的JSON格式
这个错误通常发生在可视化编辑器中，保存模板数据时，通常是手动编辑，且有无效的JSON代码（重复的键或值、多余或者缺失的逗号，等等）.

可视化编辑器中会出现“”；在模板数据GUI编辑器中编辑时会出现“Bad JSON format”.

这个错误不易检测到，且形式多样，无法列举. 要避免出现这种错误，最好的方式就是仅使用模板数据编辑器进行编辑，最好的一次检测是否存在错误的方式就是使用外部的JSON检查器，例如JSONLint，它可以高亮出错误并尝试将其修复.

2010版wikitext编辑器不会检查无效的JSON，这是由于一个老的、未修复的bug（）. 包含无效JSON的页面可能会抛出“”的消息. 要将其修复，最好使用JSON验证器（参见上方）.

这个错误发生在，如果你在 中声明了一个参数，但是在 中没有声明. 方括号中的数字代表了 中缺失的参数，指的是在序列中的顺序，但是比实际的位置少1，因为 是数组，0是第一个，1是第二个，等等.

要将其修复，确保 中声明的所有的参数都列举在了 中. 此外，你也可以移除掉整个 对象以消除这个错误.

这个错误发生在，如果你在 中声明了一个参数，但是在 中没有声明. 方括号中的数字代码了 中不应该有的参数，指的是序列中的顺序，但是比实际的位置少1，因为 是数组，0是第一个，1是第二个，等等.

要将其修复，确保 中声明的所有的参数都列举在了 中. 此外，你也可以移除掉整个 对象以消除这个错误.

这个错误发生在，如果你在 或 的值中使用了引号.

它们是布尔值，而不是字符串，因此不需要引号. 要修复这个，移除掉这些参数的 或 旁的引号.

<span id="Property_&quot;format&quot;_is_expected_to_be_...">

属性format应该是…（Property "format" is expected to be ...）
如果 参数存在，但是其值不是 、 或者有效的格式字符串，你会看到错误消息“”.

要修复这个，确保 之后的所有参数都等于 或 ，且没有拼写错误. 此外，如果是在wikitext中，确保至少包含最小的 ，语法没有通常会导致模板失败的错误，例如多余的等号或者缺失、重复的花括号. 自定义格式的语法请参见#自定义格式. 此外，你也可以移除掉 参数以消除这个错误.

如果你声明了模板数据中的一个未知参数将会发生错误. 这很可能是由于拼写错误或用了大写字母而非小写字母.

此外，还可能会发生在，你在任何模板数据对象中声明了一个参数，但这个参数不是该对象中的参数的情况. 这可能是由于拼写错误，或者你写了另一个对象中的模板数据对象中的参数，而参数不属于那个对象.

例如，你可能将参数 写到了根模板数据对象中，而不是在 内：

如果未知的参数是在 内的模板参数中的，你会在错误中的“params.参数名称”后面看到其名称.

要修复这个问题，确保参数名称没有任何的拼写错误，确保你的参数都在正确的位置. 此外，确保你没有在模板数据对象中，声明任何不存在的参数. 你可以在章节#模板数据参数中检查对象中有哪些参数是存在的.

这个错误发生在，模板数据是没有 对象. 这个对象是必需的，包含每个参数的所有细节，所以要修复这个错误，确保它已经添加，且没有拼写错误. 关于如果添加 参数，请参考上方的段落.

<span id="Limitations_and_feedback">

局限和反馈

 * 缺失功能 – 模板数据是用于提供很少的功能的工具的例子，希望用户将有助于指导他们想要的功能的开发. 如果您想要请求模板数据的新功能，请让我们知道.
 * 模板显示延迟 – 将模板数据添加到模板后，在可视化编辑器中打开模板时，元数据应立即可见. 但是，可能需要几个小时的时间才会显示元数据. 您可以通过对模板页面本身（而不是文档子页面）进行空编辑来强制更新. 要执行空白编辑，请打开模板页面进行编辑，并保存页面，而不进行任何更改，也不添加任何编辑摘要.
 * 现有问题 – 现有问题（bug）和特性请求可在Wikimedia错误追踪系统找到.

<span id="Other_tools">

其它工具

 * : 工具栏对话窗口，用于通过由模板数据构建的表单来输入模板wikitext.
 * TemplateData Wizard: 通过交互式界面生成模板信息的工具.
 * Skeleton TemplateData generator: 读取模板源wiki代码的工具，尝试寻找使用的所有参数，并按列出的参数输出纲要文档.
 * JSONLint: 允许您验证手动写入的JSON以帮助查找语法中的错误的工具.
 * 此wiki上的[ 所有带模板数据的模板列表]
 * 使用dewiki template TemplateData：模板数据显示在框中，且该模板被添加到有模板信息的分类当中.
 * https://query.wikidata.org/和Query Helper