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支持的话）. 查看m:帮助:模板文档获取更多信息

Insert the text you cut or saved in the previous text (beneath the notice template, if applicable).

Wrap any categories in tags so that they apply only to the template's main page:

Many wikis have a  template. Use this template here if it's likely that the template you're editing exists in a sandbox version (located at "Template:Templatename/sandbox") in order to prevent the categories from applying to the sandbox page:

Finally, publish the page.

You can now add and edit the template data on the documentation subpage using the instructions described in #Methods.

Adding and editing template data on the main template page
If you can't create the /doc page, you can add and edit template data on the template's main page by following the instructions in #Methods.

If a template has a documentation subpage, check both the main page and the documentation subpage for the presence of template data (the tag followed by an array inside curly brackets:  ).

Alternatively, the TemplateData extension can perform this check for you. Click "" or "" on either page. If the template already has template data on either page, you will see a yellow notice at the top of the page saying either:



or

If the template has template data on its documentation subpage

If the template has template data on its documentation subpage, this is the page you should edit. You can do this by clicking the "[edit]" located after the heading " Template documentation" (or similar), or, if you are already on the /doc page, by clicking "" or "" at the top. Follow the guidance at #Methods to add or edit the template data.

If the template has template data on its main page

If the template has template data on its main page, you once again have two options:


 * You can either move to its documentation subpage. This is the preferred option.


 * Or, you can edit it on the main template page.

Moving template data to the documentation subpage

To do this, click ""/"" on the main template page, and look for the tags, enclosed within  tags. It should look something like this:

Cut only the tags and their contents out of the code, then save the page.

Next, edit the documentation subpage by clicking the "[edit]" located after the heading " Template documentation" (or similar).

Type a heading, like "Template data", then beneath it paste the template data.

You can now edit the template data based on the guidance at #Methods.

Editing template data on the main template page

If you do not wish to move the template data to the /doc page, you can edit it on the main template page. See #Methods for how to edit template data.

If the template does not yet have template data but has a doc subpage

If the template does not yet have template data, you should add it to the documentation subpage.

Do this by clicking the "[edit]" located after the heading " Template documentation" (or similar), or, if you are already on the /doc page, by clicking "" or "" at the top. Type a heading, like "Template data", then add it beneath this heading. The section #Methods explains how to add template data.

方法


模板數據編輯方法
This is a simple way to add or edit template data, recommended for less experienced users.

模板数据编辑器是一个图形化的编辑器，可用来添加或编辑模板数据. It is part of the TemplateData extension, available on any template's page (or documentation subpage) by clicking "" or "".

After clicking "" or "", you will see a button above the editing area and page title that says "".

|453px

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

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

Features in the above window:

If no language template data exists, the interface will only offer users the wiki's own language, but users can click "" to add more inputs. The language code is displayed in brackets next to the parameters to which it can be applied, such as descriptions and labels.
 * The top item chooses the language of the interface text. It allows you to enter text content in multiple languages, displayed to users based on their settings in Preferences, not based on the wiki's language; different wikis have entirely different template databases.
 * The next item is the template description. This is the description of the template as a whole; it's shown to users in numerous places in the template editors while adding a template. This parameter and its effects are outlined here.
 * The third item controls the wikitext formatting of the template. This parameter determines how the wikitext will be laid out when the user clicks "", the two main types being  (on one line) and   (on new lines). This parameter and its effects are outlined here.
 * If the user chooses "", they can enter wikitext under "" according to rules outlined here, in order to create a custom layout for the template when the user clicks "".

If parameters have already been defined in template data, this area displays them in a list. If the template's source code specifies parameters for which no template data exists, you may see a button labeled "". The editor extracts these suggestions from the template's source code by looking for  or. Clicking "" will add these parameters using their names as defined in the source code. A green notice will also appear at the top, for example, "".
 * The fourth item configures a template's parameters.
 * At the bottom of the window you see an "" button. This allows you to add a parameter manually with a custom name.

Continue to the next step by clicking any one of the parameters in the list. This will allow you to edit that parameter's info.

600px

All of these features and their effects are outlined in the section #Within a parameter's name.

When finished, click "". This will automatically insert the template data at the bottom of the page before the tag; or, if already present, it will be updated with the new information without changing its position. The template data text will also be selected when you click "".

The template data editor creates a  parameter at the bottom of the template data (or updates it if it already exists). contains the current template data parameters in the order in which they were displayed by the template data editor. You can change the  by dragging the parameters up and down in the template data editor using the three horizontal bars on the left. and its effects are described here.

After this, click "" to save your revision of the page.



手动方法
You can also add or edit template data manually. 模板数据的结构基于JSON标准，但你无需了解JSON即可知道如何编辑模板数据. Template data follows a few very simple rules and accepts only a few dozen possible predefined parameters and values, typically following a  format.

Adding template data manually

Considerations:


 * 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" ] }



描述和参数
All available template data parameters are listed below with a description and example. They are also listed in more technical detail at Extension:TemplateData#Format.



在参数内


在参数名称中
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.



属性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