模組:TemplateParameters/doc

此模块文档被引用於約908,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中，選擇要在元素週期表輸出的元素性質。