模块:TemplateParameters/doc

此模块文档被引用于约909,000个页面。
为了避免造成大规模的影响，所有对此模块文档的编辑应先于沙盒或测试样例上测试。
测试后无误的版本可以一次性地加入此模块文档中，但是修改前请务必于讨论页发起讨论。

模板引用数量会自动更新。

本模组可以将参数填入以普通模板参数定义的格式化字符串

设计缘由

自定义的模板参数读取之构想早在2018年11月就已提出。当时数学类条目面临大量WP:114.27的似是而非的破坏，不易查证真伪，因此建立了Module:Number（及复变部分的Module:Complex Number，如高斯整数分解）来自动计算并输出数学性质，避免遭WP:114.27窜改为错误资讯而不易查证（例如多1少1的破坏难以察觉和验证），但有用户认为输出固定字串无法被修改或添加注解、参考文献不妥，因此出现了格式化字符串的需求，而部分用户认为，应尽量是要设计一般维基人都能编辑的语法，因此最后决议选择wikitext模板中的模板参数语法，但当时此功能独自分散在各个需要格式化字符串功能的模组里，例如Module:Number、Module:PeriodicTable和Module:Delcat等地方。

最初的版本仅包含简单文字替换，只能处理已知数量的参数，而在2019年6月，有用户问到能否不写新的模组、也不使用大量{{#if:}}实现，因此认为可以把自动读取参数填入格式化字符串的功能独立出来（即建立本模组），顺便提供些特殊参数解析功能，如参数批次trim和数字解析功能（根据WP:TG1请求用于{{Infobox 日本的町村}}）。

使用说明

本模组主要是提供wikitext模板中的模板参数一个API，而非设计给其他Lua函数使用，因此专门给lua呼叫的函数较少。

本模组包括的函数如下：

getFormatingStringByArgument ：固定参数的格式化字符串方法
FormatingArguments ：不定参数的格式化字符串方法
containsNumber ：判断参数是否包含数字
getNumberValue ：析出参数包含的数字
arg_to_spstr与pass_spstr ：提供不定参数迭代（跨层传递）的一种方式
argTrim ：参数批次Trim 或已展开的参数避免|后方内容遗失的方法
listArguments ：列出所有接收到的参数，提供模板可见的除错方式。
call ：将模板参数转为Lua参数的方法，提供呼叫一些不支援以模板参数呼叫之Module的功能。
templateArgWarp ：将模组调用转换为另一个模板且输入参数为从外部模板(父模板)读取之参数的未解析字串，用于替换引用。
makeTemplateParameter ：产生模板参数的未解析字串，如{{{arg}}}

用法

getFormatingStringByArgument

功能：直接将参数透过简单文字替换填入形如{{{X}}}的位置内

{{#invoke:TemplateParameters | getFormatingStringByArgument | 在{{{學科}}}中，{{{名稱}}}是一種{{{種類}}} | 學科=數學 | 名稱=三角形 | 種類=多邊形}}
显示为“在数学中，三角形是一种多边形”

用途

Module:Number中，客制化的性质输出格式。
Module:PeriodicTable中，选择要在元素周期表输出的元素性质。

FormatingArguments

功能：将未知数量的参数根据{{{X}}}规则依序填入给定的字符串中。

模板中输入

{{#invoke:TemplateParameters|FormatingArguments|格式=這是第{\{\{1}\}\}個參數；|count=1|usingConditionalExpressions=yes}}

叫用模板{{<模板名稱>|一|二|三|四}}
显示为：“这是第一个参数；这是第二个参数；这是第三个参数；这是第四个参数；”
解释：
- 模板中“格式”参数原本为這是第{{{1}}}個參數；，透过加入跳脱字元防止先被解析后，透过FormatingArguments函数将传入模组读所有参数依序填入，不必透过大量的{{#if:{{{N}}}就能达成不定数量的参数传递。

模板中输入

{{#invoke:TemplateParameters|FormatingArguments|格式=*:[[畢氏三元數]]：{\{#tag:math{{!}}\\left({\{\{1}\}\},{\{\{2}\}\} ,{\{\{3}\}\}\\right)}\}\n|count=3|usingConditionalExpressions=yes}}

叫用模板{{<模板名稱>|3|4|5|5|12|13|7|24|25}}
显示为：
毕氏三元数： $\left(3,4,5\right)$

毕氏三元数： $\left(5,12,13\right)$

毕氏三元数： $\left(7,24,25\right)$
解释：
- 模板中“格式”参数原本为*:[[畢氏三元數]]：{{#tag:math|\left({{{1}}},{{{2}}} ,{{{3}}}\right)}}\n。
  指定了数量为3（ | count=3）后，会将参数每三个一组代入{{{1}}}、{{{2}}}和{{{3}}}。

格式字串中支援的参数

下面为FormatingArguments支援的参数，若有同名参数可能会影响运作

读取不定参数：
- {{{1}}}、{{{2}}}、{{{3}}}...即以组为单位读取不定参数。
  例如{{|1|2|3|4|5|6|7|8|9}}如果设定为每组3个参数，
  则第一组的{{{1}}}、{{{2}}}、{{{3}}}分别会代入1、2和3；
  
  第二组的{{{1}}}、{{{2}}}、{{{3}}}分别会代入4、5和6
  
  以此类推。
- {{{count+1}}}、{{{count+2}}}、{{{count+3}}}...读取下一组的不定参数。
  例如{{|1|2|3|4|5|6|7|8|9}}如果设定为每组3个参数，此时{{{count+1}}}即为{{{4}}}
  则第一组的{{{4}}}、{{{5}}}、{{{6}}}分别会代入4、5和6；
  
  则第二组的{{{4}}}、{{{5}}}、{{{6}}}分别会代入7、8和9；
  
  则第三组的{{{4}}}、{{{5}}}、{{{6}}}因为没有第四组，而会变成空值、预设参数或保持原样（即{{{4}}}）；
- {{{0}}}、{{{-1}}}、{{{-2}}}...读取前一组的不定参数。
  例如{{|1|2|3|4|5|6|7|8|9}}如果设定为每组3个参数
  则第一组的{{{0}}}、{{{-1}}}、{{{-2}}}因为第一组没有前一组，而会变成空值、预设参数或保持原样（即{{{0}}}）；
  
  则第二组的{{{0}}}、{{{-1}}}、{{{-2}}}分别会代入3、2和1；
  
  则第三组的{{{0}}}、{{{-1}}}、{{{-2}}}分别会代入6、5和4；
  
  以此类推。
- {{{random}}}：位于本组的随机参数。
- {{{allRandom}}}：所有参数的随机参数。
- {{{last}}}：本组的最后一个参数。
判断用参数
- {{{isFirst}}}：如果这是第一组参数则为1，否则为空值。
- {{{isLast}}}：如果这是最后一组参数则为1，否则为空值。
- {{{count}}}：参数组的数量。
- {{{argGroupID}}}：返回目前作用中的参数是第几组。

Subst方法

此模板可以使用Subst，不过若用<nowiki></nowiki>搭配 | delnowiki = 参数的话会导致替换失败。

替代方案可以使用跳脱字元（如\{、\}等）以及H:魔术字（如{{!}}、{{ {{{|safesubst:}}}!}}、{{[[Template:|]]}}、{{ {{{|safesubst:}}}=}}等）
若觉得编辑困难可以使用子页面搭配{{msgnw:模板名}}以及 | delmsgnw = 参数来完成
- 详细使用方式可参考User:A2569875/SubstTest搭配User:A2569875/SubstTest/Cell的范例。
- 使用{{msgnw:模板名}}需要(※)注意的是：由于使用msgnw，因此<noinclude></noinclude>等标记无效，因此不应该在该子模板中直接加入注解或{{Doc}}的内容，需要使用{{ifsubst}}才能运作，例如{{ {{{|safesubst:}}}ifsubst||<noinclude>{{documentation}}</noinclude>}}。
  或者：

{{ {{{|safesubst:}}}ifsubst||<noinclude>
不被包含引用的部分
</noinclude>}}

containsNumber

功能：用于确定一个参数内是否有包含阿拉伯数字

{{#invoke:TemplateParameters|containsNumber|hijk42lm}}→“1”
{{#invoke:TemplateParameters|containsNumber|hijklm}}→“”

用法

{{#if:{{#invoke:TemplateParameters|containsNumber|hijk42lm}}|有數字|沒數字}}→“有数字”
{{#if:{{#invoke:TemplateParameters|containsNumber|hijklm}}|有數字|沒數字}}→“没数字”

getNumberValue

功能：尝试从一个参数内读出一个阿拉伯数字，若读不出来，则传回0

{{#invoke:TemplateParameters|getNumberValue|hijk42lm}}→“42”
{{#invoke:TemplateParameters|getNumberValue|hijklm}}→“0”

用法

{{#expr: hijk42lm }}→“表达式错误：无法识别词语“hijk”。”
{{#expr:{{#invoke:TemplateParameters|getNumberValue|hijk42lm}} }}→“42”
{{#expr:hijklm }}→“表达式错误：无法识别词语“hijklm”。”
{{#expr:{{#invoke:TemplateParameters|getNumberValue|hijklm}} }}→“0”

arg_to_spstr与pass_spstr

功能：arg_to_spstr会将参数转变成一个可供pass_spstr使用的字串；pass_spstr可以将arg_to_spstr给出的参数套入模板语法

设计动机：批次大量传送参数的方案

{{#invoke:TemplateParameters|pass_spstr
 | code = {{{1}}}{{2}}{{{3}}}
 | args = {{#invoke:TemplateParameters|arg_to_spstr|A|B|C}}
}}

显示为“A-B-C”

argTrim

功能：适用于本系列模板的trim方案（delnowiki可正常使用{{trim}}），{{trim}}会导致使用“{{!}}”的后方内容被舍弃

一般Trim
- 模板内容{{#invoke:TemplateParameters|FormatingArguments|格式=[\[:{\{Trim{{!}} {\{\{1}\}\} }\}]\]|count=1|usingConditionalExpressions=yes}}
- 叫用模板{{<模板名稱>|一{{!}}遺失的內容}}
- 显示为：“一”
一般Trim + delnowiki
- 模板内容{{#invoke:TemplateParameters|FormatingArguments|格式=<nowiki>[[:{{Trim| {{{1}}} }}]]</nowiki>|delnowiki=1|count=1|usingConditionalExpressions=yes}}
- 叫用模板{{<模板名稱>|一{{!}}遺失的內容}}
- 显示为：“遗失的内容”
使用argTrim
- 模板内容{{#invoke:TemplateParameters|FormatingArguments|格式=[\[:{{((}}#invoke:TemplateParameters{{!}}argTrim{{!}}{{{1}}} {{))}}]\]|count=1|usingConditionalExpressions=yes}}
- 叫用模板{{<模板名稱>|一{{!}}遺失的內容}}
- 显示为：“遗失的内容”
使用argTrim + delnowiki
- 模板内容{{#invoke:TemplateParameters|FormatingArguments|格式=<nowiki>[[:{{#invoke:TemplateParameters|argTrim|{{{1}}} }}]]</nowiki>[\[:{\{#invoke:TemplateParameters{{!}}argTrim{{!}}{{{1}}} }\}]\]|count=1|usingConditionalExpressions=yes}}
- 叫用模板{{<模板名稱>|一{{!}}遺失的內容}}
- 显示为：“遗失的内容”

listArguments

功能：列出模板接收到的参数

用途：侦错用

输入{{#invoke:TemplateParameters|listArguments|A|B|C|99=D|E=F}}
显示为：

{{#invoke:}}呼叫参数:
1 : A

2 : B

3 : C

99 : D

E : F

call

功能：将模板参数转为Lua参数的方法，提供呼叫一些不支援以模板参数呼叫之Module。

用途：能让一些未提供模板参数呼叫之Module在不建立新Module的情况下由模板调用。

例如Module:yesno目前暂未支援由模板直接调用。

输入{{#invoke:TemplateParameters|call|Module:yesno|T}}
显示为：“1”（参见下方#回传值子章节）

参数：

第一参数为模板与模组名称，以点“ . ”运算子来从模组中获得函数名称，如“Module:Foo.bar”指的是Module:Foo中的function bar( )，需要注意的是，为了提升效能，因此判断是用简单的字串分割达成，因此若模组名称含有点“ . ”符号，则无法使用此功能。
其他参数则会依序传入指定的模组函数中

回传值：

若模组回传值为数字或字串，则会直接显示结果；
若模组回传值为布林值则：true以“1”表示，否则输出空字串。这是为了让结果能给{{#if:}}使用
若模组没有回传值则输出空字串；
若模组回传值为其他物件，则会尝试将物件转为JSON后输出。此步骤有可能因为物件中包含了无法JSON化的物件导致失败。

选项：

| isJSON = ：将所有输入参数视为JSON
部分模组中函数可能有需要传入特殊格式物件的需求，此时可以透过设定此选项来以JSON来输入支援的物件。

注意事项：若指定的模组中函数本身已支援模板调用则可能出错。因为支援模板调用的模组通常是用第一参数接收所有模板参数，而此函数会先将模板参数全部展开才传入，可能会有参数无效或者第一参数无法使用（如支援模板调用的第一参数预期是一个包含所有模板参数资讯的lua table，但本函数将参数展开可能导致第一参数变为字符串或数字）等问题。

templateArgWarp

功能：替换引用时，将自身替换为另一个模板与参数

用途：如防止替换引用（替换引用又换回自身）或替换引用时转成其他等价模板等。

参数：第一参数为要替换成的模板名称。只有第一参数有效，其余参数皆为从父模板读取。

makeTemplateParameter

功能：产生模板参数的未解析字串，如{{{arg}}}

用途：搭配{{虚拟模板}}作为替换引用的替代方案，参见{{参数}}。

输入{{#invoke:TemplateParameters|makeTemplateParameter|arg|default}}
显示为：“{{{arg|default}}}”

用途

Module:Number中，客制化的性质输出格式。
Module:PeriodicTable中，选择要在元素周期表输出的元素性质。