模組:Template wrapper/doc

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

When writing a wrapper template, give this module all of the normally required default parameters necessary to use the wrapper template in its base form. Editors then use the wrapper template as-is or may supply additional wrapper and canonical parameters. Any of the canonical parameters supported by the working template may be added to the wrapper template or supplied by editors in article space. When an editor supplies a parameter that has a default value in the wrapper template, the editor-supplied value overrides the default. When it is necessary to remove a default parameter, editors may set the parameter value to the special keyword unset which will cause this wrapper module to erase the wrapper template's default value for that parameter. This module discards empty named parameters.

Positional parameters are not normally passed on to the working template. Setting |_include-positional=yes will pass all positional parameters to the working template. Positional parameters cannot be excluded; positional parameters may be unset.

Parameters that are used only by the wrapper should be either positional ({{{n}}}) or listed in |_exclude= (a comma-separated list of named parameters). This module will not pass _excluded parameters to the working template.

用法

{{#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）
|canonical parameters=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	filter exclued parameters		working template
|wrapper parameters=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→
		|_exclude=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→		→
		|_include-positional=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→
		|_alias-map=	→	转换别名参数 为规范参数	→	|canonical parameters=	→	–––––––→	→	–––––––→	→				→
					→		→	修改复用的 规范参数
|alias parameters=	→	–––––––→	→						→	|reused parameters=	→	–––→	→
		|_reuse=	→	–––––––→	→	–––––––→	→
|canonical parameters=	→	–––––––→	→	–––––––→	→	–––––––→	→
		|default parameters=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––→	→

参数

_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

Wrapper parameters listed in |alias-map= are not passed to the working template. Mapping positional parameters when |_include-positional=yes may give undesirable results. |_alias-map=1:author and |_include-positional=yes will cause all other positional parameters to be passed to the working template as is: wrapper template {{{2}}} becomes working template {{{2}}}, etc; working template will not get {{{1}}} though it will get |author=.

_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