wiki:高级语法:模板 [ACWiki ——硬核二次元文娱百科]

本页面只读。您可以查看源文件，但不能更改它。如果您觉得这是系统错误，请联系管理员。
====== 模板 ======
===== 语法概述 =====
您可以使用''%%[|%%//模板名//%%|%%//模板参数1//%%|%%//模板参数2//%%|%%//...//%%|%%//模板参数n//%%|]%%''来插入一个模板页面((与MediaWiki的模板功能语法比较类似。))。

===== 什么是 “模板”？ =====
“模板” 是一类用于调用的页面，其本质与普通页面无异，用户可以通过调用模板，将其内容插入到其他的页面当中。此外，模板内还可以设置若干参数，用户可以输入参数的值来达到修改模板内部分内容的目的。

请注意，在DokuWiki中，“模板” 一词通常是 “主题” 的同义词，但这里的 “模板” 一词没有 “主题” 或 “样式” 的意思。

===== 模板的创建与调用 =====
==== 存放模板的命名空间 ====
模板一般情况下会统一放置在一个命名空间内，默认的命名空间是''template''。

为叙述方便，下文会将''template''这个命名空间视作存放模板的命名空间。

==== 创建模板 ====
创建模板的方法与创建普通页面的方法无异。

例如想创建一个名叫''example''的模板，只需在''template''命名空间当中创建一个叫''example''的页面即可。换句话说，即创建''template:example''页面。

==== 调用模板 ====
调用模板最基本的语法是：''%%[|模板名|]%%''。

例如，''example''模板内有如下内容：
<code>
Hello world.
</code>
然后我们在下面一段文字中调用它：
<code>
The template says: "[|example|]"
</code>
输出的结果是
> The template says: "Hello world."

请注意，如果此模板存放于专门存放模板的命名空间中，则模板名中可以不写存放模板的命名空间。例如，想调用存放在''template''命名空间当中的''example''模板时：
  * ''%%[|example|]%%''——可以正确地调用
  * ''%%[|template:example|]%%''——不能正确地调用，这会定位到''template:template:example''页面

===== 参数设置 =====
在模板中，可以设置一些参数，以使模板内的内容产生变化。用户在调用模板时，给各参数赋予不同的参数值，模板内相应的参数所在的位置也会被参数值所替代。

==== 参数 ====
参数使用三个花括号包围：''%%{{{%%//参数名//%%}}}%%''。

参数名建议用字母和数字的组合，例如''%%{{{1}}}%%''、''%%{{{title}}}%%''、''%%{{{argu1}}}%%''等等。

==== 含有参数的调用 ====
含有参数调用的语法是：''%%[|%%//模板名//|//参数名1=参数值1//|//参数名2=参数值2//|...%%|]%%''。

如果某些参数值没有指明参数名，暂且称其为“无名参数”，就像下面的样子：
<code>
[|example|A|B|C|...|]
</code>
那么参数名会被指定为该参数值的次序，也就是给它们 “编号”，相当于：
<code>
[|example|1=A|2=B|3=C|...|]
</code>
请注意，这种对于无名参数的编号方法与MediaWiki中的有所不同。

例如，''example''模板内有如下内容：
<code>
Hello {{{1}}}.
</code>
然后我们在下面一段文字中调用它：
<code>
The template says: "[|example|1=my friend|]"
</code>
输出的结果是
> The template says: "Hello my friend."

==== 参数的默认值 ====
含默认值的参数语法为：''%%{{{%%//参数名=默认值//%%}}}%%''。
对于含默认值的参数，在调用模板时如果不规定其参数值，那么会输出其默认参数。

例如，''example''模板内有如下内容：
<code>
Hello {{{1=world}}}.
</code>
然后我们在下面一段文字中调用它：
<code>
指定参数值：[|example|1=my friend|]

不指定参数值：[|example|]
</code>
输出的结果是
> 指定参数值：Hello my friend.
>
> 不指定参数值：Hello world.

==== 参数值中特殊字符的处理 ====
由于''|''起到分隔参数的作用，第一个''=''起到分隔参数名和参数值的作用，因此在参数值中无法直接使用这两个字符。

对于''|''，如确实需要在参数值中使用（比如创建一个表格），请使用''~~!~~''替代。

对于''=''，如确实需要在没有指明参数名参数值中使用，请在参数值开头加一个''=''。例如想要让''%%[|example|1+1=2|...|]%%''第一个参数的参数值是''1+1=2''，那么可以写成：''%%[|example|=1+1=2|...|]%%''。

===== noinclude 与 includeonly =====
''%%<noinclude>%%''与''%%<includeonly>%%''标签是用在模板页面的两个标签。被''%%<noinclude>%%''包围的内容只在模板页显示，而被''%%<includeonly>%%''包围的内容只在被调用的地方显示。

因此，建议''%%<noinclude> ... </noinclude>%%''用来存放对模板的说明，而''%%<includeonly> ... </includeonly>%%''用来存放模板本身的内容，并起到在模板页隐藏模板内容的作用。

例如，''example''模板内有如下内容：
<code>
<noinclude>
这是对模板的说明。
</noinclude>

<includeonly>
这是模板本身的内容。
</includeonly>
</code>
''example''模板本身的页面显示如下：
> 这是对模板的说明。

然后我们在其他页面调用它：
<code>
[|example|]
</code>
输出的结果是：
> 这是模板本身的内容。

===== 模板应用举例 =====
==== 产生有颜色的文本 ====
模板''red''((实现此功能需要打开“允许嵌入式HTML”（''htmlok''）功能。))：
<code>
<html><span style="color:red"></html>{{{1}}}<html></span></html>
</code>
调用：
<code>
[|red|这是红色的字。|]
</code>

==== 给汉字注拼音 ====
模板''ruby''((实现此功能需要打开“允许嵌入式HTML”（''htmlok''）功能。))：
<code>
<html><ruby><rb></html>
{{{1}}}
<html></rb><rp>（</rp><rt></html>
{{{2}}}
<html></rt><rp>）</rp></ruby></html>
</code>
调用：
<code>
[|ruby|我|wǒ|][|ruby|们|men|]
</code>

当然这里只列举了模板的两种应用，实际上可能有更多的应用。

===== 注意事项 =====
==== 关于缓存 ====
当一个模板内容改变时，引用该模板的页面的内容却不会改变，除非修改这个页面以重新生成缓存。关于这个问题，目前折中的办法是尽量少去修改模板的内容。

==== 模板的重命名 ====
如要重命名一个模板，**请勿**使用页面右侧的“页面重命名”按钮((这个功能是由Move插件实现的。))进行重命名，否则会影响应用该模板的页面的渲染效果。