模组:Template wrapper/doc

本模块用于将模板封装，以提供默认参数值，并允许编者向底层工作模板传递额外参数。

在编写封装模板时，应为此模块提供使用封装模板所需的所有默认参数。然后，编者可以直接使用封装模板，也可以提供其他封装和规范参数。工作模板支持的所有规范参数都可以添加到封装模板中，或由编者中条目中提供。当编者提供的参数在封装模板中有默认值时，编者提供的值会覆盖默认值。如果需要移除默认参数，编者可以将该参数值设置为关键字unset。参数留空时本模块会将其丢弃。

匿名参数通常不会传递给工作模板。设置|_include-positional=yes时将所有匿名参数传递给工作模板。匿名参数不能被排除；匿名参数也可以设为unset。

仅由封装模板使用的参数，要么是匿名参数（{{{n}}}），要么在|_exclude=中列出。本模块不会将_excluded参数传递给工作模板。

用法

{{#invoke:Template wrapper|wrap|_template=working template|_exclude=named parameter, named parameter, ...|_reuse=named parameter, named parameter, ...|_alias-map=alias parameter:canonical parameter|_include-positional=yes|<default parameter>|<default parameter>|...}}

控制参数（详见下方说明）

|_template= – （必须）工作模板（即被封装的模板）的名称（不带“Template:”命名空间前缀）

|_exclude= – 仅在封装模板中使用、不传递给工作模板的参数列表，以逗号分隔

|_reuse= – 复用参数列表，以逗号分隔，这些参数由封装模板和工作模板共用

|_alias-map= – 封装参数至规范参数的映射列表，使用逗号分隔，作用是指定规范参数的别名

|_include-positional= – 填写yes时将所有匿名参数传递给工作模板

定义

规范参数（canonical parameter）：工作模板支持和使用的参数

封装参数（wrapper parameter）：封装模板使用的参数；可为规范参数提供数据，或用于控制封装模板

别名参数（alias parameter）：对封装模板具有上下文意义的封装参数，但必须重命名为规范参数以供工作模板使用

复用参数（reused parameter）：由封装模板和工作模板共用的参数，传入工作模板时已被封装模板修改

默认参数（default parameter）在封装模板中给出默认值的规范参数

参数处理

封装模板 （wrapper template）		Module:Template wrapper												工作模板 （working template）
|规范参数=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	过滤 排除参数		working template
|封装参数=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→
		|_exclude=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→		→
		|_include-positional=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→
		|_alias-map=	→	转换别名参数 为规范参数	→	|规范参数=	→	–––––––→	→	–––––––→	→				→
					→		→	修改复用的 规范参数
|别名参数=	→	–––––––→	→						→	|复用参数=	→	–––→	→
		|_reuse=	→	–––––––→	→	–––––––→	→
|规范参数=	→	–––––––→	→	–––––––→	→	–––––––→	→
		|默认参数=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––→	→

参数

_template

唯一必需的参数，|_template=提供工作模板（被封装的模板）的名称（不带“Template:”命名空间前缀）。

_alias-map

|_alias-map=封装参数至规范参数的映射列表，使用逗号分隔，作用是指定工作模板规范参数在封装模板中的别名。每项映射格式如下：

<from>:<to> – 其中<from>是封装模板的参数名，<to>是规范参数名

例如封装模板中要使用|assessor=参数，在工作模板中没有|assessor=参数，但有等效的|author=参数，这时可写为：

|_alias-map=assessor:author

匿名参数也可以映射为规范参数：

|_alias-map=1:author, 2:title, 3:language

可以使用#枚举符将封装参数枚举映射至规范参数：

|_alias-map=assessor#:author#

多个封装参数可以映射到一个规范参数：

|_alias-map=1:author, assessor:author

|alias-map=中列出的封装参数不会传递给工作模板。设置|_include-positional=yes时映射匿名参数可能导致不良后果。同时设置|_alias-map=1:author和|_include-positional=yes时，封装模板中的{{{1}}}传入工作模板的|author=，其他匿名参数也会传入工作模板，即封装模板的{{{2}}}传递为工作模板的{{{2}}}等等。

_reuse

|_reuse=规范参数列表，使用逗号分隔，这些参数对封装模板和工作模板都有意义。

在最简单的情况下，传入封装模板的规范参数会覆盖封装模板中提供的默认参数。有时，一个封装参数与规范参数的名称相同，并且需要在封装模板中对参数值修改后再传入给工作模板。例如，|title=既是封装参数，也是规范参数，封装模板需要将其修改后再传入工作模板。为此，我们首先编写：

|_reuse=title

之后，在封装模板的{{#invoke:Template wrapper|wrap|_template=...|...}}中编写：

|title=Modified {{{title}}}

复用参数不能被覆盖。

_exclude

|_exclude=仅在封装模板中使用、不传递给工作模板的参数列表，以逗号分隔。此列表适用于从封装模板接收的所有封装参数和规范参数（包括已重命名为别名参数的规范参数）。

例如，封住模板使用|id=参数的值作为默认参数|url=的部分内容，可以这样写：

|_exclude=id

之后，在封装模板的{{#invoke:Template wrapper|wrap|_template=...|...}}中编写：

|url=https://example.com/{{{id}}}

这样，被修改后的|url=参数值被传递给工作模板，但|id=参数不传递。

复用参数和默认参数不应被排除。

_include-positional

|_include-positional=填写yes时将所有匿名参数传递给工作模板，默认状态（留空/取消该参数）为排除匿名参数。

覆盖默认参数

编者只需在封装模板中将默认参数设置为所需值，即可覆盖默认参数。参数值留空时将被忽略，若要将默认参数设为空值，请填写关键字unset，以将该默认参数将作为空（无赋值）参数传递给工作模板。

复用参数不能设为unset或被覆盖。

调试/文档模式

This module has two entry points. A wrapper template might use a module {{#invoke:}} written like this:

{{#invoke:Template wrapper|{{#if:{{{_debug|}}}|list|wrap}}|_template=<working template>|_exclude=_debug, ...|...}}

where the |_debug= wrapper parameter, set to any value, will cause the module to render the call to the working template without actually calling the working template.

As an example, {{cite wikisource}} is a wrapper template that uses {{citation}} as its working template. {{cite wikisource}} accepts positional parameters but {{citation}} does not so the wrapper template must convert the positional parameters to named parameters which it does using the |_alias-map= parameter:

{{#invoke:template wrapper|{{#if:{{{_debug|}}}|list|wrap}}|_template=citation
  |_exclude=..., _debug <!-- unnecessary detail omitted -->
  |_alias-map=1:title, 2:author, 3:language

This example uses positional parameters and sets |_debug=yes to show that the {{citation}} template is correctly formed:

{{cite wikisource|Sentido y sensibilidad|Jane Austen|es|_debug=yes}}

Jane Austen.  Sentido y sensibilidad. 维基文库 （西班牙文）. 

and, with |_debug= unset:

{{cite wikisource|Sentido y sensibilidad|Jane Austen|es|_debug=}}

Jane Austen.  Sentido y sensibilidad. 维基文库 （西班牙文）. 

The |_debug= name is chosen here for convenience but may be anything so long as it matches the {{#if:}} in the {{#invoke:}}.

You may also call the link function to get something like the left-hand side of Template:yy. This is essentially the list function with the template name turned into a link. Template:Yytop Template:Yy Template:Yybottom