Help:TemplateData/zh

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

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

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

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

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

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

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



添加或编辑模板數據
要添加或编辑模板数据，首先导航到模板的页面，它位于「/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页面，你可以在模版的主要页面上编辑它 参见 #Methods 以学习如何编辑模板数据.

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

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

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

方法


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

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

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

|453px

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

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

上述窗口中的功能：


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


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

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

600px

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

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

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

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



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

手动添加模板数据

需要考虑的地方：


 * If you're adding template data on a template's documentation subpage (recommended), you may add it anywhere on the page; check to see if your language's Wikipedia has a preferred location for it. For example, on the English Wikipedia, template data is typically near the bottom of the documentation page; on the German Wikipedia, it is typically at the top.
 * If you're adding template data on a template's main page (not recommended; see #Prior checks), you must make sure to place it inside the  tags.

Click "" or "" on the respective page, then move to the place in the page where you intend to add template data and write a heading: "Template data".

Many wikis have a TemplateData header template that adds a short notice regarding template data. If your wiki does, add it after the heading.

To start adding template data, type an opening and closing tag and a pair of curly brackets on new lines, with an empty line between them:

Next, add an indent on the empty line between the two curly brackets, and start adding parameters. Details for the parameters can be found at #Template data parameters. Most are optional; some are highly recommended.

Parameters can be in any order, but what follows is the order that best conforms to template data documentation and makes the content easiest to use for editors:

Make sure the parameters, for example, in the  object, remain inside that object; otherwise you will trigger an "" error when you try to save.

-{zh-hans:示例; zh-hant:範例;}-

Here is some example template data for a hypothetical cleanup template. Such a template would display a notice and place the page into a dated category based on the month and year entered. The notice might also contain a link to a talk page section. The template data would look something like this:

The corresponding template data documentation would display as follows:

{	"description": "Use this template to indicate that an article is in need of cleanup.", "format": "inline", "params": { "date": { "label": "Month and year", "description": "The month and year that the template was added", "type": "string", "autovalue": " ", "example": "January 2013", "suggested": true },		"reason": { "aliases": ["1"], "label": "Reason", "description": "The reason the article is in need of cleanup", "type": "string" },		"talk": { "aliases": ["talksection"], "label": "Talk page section", "description": "The section of the talk page containing relevant discussion", "type": "string" }	},	"paramOrder": [ "date", "reason", "talk" ] }



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



在参数内


在参数名称中
Note: if neither,   nor   are set as   for a parameter, its status will show as   in the template data documentation.

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

Note that if you are abusing a hack template to dynamically generate template data, it cannot be checked for errors before saving.

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



类型参数
参数控制可视化模板编辑器如何解读参数. In some cases, template editors have been programmed to modify the user interface for a certain parameter according to this template data value, such as to only allow the user to enter valid values that match the specified type. This parameter does not have any functional effect on the template parameter or its value; it merely controls how template editors see and treat the parameter in editing mode.

How to use

It is used by adding the  parameter, followed by a colon and a space, then adding any of the values listed in the table below in quotation marks.

Example:

Effects

As of February 2020, only 5 of the 13 type values have visible effects in VisualEditor and the 2017 wikitext editor, while 8 have visible effects in TemplateWizard.

The effects of certain values are likely to change as the template editors get updates to support them. One such effort for VisualEditor and the 2017 wikitext editor is tracked in the Phabricator task T55613. A similar effort to get TemplateWizard to support the boolean value is tracked in T200664.

The currently known effects are listed as follows.

自定义格式
When editing the  value, you create custom formats by inputting a set of wikitext symbols using some predefined rules.


 * - start of the template
 * - content (e.g., string, integer or parameter). This underscore serves to indicate the minimum length of a value in characters and can be repeated, like . If this length is not reached, it fills the remaining characters with spaces. This can be used to align all equals signs to a specific position after a parameter (if used with   for new lines).
 * - pipe (separates parameters)
 * - equals sign (precedes the value of a parameter)
 * or pressing the enter key - new line (this will display as  in the entry field)
 * - space (can be used with  to indent new lines)
 * - end of the template

The wikitext should at least meet the minimum of, otherwise there will be an invalid format string error.



空白样板
您可以复制下面的空白样本来向一个模板中添加新的模板信息. 只包含最常见的标签.

错误


/糟糕的JSON格式
These errors occur when saving template data, usually manually edited, with invalid JSON code (duplicate keys/parameters, trailing or missing commas, etc.) in the visual editor or the 2017 wikitext editor.

"" appears in the visual editor and the 2017 wikitext editor; "Bad JSON format" appears when editing in the template data GUI editor.

These errors can be difficult to detect and come in too many forms to list. The best way to avoid them is to edit template data exclusively with the template data editor; the best way to detect them once they've occurred is to use an external JSON validator, such as JSONLint, which will highlight errors and aid in fixing them.

The 2010 wikitext editor does not check for invalid JSON thanks to an old, unfixed bug. Pages that contain invalid JSON may throw alarming "" messages. To fix these errors, your best bet is to use a JSON validator (see above).

This error occurs if you state a parameter in  that is not stated in. The number in the square brackets refers to the parameter in  that is missing. It refers to its order in the sequence, but it is one less than its actual position, since  is an array; 0 is the first one, 1 is the second, etc.

To fix this, make sure all parameters stated in  are listed in. Alternatively, you can remove the  object to remove this error.

This error occurs if you state a parameter in  that is not stated in. The number in the square brackets refers to the parameter in  that shouldn't be there. It refers to its order in the sequence, but it is one less than its actual position, since  is an array; 0 is the first one, 1 is the second, etc.

To fix this, make sure all parameters stated in  are listed in. Alternatively, you can remove the  object to remove this error.

This error occurs if you put quotation marks around the value of either  or.

These are boolean values, not strings, therefore they require no quotation marks. To fix this, remove any quotation marks around the values  or   for these parameters.

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

属性format应该是…（Property "format" is expected to be ...）
If the  parameter exists but its value is not ,   or a valid format string, you will see the error message "".

To fix this, make sure the value after  equals   or   and that there no spelling mistakes. Alternatively, if it's wikitext, make sure it contains a minimum of  and that there are no mistakes in the syntax that would normally cause a template to fail, such as duplicate equals signs or missing/duplicate curly brackets; see the section #Custom formats for the syntax for custom formats. Alternatively, you can remove the  parameter to remove this error.

This error occurs if you state a parameter that does not exist in template data. This is probably due to spelling mistakes.

It also occurs if you state a parameter in any template data object that is not a parameter of that object. This may be due to spelling mistakes, or you may have written the parameter of one template data object under another object that it doesn't belong to.

For example, you might have written the parameter  under the root template data object instead of inside  :

Alternatively, if the unexpected parameter is under a template parameter inside, you'll see its name after "params.parametername." in the error.

To fix this, make sure there aren't any spelling mistakes in the parameter names, and make sure your parameters are in their correct location. Additionally, make sure you don't state any parameters that don't exist for a template data object. You can check which parameters exist for an object in the section #Template data parameters.

This error occurs if there is no  object in the template data. This is a necessary object, as it contains all the details of each parameter, so to fix this error, make sure it's added and that there are no spelling mistakes. See the section above on how to add the  parameter.

<span id="Limitations_and_feedback">

局限及疑问

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

<span id="Other_tools">

其它工具

 * : A toolbar dialog window for entering template wikitext via an form built from template data.
 * TemplateData Wizard: 一个通过交互式界面生成模板信息的工具.
 * Skeleton TemplateData generator: 一个读取模板源wiki代码的工具，尝试寻找使用的所有参数，并按列出的参数输出纲要文档.
 * JSONLint: 一种允许您验证手动写入的JSON以帮助查找语法中的错误工具.
 * 在此wiki上[ 所有带模板数据的模板列表]
 * 使用dewiki template TemplateData模板数据在框中被显示出来，且该模板被添加到有模板信息的分类当中.
 * https://query.wikidata.org/ and Query Helper