模組: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