- 本文用于介绍萌娘百科中一些特定功能的操作方法；
- 本文仅是一篇论述，不属于方针或指引。如果本指南与相关方针或指引发生冲突或存在不一致的情况，请以方针或指引的条文为准。
模板数据（TemplateData）是一项MediaWiki扩展，能够帮助用户在可视化编辑器中更方便地插入各类模板。本页面主要介绍如何为模板编写和编辑模板数据，所述内容一般仅适用于可视化编辑器与2017版wikitext编辑器。
添加或编辑模板数据
开始前的检查
在添加或编辑模板数据之前，需要先检查模板是否有文档子页面，以及模板数据是否已经存在。
许多模板都会将使用说明、分类链接和模板数据放置在文档子页面（/doc）中，并通过 {{Documentation}} 模板将其内容嵌入到模板主页面。你可以通过以下方式判断：
- 在模板主页面底部，通常能看到“模板文档”标题，以及[查看]、[编辑]、[历史]、[清除]等链接，这表明存在文档子页面。
- 如果模板主页面源代码中大段的
<noinclude>{{Documentation|content=...}}</noinclude>，说明文档直接写在主页面中（较少见）。 - 页面底部可能会显示类似“以上文档嵌入自Template:模板名/doc”的提示。
重要： 如果模板既有文档子页面又在其主页面包含模板数据，主页面中的数据会覆盖子页面中的数据。因此，应当只保留一份模板数据，并强烈建议将其放在文档子页面中。
如果没有文档子页面，建议创建一个，然后将页面中原有的说明文字（以及可能已经存在的模板数据）移动到子页面中。具体步骤：
- 编辑模板主页面，找到
<noinclude>部分，将其中的内容（通常是{{Documentation|content= ... }}之间的全部内容）剪切出来。 - 删除
|content=参数，使其变为{{Documentation}}。 - 保存模板主页面。
- 在浏览器地址栏的模板页面 URL 末尾加上
/doc，按回车，然后创建该子页面。 - 将之前剪切的内容粘贴到文档子页面中，并用
<includeonly>包裹分类链接，以避免子页面本身被错误分类。 - 保存文档子页面。
现在就可以在文档子页面上添加或编辑模板数据了。
如果想直接在主模板页面添加（在不创建子页面的情况下），请务必把模板数据放在 <noinclude> 标签内。
方法一：使用模板数据编辑器
这是最简单、推荐的方法。编辑器提供了一个图形界面，无需手动编写 JSON。
打开编辑器
在模板页面或其文档子页面点击“编辑”或“编辑源代码”，你将在编辑工具栏上方（或页面标题附近）看到一个名为“编辑模板数据”的按钮。点击该按钮即可进入模板数据编辑器。
如果该页面或关联页面已经存在模板数据，编辑器会自动加载已有数据；如果没有，则显示空白表单。
编辑器界面详解
编辑器窗口分为以下几个功能区域：
- 选择语言：位于顶部。你可以为模板描述、参数标签、参数描述等输入多种语言的文本。用户看到的语言取决于其用户设置中的界面语言，而不是站点的默认语言。默认只显示当前站点的基本语言字段，可通过“添加语言”按钮增加其他语言输入框。语言代码（如 en、de）会显示在相关字段的括号中。
- 模板描述：对整个模板功能的简要说明。该描述会在搜索模板时显示在模板名称下方，也会在添加模板时的编辑器顶部显示。描述应使用纯文本，字数尽量简洁。如果留空，编辑器会显示占位文字（例如“该模板还没有描述”）。
- 模板格式：控制用户点击“应用”后生成的 wikitext 布局。有三种选择：
- 内联 (inline)：所有参数写在同一行，例如
{{模板名|参数1=值|参数2=值}} - 块状 (block)：每个参数单独一行，例如：
- 内联 (inline)：所有参数写在同一行，例如
{{模板名
| 参数1 = 值
| 参数2 = 值
}}
-
- 自定义：允许你使用特定的格式字符串来精细控制输出。选择后，在下方的“自定义格式字符串”输入框中编写 wikitext 格式代码。基本规则：
-
{{代表模板开始，}}代表模板结束。_代表参数内容（可连续多个，如_______用于对齐）。|分隔参数，=连接参数名与值。\n或回车表示换行（输入框内会显示为 ↵）。- 空格可用于缩进。
-
- 最简单的自定义格式至少需包含
{{_|_=_}}，否则会报错。 - 一些常用示例如下：
-
- 无参数名前空格，每个模板独占一行：
\n{{_\n|_ = _\n}}\n→ 每个参数紧贴左侧，模板间有空行。 - 参数缩进：
{{_\n |_ = _\n}}→ 参数行前有一个空格缩进。 - 等号对齐：
{{_\n|_______________ = _\n}}\n→ 通过下划线数量使等号对齐。 - 更多示例参见自定义格式章节。
- 无参数名前空格，每个模板独占一行：
- 最简单的自定义格式至少需包含
- 参数列表：这是编辑器的核心区域，用于管理模板的所有参数。
- 如果模板的源代码中包含参数（如
{{{date}}}或{{{1}}}），而模板数据中尚未定义，编辑器顶部会出现“添加 X 个建议的参数”按钮。点击后会将它们以原名导入。导入成功后顶部会显示绿色提示，如“已导入 3 个新参数：date, reason, talk”。 - 点击列表中的任意参数，可展开其详细设置。这些设置包括：
- 标签：显示在编辑表单中的参数名称，可替代原始参数名，便于阅读。建议不超过20个字符。
- 描述：对该参数用途的进一步解释，帮助用户理解应填写什么内容。纯文本，不支持 wikitext。
- 必填 / 建议 / 弃用：设置参数的使用状态。具体效果见下文状态选项。
- 别名：该参数的其他可用名称。例如参数
talk可能也有别名talksection。填写时用逗号分隔。 - 默认值：文档用途的预设值（不会自动填入输入框），例如
Category:CommonsRoot。 - 自动值：在用户插入模板时自动填入输入框的值，用户可自行修改。常用于日期等，如
{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}。 - 示例值：提供一个填写范例，显示在参数描述下方，帮助用户理解格式。
- 参数类型：定义该参数值的数据类型，会影响编辑器提供的输入控件。可选的类型有：未知(unknown)、字符串(string)、行(line)、内容(content)、不平衡维基文本(unbalanced-wikitext)、wiki页面名称(wiki-page-name)、wiki文件名称(wiki-file-name)、wiki模板名称(wiki-template-name)、wiki用户名称(wiki-user-name)、数字(number)、布尔值(boolean)、日期(date)、URL(url)。不同类型的效果见类型参数详细效果。
- 建议值：为某些类型（如内容、行、字符串、数字、未知、不平衡维基文本）的参数提供一个下拉菜单，方便用户直接选择。你可以在此输入多个值，每输入一个按回车添加。例如为一个“介质”参数添加“期刊”、“书籍”、“报纸”、“杂志”等选项。
- 继承：可以指定当前参数从另一个参数继承所有属性，然后用单独定义的属性覆盖继承而来的属性。例如，
topic2继承topic1但修改了标签。
- 参数的排列顺序可以通过拖拽每条参数左侧的拖拽手柄（三条横线图标）来调整。最终顺序会写入
paramOrder字段，影响在模板编辑器中参数的显示顺序。 - 窗口底部有“添加参数”按钮，可手动添加一个自定义名称的参数。
- 点击“删除参数”按钮会移除该参数及其所有信息。此操作不可逆，除非之后点击“X”关闭窗口放弃所有更改。
- 如果模板的源代码中包含参数（如
完成编辑后，点击窗口右下角的“应用”按钮。模板数据 JSON 代码会被自动生成并插入到页面中，通常位于 </noinclude> 之前（或原地更新）。随后页面回到普通编辑视图，新增的代码会被高亮选中。最后点击“保存更改”按钮即可。
注意事项：
- 模板数据编辑器不允许保存参数名为空白的参数。空字符串名称的参数在模板向导中虽然不会引起错误，但在可视化编辑器和2017版wikitext编辑器中将完全不显示。
- 退出编辑器时会提示确认是否放弃更改。
- 修改后可以按 Ctrl+Z 撤销应用操作。
方法二：手动编写 JSON
你也可以直接编辑页面的 wikitext，手动添加或修改 <templatedata>...</templatedata> 块。模板数据使用 JSON 格式，但规则很简单，只需遵循基本的 "键": "值" 对即可。
基本步骤：
- 在模板页面或文档子页面点击“编辑源代码”。
- 在合适的位置（通常为文档子页面的底部，或主页面
<noinclude>内部）添加以下框架：
== 模板数据 ==
<templatedata>
{
"description": "",
"params": {
"1": {
"label": "",
"description": "",
"type": ""
}
}
}
</templatedata>
- 根据实际模板参数，在
"params"对象中添加对应的参数名和属性。属性可参考下文的参数列表，多个参数之间用逗号分隔（最后一个参数不加逗号）。 - 填写完成后保存页面。如果 JSON 格式有误，编辑器会报错并阻止保存（2010版wikitext编辑器除外，它目前不校验 JSON，但推荐使用外部验证工具如 JSONLint 检查）。
下面是一个较完整的示例，展示了一个“清理”模板的模板数据：
<templatedata>
{
"description": "使用此模板标记需要清理的条目。",
"format": "inline",
"params": {
"date": {
"label": "月份和年份",
"description": "添加模板的月份和年份",
"type": "string",
"autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}",
"example": "2013年1月",
"suggested": true
},
"reason": {
"aliases": ["1"],
"label": "原因",
"description": "条目需要清理的原因",
"type": "string"
},
"talk": {
"aliases": ["talksection"],
"label": "讨论页章节",
"description": "讨论页中相关讨论所在的章节",
"type": "string"
}
},
"paramOrder": [
"date",
"reason",
"talk"
]
}
</templatedata>
手动编写时，请注意：
- 所有键和字符串值必须用英文双引号
"括起来。 - 布尔值
true和false不加引号。 - 最后一个参数或属性的末尾不要多加逗号，否则会引发 JSON 解析错误。
模板数据参数详解
以下列出所有可在模板数据块中使用的参数。参数分为顶层参数和参数内部参数。
顶层参数
| 参数 | 说明 | 示例 |
|---|---|---|
description |
整个模板的说明。纯文本，可选但强烈推荐。在搜索模板和添加模板时会显示。 | "description": "用于链接至萌娘共享分类的模板"
|
format |
指定模板的默认 wikitext 布局。可设置为 "inline"、"block" 或自定义格式字符串。若未指定，编辑器会尝试保留现有格式，否则默认为 inline。 |
"format": "inline"
|
params |
一个对象，包含模板所有参数及其信息。必需。 | （见下文） |
paramOrder |
一个数组，列出参数在编辑器中显示的顺序。数组中的每个元素必须是 params 中定义的参数名。如果未指定，顺序由模板源代码决定。若使用模板数据编辑器，编辑器会自动生成此字段。 |
"paramOrder": ["date", "reason", "talk"]
|
sets |
（实验性）定义参数集合，用于将相关参数分组。暂未广泛使用。 | "sets": [ { "label": "日期", "params": ["year", "month", "day"] } ]
|
参数内部（params 中的每个参数对象）
每个参数可包含以下属性：
| 属性 | 说明 | 示例 |
|---|---|---|
| 参数名 | 参数的名称，即模板源代码中的 {{{参数名}}} 部分。例如 date，1。 |
|
label |
参数的显示标签，会替代原始参数名显示在编辑界面。建议简短，不超过20字符。 | "label": "月份和年份"
|
description |
参数的描述文本，解释该参数的含义或填写格式。纯文本，可选但强烈推荐。 | "description": "模板被添加的月份和年份"
|
required |
布尔值，若为 true 则该参数为必填。在可视化编辑器和2017编辑器中会自动显示并要求用户填写。默认为 false。 |
"required": true
|
suggested |
布尔值，若为 true 则该参数为强烈建议填写。在可视化编辑器和2017编辑器中会自动显示（但非强制）。若同时设置 required 为 true，则以 required 为准。默认为 false。 |
"suggested": true
|
deprecated |
标记该参数为已弃用。值可为 true、false，或一段说明文字（纯文本，但目前编辑器不显示该文字）。弃用的参数在可视化编辑器和2017编辑器中会带有警告图标。若同时设置 required 或 suggested，在可视化编辑器和2017编辑器中仍会保留相应行为，但在模板向导中弃用会覆盖其他状态。默认为 false。 |
"deprecated": "请改用 'publicationDate' 参数。"
|
aliases |
一个字符串数组，列出该参数的其他可行名称。例如模板可能同时支持 talk 和 talksection。在编辑器中，使用别名同样有效。 |
"aliases": ["1", "talksection"]
|
default |
默认值的文档性描述（不会自动填入）。在编辑器中会以灰色文本显示在输入框内，格式为“默认：值”。 | "default": "Category:CommonsRoot"
|
autovalue |
自动值。在用户插入模板时会预先填入输入框，用户可修改。常用 wikitext 替换来实现动态值，如 {{subst:CURRENTYEAR}}。 |
"autovalue": "5月 2026"
|
example |
示例值，显示在参数描述下方，帮助用户理解格式。若同时设置了 default，则示例不会出现在输入框中，只在描述区显示。 |
"example": "2013年1月"
|
type |
参数类型，控制编辑器行为的核心属性之一。见类型参数详细效果。 | "type": "string"
|
suggestedvalues |
一个字符串数组，为适用类型的参数提供下拉选项列表。仅支持部分类型（内容、行、字符串、数字、未知、不平衡维基文本）。 | "suggestedvalues": ["期刊", "书籍", "报纸", "杂志"]
|
inherits |
从另一个参数继承所有属性。可被后续定义的属性覆盖。例如，"inherits": "topic1" 会使当前参数获得 topic1 的所有设置，然后你可单独改写 label 等。 |
"inherits": "topic1"
|
状态选项（required / suggested / deprecated）的交互效果
- 在可视化编辑器和2017版wikitext编辑器中：
required: true：参数自动显示，输入框旁有黑色星号，描述下方显示“此参数为必填”，离开空值框时变红，不填值可插入但会提示。suggested: true：参数自动显示，无额外提示。deprecated: true：参数旁显示灰色感叹号，描述中有弃用提示，但功能不受影响。- 如果同时
required和deprecated为 true，则参数仍必填且显示弃用标记。 required会覆盖suggested，即设为必填后不会出现建议状态。
- 在模板数据文档表格中（即模板页面自动生成的参数表），状态会显示为“必填”、“建议”、“弃用”或“可选”（三者皆未设置时显示“可选”）。
类型参数详细效果
类型参数会影响编辑器提供的输入控件和验证行为。目前各编辑器支持程度不同（截至2020年信息）：
| 类型值 | 描述 | 编辑器效果 |
|---|---|---|
"unknown" |
默认类型，无特殊行为。 | 无特殊效果。 |
"string" |
任意文本字符串。 | 无特殊效果（与 unknown 相同）。 |
"line" |
短文本，预期不包含换行。 | 在可视化编辑器和2017编辑器中，输入框禁止换行。 |
"content" |
页面的wikitext，可包含链接、图片等。 | 在模板向导中，输入框增高并允许换行。 |
"unbalanced-wikitext" |
不平衡的wikitext，例如不完整的标签。 | 在模板向导中，输入框增高并允许换行。 |
"wiki-page-name" |
有效的维基页面名称。 | 提供页面名称下拉建议（可搜索）。在可视编辑器和2017编辑器中强制单行。 |
"wiki-file-name" |
有效的文件名称（不含“File:”前缀）。 | 在模板向导中，提供文件列表下拉，含缩略图。 |
"wiki-template-name" |
有效的模板名称。 | 提供模板名称下拉建议，并强制单行（可视编辑器/2017编辑器）。 |
"wiki-user-name" |
有效的用户名。 | 提供用户名下拉建议，并强制单行（可视编辑器/2017编辑器）。 |
"number" |
数值（可含负数和十进制）。 | 在模板向导中，输入框两侧出现加减按钮，且只能输入数字。还会覆盖 autovalue 的效果（不自动填入）。 |
"boolean" |
布尔值，通常用“1”、“0”或空白表示。 | 在可视化编辑器中（配合 autovalue:0）会出现可切换的复选框。 |
"date" |
ISO 8601 格式日期，如 2014-05-22。 | 在模板向导中，输入框变短并带有日历选择器，自动格式化输出。会覆盖 autovalue 的效果。 |
"url" |
网址，需包含协议（如 https://）。 |
在可视编辑器和2017编辑器中，输入框左侧显示外部链接图标，若留空且点击别处会变红（类似必填的视觉提示，但不阻止插入）。如果同时设置了 autovalue，则 URL 的视觉效果会被覆盖。 |
自定义格式
当 format 设置为自定义字符串时，可使用以下标记构建输出格式：
{{– 模板起始_– 参数值占位符，可重复多个用于对齐（如_______）|– 参数分隔=– 参数名与值之间的等号\n或直接回车 – 换行- 空格 – 用于缩进
}}– 模板结束
自定义字符串必须至少包含 {{_|_=_}}，否则会报“无效格式字符串”错误。
以下是一些常见需求对应的格式字符串：
| 目标 | 格式字符串 | 示例输出 |
|---|---|---|
| 内联 | {{_|_=_}} 或直接设置 "inline" |
{{Foo|bar=baz|quux=quuz}}
|
| 块状，参数每行一个 | {{_\n| _ = _\n}} 或 "block" |
（见上文块状示例） |
| 无参数名前空格，每个模板独占一行 | \n{{_\n|_ = _\n}}\n |
模板前后有空行，参数左对齐 |
| 参数缩进一个空格 | {{_\n |_ = _\n}} |
空格缩进 |
| 对齐等号 | {{_\n|_______________ = _\n}}\n |
通过下划线数量使等号纵向对齐 |
| 管道符置于上一行末尾 | {{_|\n _______________ = _}} |
空白样板
你可以复制以下最小化样板开始手动添加模板数据：
<templatedata>
{
"description": "",
"params": {
"1": {
"label": "",
"description": "",
"type": ""
}
}
}
</templatedata>
常见错误
当手动编辑模板数据时，可能会遇到页面保存失败并显示错误信息。以下列出常见的错误及其解决方法：
“JSON 格式错误” / “解析错误”
- 原因： JSON 语法不正确，例如键名缺引号、多余逗号、括号不匹配等。
- 解决： 使用 JSONLint 等工具验证 JSON，修复语法错误。建议尽量用模板数据编辑器来避免此类问题。
“缺少必需属性 paramOrder[数字]”
- 原因： 在
"paramOrder"数组中缺少某个在"params"中已定义的参数。 - 解决： 将缺失的参数按期望顺序加入
"paramOrder"数组，或直接删除整个"paramOrder"字段（编辑器会按默认顺序）。
“属性 paramOrder[数字] 的值无效”
- 原因：
"paramOrder"数组中包含了一个未在"params"中定义的参数名称。 - 解决： 移除该非法名称，或将其添加到
"params"中。
“属性 params.参数名.required 的类型预期为 boolean”
- 原因： 将
required或suggested的值用引号括了起来，例如"required": "true"。它们应为布尔值，不能用引号。 - 解决： 去掉引号，写成
"required": true。
“属性 format 预期值为 inline、block 或有效的格式字符串”
- 原因：
format的值既不是"inline"或"block"，也不是符合规则的自定义字符串，或者自定义字符串不符合最小要求。 - 解决： 检查拼写，或确保自定义字符串至少包含
{{_|_=_}}，且没有重复的等号或花括号错误。
“未知属性 属性名”
- 原因： 在模板数据对象中使用了不认识的属性名，或者将本应放在子对象中的属性放错了位置（例如将
"label"直接放在根对象下而不是参数内部）。 - 解决： 检查属性名拼写，确保所有属性都在正确的层级。可以参考本文档的参数列表确认有效属性。
“缺少必需属性 params”
- 原因： 模板数据完全缺少
"params"对象。 - 解决： 添加
"params": { ... }并包含至少一个参数。
注意事项
模板数据保存后，通常会立即在可视化编辑器中生效。但有时可能需要数小时才能在所有缓存中更新。你可以对模板主页面进行一次空编辑（不修改页面，直接保存）来强制刷新。
参见
- Help:TemplateData
- Extension:TemplateData
- 模板数据格式规格（英文）
- JSONLint：验证手动编写的 JSON 格式是否正确。
- 带有模板数据的模板列表
| |||||||||||||||||||||||||||||||||||