帮助:解析器函数

本页使用了标题或全文手工转换,现处于中国大陆简体模式
帮助页面

解析器函数是一个MediaWiki扩展,由mw:Extension:ParserFunctions提供。

ParserFunctions扩展提供11个额外的解析器函数以补充MediaWiki固有的“魔术字”。(有可能会配置到额外的解析器函数以支持运行;这些字符串函数已在其他文档页面记载。)

此扩展提供的所有解析器函数均采用以下形式:

{{#函数名: 参数1 | 参数2 | 参数3... }}

各函数名都对大小写不敏感。语句中的空格、换行等空白字符将被省略。

#expr

类型 运算符号
分组(括弧) ( )
数字 1234.5   e (2.718)   pi (3.142)
二进制运算符 e   一元 +,-
一元 not ceil trunc floor abs exp ln sin cos tan acos asin atan
二进制 ^
* / div mod
+ -
取整 round
逻辑 = != <> > < >= <=
and
or

这个函数计算数学表达式并返回计算值。 在nsp=0中可以通过mw.ext.ParserFunctions.expr来使用此函数。

{{#expr: 表达式 }}

右表依优先级列出了支持的运算符。运算结果的精度和格式受运行wiki服务器操作系统和站点语言的数字格式影响可能存在差异。

使用布尔代数时,0表示false,其他任何非0数值(无论正负)均表示true

{{#expr: 1 and -1 }}1
{{#expr: 1 and 0 }}0
{{#expr: 1 or -1 }}1
{{#expr: -1 or 0 }}1
{{#expr: 0 or 0 }}0

空表达式返回空值,无效的表达式返回错误信息,使用#iferror函数检查错误:

{{#expr: }}
{{#expr: 1+ }}表达式错误:缺少+的操作数。
{{#expr: 1 = }}表达式错误:缺少=的操作数。
{{#expr: 1 foo 2 }}表达式错误:无法识别词语“foo”。

置于数字前或数字后的加减号是有意义的,会被视为正负号而不会报错:

{{#expr: +1 }}1
{{#expr: -1 }}-1
{{#expr: + 1 }}1
{{#expr: - 1 }}-1

注意:使用魔术字输出数值时,首先要将其格式化以去除逗号,获得纯数字。例如:{{NUMBEROFUSERS}}输出1,190,而期望的输出值是1190,使用{{formatnum:{{NUMBEROFUSERS}}|R}}便可以实现。对于某些语言,格式化数字尤为重要。例如孟加拉语中,{{NUMBEROFUSERS}}的输出结果是৩০,০৬১。

{{#expr:{{NUMBEROFUSERS}}+100}} 表达式错误:无法识别标点符号“,”。
{{#expr:{{formatnum:{{NUMBEROFUSERS}}|R}}+100}}1290

如果你想要进行基于日期时间的计算(如检测当前日期时间是否超过指定日期时间),首先用{{#time: xNU }}将日期时间转换为距1970年1月1日的秒数,再对秒数进行加减运算。 → 如果你想要进行基于日期时间的计算(如检测当前日期时间是否超过指定日期时间),首先用1701982889将日期时间转换为距1970年1月1日的秒数,再对秒数进行加减运算。

四舍五入

将左边的数字四舍五入为1/10的幂的倍数,指数等于右边给出的数字的截断值(truncated value)。

向上、向下取整分别使用ceilfloor

案例 结果 舍入方式
{{#expr: 1/3 round 5 }} 0.33333 最终的数字小于5,所以没有明显的取整发生 (0.333333… → 0.33333)
{{#expr: 1/6 round 5 }} 0.16667 最终的数字大于5,所以被向上取整 (0.166666… → 0.16667)
{{#expr: 8.99999/9 round 5 }} 1 同理,最后一位数因后一位而加1,进而引起了前面的进位 (0.999998… → 1.00000 → 1)
{{#expr: 1234.5678 round -2 }} 1200 舍入至最近的整百数,负值在小数点左边。
{{#expr: 1234.5678 round 2 }} 1234.57 舍入至最近的整1/100数,因为正值会舍入至小数点右边。
{{#expr: 1234.5678 round 2.3 }} 1234.57 舍入指数的小数点在舍入结果中不起作用
{{#expr: trunc 1234.5678 }} 1234 小数部分被全部舍弃(截断)
四舍五入至最近的整数
{{#expr: 1/3 round 0 }} 0 向下取整至0
{{#expr: 1/2 round 0 }} 1 向上取整至1
{{#expr: 3/4 round 0 }} 1 向上取整至1
{{#expr: -1/3 round 0 }} -0 向上取整至0
{{#expr: -1/2 round 0 }} -1 向下取整至-1
{{#expr: -3/4 round 0 }} -1 向下取整至-1
使用ceil和floor向上或向下取整
{{#expr: ceil(1/3) }} 1 向上取整至1
{{#expr: floor(1/3) }} 0 向下取整至0
{{#expr: ceil(-1/3) }} -0 向上取整至0
{{#expr: floor(-1/3) }} -1 向下取整至-1
{{#expr: ceil 1/3 }} 0.33333333333333 没有取整,因为1本来就是整数

字符串

表达式函数只用于仅含有数字和运算符号的表达式,而字母字符串和其它符号不在此列。若需要比较字符串,可以用#ifeq替代。

{{#expr: "a" = "a" }}表达式错误:无法识别标点符号“"”。
{{#expr: a = a }}表达式错误:无法识别词语“a”。
{{#ifeq: a | a | 1 | 0 }}1

#if

这个函数判断一个字符串是否为空。只包含空格的字符串被视为空字符串。

{{#if: 测试字符串 | 测试字符串非空时的取值 | 测试字符串为空或仅包含空白字符时的取值 }}
{{#if: 参数1 | 参数2 | 参数3 }}

这个函数首先判断参数1是否为空。如果参数1不为空,则输出参数2。如果参数1为空或只包含空白内容(空格、换行等),则输出参数3。

{{#if: | yes | no}}no
{{#if: string | yes | no}}yes
{{#if:      | yes | no}}no
{{#if:


| yes | no}}
no

字符串内容会被处理为纯文本,因此不会计算数学表达式(参见#ifexpr):

{{#if: 1==2 | yes | no }}yes
{{#if: 0 | yes | no }}yes

最后一个参数(false)可以忽略:

{{#if: foo | yes }} yes
{{#if: | yes }}
{{#if: foo | | no}}

该函数可嵌套。为了做到这一点,嵌套内层的#if函数需要按规则完整填写所有参数以符合#if的参数形式。一般至多可嵌套7层,该数也可能为wiki自身限制和内存限制而有变动。

{{#if: 测试字符串 | 字符串非空时的值 | {{#if: 测试字符串 | 字符串非空时的值 | 字符串为空(或只有空格)的值 }} }}

你可以在#if条件句中以字符串变量代替测试字符串。在这里,你需要在变量名的后面加上|(分隔符)以正确引用字符串。 (因此如果参数没有值,则计算结果为一个空字符串而非"{{{1}}}"。)

{{#if:{{{1|}}}|你在变量1里面输入了文本|变量1里面没有文本}}

参见mw:Help:Parser functions in templates以了解更多关于解析器函数中变量的相关例子。

#ifeq

这个函数判断两个输入字符串是否相同,并根据结果输出两个字符串的其中一个。 如果需要更多的比较和输出字符串,请考虑使用#switch

{{#ifeq: string 1 | string 2 | value if identical | value if different }}

如果两个字符串均为数字,则函数会进行数值的比较:

{{#ifeq: 01 | 1 | equal | not equal}}equal
{{#ifeq: 0 | -0 | equal | not equal}}equal
{{#ifeq: 1e3 | 1000 | equal | not equal}}equal
{{#ifeq: {{#expr:10^3}} | 1000 | equal | not equal}}equal

否则,函数会进行文本的比较(大小写敏感):

{{#ifeq: foo | bar | equal | not equal}}not equal
{{#ifeq: foo | Foo | equal | not equal}}not equal
{{#ifeq: "01" | "1" | equal | not equal}}not equal  (对比上面没有引号的例子)
{{#ifeq: 10^3 | 1000 | equal | not equal}}not equal  (对比上面带有#expr的例子,会先回传一个有效的整数)

作为例子,考虑一个已存在的模板Template:Timer,该模板利用解析器来选择两个标准时间,short和long。 它以参数作为第一个输入来比较字符串“short”–这没有约定顺序,但是如果参数在第一个则更容易理解。 模板代码定义为:

{{#ifeq: {{{1|}}} | short | 20 | 40 }}

会产生如下结果:

{{timer|short}}20
{{timer|20}}40
{{timer}}40

#iferror

这个函数接收一个输入字符串,返回两个结果中的一个。如果输入字符串包含一个由其他解析器函数(比如#expr#time#rel2abs)、模板错误(比如模板循环和模板递归)或其他解析器“软错误”生成的class="error"的HTML对象,那么视为真。

{{#iferror: test string | value if error | value if correct }}

待返回字符串参数可以省略。若省略"correct"(正确)字符串参数,则在"test string"(测试字符串)不出错的情况下函数将返回被测字符串本身。若省略"error"(错误)字符串参数,则函数将在被测字符串出错时返回空字符串:

{{#iferror: {{#expr: 1 + 2 }} | error | correct }}correct
{{#iferror: {{#expr: 1 + X }} | error | correct }}error
{{#iferror: {{#expr: 1 + 2 }} | error }}3
{{#iferror: {{#expr: 1 + X }} | error }}error
{{#iferror: {{#expr: 1 + 2 }} }}3
{{#iferror: {{#expr: 1 + X }} }}
{{#iferror: {{#expr: . }} | error | correct }}correct
{{#iferror: <strong class="error">a</strong> | error | correct }}error

Some errors may cause a tracking category to be added, using {{#iferror:}} will not suppress the addition of the category.

#ifexpr

此函数会判断数学表达式并根据其布尔值结果返回对应的字符串:

{{#ifexpr: expression | value if true | value if false }}

这里"expression"输入串将原封不动的作为上面#expr的参数进行调用,且表达式运算符是通用的,返回值也将作为布尔表达式进行处理。

输入表达式为空时将视为false

{{#ifexpr: | yes | no}}no

如上面所提,0将视为false,非零值将视为true,因此这个函数与下面的仅用#ifeq#expr的表述等价:

{{#ifeq: {{#expr: expression }} | 0 | value if false | value if true }}

除了下面这种情况:所输入表达式为空或者是一个错误表达式(空串会返回一条错误信息,而它不等于0,所以在后者我们会得到"value if true")。

{{#ifexpr: = | yes | no }} 表达式错误:预期外的=运算符。

相对的

{{#ifeq: {{#expr: = }} | 0 | no | yes }} yes

两个返回值都可以省略,当合适的对应分支被省略时,函数不输出:

{{#ifexpr: 1 > 0 | yes }}yes
{{#ifexpr: 1 < 0 | yes }}
{{#ifexpr: 0 = 0 | yes }} yes
{{#ifexpr: 1 > 0 | | no}}
{{#ifexpr: 1 < 0 | | no}} no
{{#ifexpr: 1 > 0 }}

Boolean operators of equality or inequality operators are supported.

{{#ifexpr: 0 = 0 or 1 = 0 | yes}}yes
{{#ifexpr: 0 = 0 and 1 = 0 | | no}}no
{{#ifexpr: 2 > 0 or 1 < 0 | yes}}yes
{{#ifexpr: 2 > 0 and 1 > 0 | yes | no}}yes

#ifexist

这个函数将一组字符串作为输入,并翻译成页面标题,然后根据在本地wiki上是否存在该页面而返回对应的值。

{{#ifexist: page title | value if exists | value if doesn't exist }}

只要页面存在就会判定为true(真值),即便那个页面看上去是空白的(比如像是分类链接或者是魔术字解释页之类的却不包含任何可视内容的页面),或者是重定向页,或者它就是空白页。当且仅当页面是红链时判定为false(假值),包括那些曾经存在却被删除的页面。

{{#ifexist: Help:解析器函数 | exists | doesn't exist }}exists
{{#ifexist: XXHelp:解析器函数XX | exists | doesn't exist }}doesn't exist

函数在系统消息被自定义时返回true,对特殊页面的判定则取决于本地软件自身。

{{#ifexist: Special:监视列表 | exists | doesn't exist }}exists
{{#ifexist: Special:用户查核 | exists | doesn't exist }}exists (因为nsp=0扩展已经安装于此wiki)
{{#ifexist: MediaWiki:Copyright | exists | doesn't exist }}exists (因为MediaWiki:Copyright已自定义)

如果一个页面使用了#ifexist:来检查目标页面,则这个检查页面将出现在被检查页面的Special:链入页面里。所以如果本页面(Help:解析器函数)使用了代码 {{#ifexist:Foo}},那么Special:链入页面/Foo将列出Help:解析器函数。

若wiki有其在使用的对应的共享媒体库,#ifexist:就可用于检查一个文件是否在媒体库中,而不仅仅只是在wiki本体上检查:

{{#ifexist: File:Example.png | exists | doesn't exist }}exists
{{#ifexist: Image:Example.png | exists | doesn't exist }}exists
{{#ifexist: Media:Example.png | exists | doesn't exist }}exists

如果文件有一个已创建的对应的本地描述页面,上面的结果将全部是exists

#ifexist:不会对跨站链接起作用。

ifexist 限制

#ifexist:被视为“高开销(expensive)解析器函数”,每个页面调用这类函数的次数(包括包含于嵌入式模板的函数)存在一个限制。 当达到该限制时,更多的#ifexist:函数,无论其目标页面是否存在,只会自动返回错误值false,且该页面会被分类到Category:有过多高开销解析器函数调用的页面中。 追踪分类的名称可能因您的wiki内容的语言而异。

一些情况下,在css中使用选择器a.new(以选出链接到不存在的页面的链接)或者是a:not(.new)(以选出已存在页面的链接),是可以达到模仿ifexist的效果的。 另外,$wgExpensiveParserFunctionLimit可以调整对高开销解析器函数数量的限制,如果有需要,也可以增加页面LocalSettings.php中的限制值。

ifexisit和需要的页面

一个不存在的页面被#ifexist检测后会被计数在待创建页面中。

#rel2abs

这个函数将文件的相对路径转换为绝对路径。

{{#rel2abs: path }}
{{#rel2abs: path | base path }}

在输入项path中,可以使用以下类型的句法:

  • . → 本级路径
  • .. → 回到上一级
  • /foo → 向下一级进入子目录/foo

base path没有指定,将默认的填入函数所在页面的绝对路径:

{{#rel2abs: /quok | Help:Foo/bar/baz }}Help:Foo/bar/baz/quok
{{#rel2abs: ./quok | Help:Foo/bar/baz }}Help:Foo/bar/baz/quok
{{#rel2abs: ../quok | Help:Foo/bar/baz }}Help:Foo/bar/quok
{{#rel2abs: ../. | Help:Foo/bar/baz }}Help:Foo/bar

无效语法,如/././,将被忽略。 由于不允许超过两个连续的句号,因此可以使用诸如此类的序列来分隔连续的语句:

{{#rel2abs: ../quok/. | Help:Foo/bar/baz }}Help:Foo/bar/quok
{{#rel2abs: ../../quok | Help:Foo/bar/baz }}Help:Foo/quok
{{#rel2abs: ../../../quok | Help:Foo/bar/baz }}quok
{{#rel2abs: ../../../../quok | Help:Foo/bar/baz }}错误:路径深度无效:“Help:Foo/bar/baz/../../../../quok”(试图访问根节点之上的节点)。

For a similar group of functions see also Help:Magic words#URL data. Built-in parser functions include: 'localurl:', 'fullurl:', 'anchorencode:' etc.

#switch

该函数将一个输入值同若干个测试用例(test cases)做比较,如果找到匹配,返回有关联的字符串。

{{#switch: comparison string
 | case = result
 | case = result
 | ...
 | case = result
 | default result
}}

例如:

{{#switch: baz | foo = Foo | baz = Baz | Bar }} Baz
{{#switch: foo | foo = Foo | baz = Baz | Bar }} Foo
{{#switch: zzz | foo = Foo | baz = Baz | Bar }} Bar

含有部分嵌入包含标记的#switch会影响到能让不熟悉模板代码的编辑者查看和编辑可配置元素的配置文件。

默认

如果comparison string不能与任何case匹配,则返回default result

{{#switch: test | foo = Foo | baz = Baz | Bar }} Bar

在这种语法中,默认返回值必须是函数的最后一个参数,而且不能包含原始等号(不带{{}}的等号)。 否则,就会解析为样例比较,无匹配的样例时不显示文本。 这是因为默认值没有定义(是空的)。 如果有样例匹配,则返回关联的字符串。

{{#switch: test | Bar | foo = Foo | baz = Baz }} →
{{#switch: test | foo = Foo | baz = Baz | B=ar }} →
{{#switch: test | test = Foo | baz = Baz | B=ar }} → Foo

你也可以将case字符串设为#default从而清楚地声明默认值。

{{#switch: comparison string
 | case = result
 | case = result
 | ...
 | case = result
 | #default = default result
}}

这种方式声明的默认结果可以放在函数的任何地方:

{{#switch: test | foo = Foo | #default = Bar | baz = Baz }} Bar

如果"default"参数被省略,且没有找到匹配,则不返回结果:

{{#switch: test | foo = Foo | baz = Baz }}

分组结果

该函数允许有“跌落”值,多个"case"字符串返回相同的"result"字符串,从而减少重复。

{{#switch: comparison string
 | case1 = result1
 | case2 
 | case3 
 | case4 = result234
 | case5 = result5
 | case6 
 | case7 = result67
 | #default = default result
}}

在本例中,第二、三、四个分支都会返回"result234",第六和第七个分支都会返回"result67"。 上述案例中,最后一个参数中的“#default = ”可以省略。

带有参数使用

该函数允许将参数用作测试字符串。 在本例中,不必将管道符放在参数名称后面,因为你不太可能需要选择字符串“{{{parameter name}}}”作为样例。 ((如果没有管道符,且参数不存在或没有值,则参数就会显示为这样。) 参见Help:Parser functions in templates。)

{{#switch: {{{1}}} | foo = Foo | baz = Baz | Bar }}

上面的例子中,如果{{{1}}}等于foo,函数返回Foo。 如果等于baz,函数返回Baz。 如果参数是空的或者不存在,函数返回Bar

上面的这些中,也可以将样例组合起来以返回单个结果。

{{#switch: {{{1}}} | foo | zoo | roo = Foo | baz = Baz | Bar }}

如果{{{1}}}等于foozooroo,函数返回Foo。 如果等于baz,函数返回Baz。 如果参数是空的或者不存在,函数返回Bar

而且,如果你希望在测试参数不能匹配任何样例时不返回任何内容,可以省略默认结果。

{{#switch: {{{1}}} | foo = Foo | bar = Bar }}

在本例中,如果{{{1}}}存在且等于foobar,则分别返回FooBar,否则不返回任何内容。

这样做相当于将默认值声明为空。

{{#switch: {{{1}}} | foo | zoo | roo = Foo | baz = Baz | }}

如果由于某些原因需要将样例设置为{{{parameter name}}},则函数在参数不存在或没有值的情况下返回该样例的结果。 参数需要存在且拥有不同于字符串“{{{parameter name}}}”的值以返回函数的默认结果。

(若{{{1}}}不存在或者是空的):
{{#switch: {{{1}}} | {{{1}}} = Foo | baz = Baz | Bar }} Foo
(若{{{1}}}的值为test):
{{#switch: {{{1}}} | {{{1}}} = Foo | baz = Baz | Bar }} Bar
(若{{{1}}}的值为“{{{1}}}”):
{{#switch: {{{1}}} | {{{1}}} = Foo | baz = Baz | Bar }} Foo


在这样的例子中,你需要给参数添加管道符({{{1|}}})。

比较行为

如同#ifeq那样,若被比较字符串和测试用例字符串都是数字,那么按照数值进行比较;反之若存在一个非纯数字符串,都会按照字符串比较规则进行:

{{#switch: 0 + 1 | 1 = one | 2 = two | three}} → three
{{#switch: {{#expr: 0 + 1}} | 1 = one | 2 = two | three}} → one
{{#switch: a | a = A | b = B | C}} → A
{{#switch: A | a = A | b = B | C}} → C

case字符串可以是空的:

{{#switch: | = Nothing | foo = Foo | Something }}Nothing

只要找到一个匹配,后面的case都会忽略:

{{#switch: b | f = Foo | b = Bar | b = Baz | }}Bar

原始等号

“case”字符串不能包含原始等号。如果需要在比较串中加入等号,可以使用仅包含一个等号的模板模板链接:{{=}}来代替=,或者是用HTML标识码&#61;来代替。

例如:

您输入的 您输出的
{{#switch: 1=2
 | 1=2 = raw
 | 1<nowiki>=</nowiki>2 = nowiki
 | 1{{=}}2 = template
 | default
}}
template
{{#switch: 1=2
 | 1&#61;2 = html
 | default
}}
html

替换#ifeq

#switch可以用于减少扩展深度

例如:

  • {{#switch:{{{1}}} |condition1=branch1 |condition2=branch2 |condition3=branch3 |branch4}}

等效于

  • {{#ifeq:{{{1}}}|condition1 |branch1 |{{#ifeq:{{{1}}}|condition2 |branch2 |{{#ifeq:{{{1}}}|condition3 |branch3 |branch4}}}}}}

也就是线性的深度迭代判断:

{{#ifeq:{{{1}}}|condition1
  |<!--then-->branch1
  |<!--else-->{{#ifeq:{{{1}}}|condition2
                |<!--then-->branch2
                |<!--else-->{{#ifeq:{{{1}}}|condition3
                              |<!--then-->branch3
                              |<!--else-->branch4}}}}}}

另一方面,对于嵌套在两个分支中的if(以缩进形式呈现,两侧都缩进),替换成switch可能很复杂/不切实际,从而形成对称树:

{{#ifeq:{{{1}}}|condition1
 |<!--then-->branch1t{{
  #ifeq:{{{1}}}|condition2
   |<!--then-->branch1t2t{{#ifeq:{{{1}}}|condition4|<!--then-->branch1t2t4t|<!--else-->branch1t2t4e}}
   |<!--else-->branch1t2e{{#ifeq:{{{1}}}|condition5|<!--then-->branch1t2e5t|<!--else-->branch1t2e5e}}
  }}
 |<!--else-->branch1e{{#ifeq:{{{1}}}|condition3
   |<!--then-->branch1e3t{{#ifeq:{{{1}}}|condition6|branch1e3t6t|branch1e3t6e}}
   |<!--else-->branch1e3e{{
    #ifeq:{{{1}}}|condition7
     |branch1e3e7t
     |branch1e3e7t
    }}
  }}
}}

#time

该解析器函数接收一个(公历的)日期或者时间,并根据给定的语法将其格式化。可以指定日期/时间对象,默认则为魔术字Help:魔术字#Date and time的当前值——也就是说,页面最后被渲染为HTML时的时间。

{{#time: format string }}
{{#time: format string | date/time object }}
{{#time: format string | date/time object | language code }}
{{#time: format string | date/time object | language code | local }}

右表列举了支持的格式化代码。任何不被识别的格式化字符串都不会被修改,这同样适用于空白字符(系统不使用空白字符来解释代码)。格式化字符串内有两种方法来转义字符:

  1. 反斜杠后跟随一个格式化字符串会被解释为单个原始的字符
  2. 用英文双引号括起来的字符视为原始字符,引号将被移除。

此外,xx会被解释为单个原始的x。

由于格式化代码列表会持续发展(支持新日历,或支持以不同方式计算和格式化的新日期字段),您应该转义所有需要传入而保持不变的文字字符(不仅仅是格式化代码当前使用的ASCII字母)。

不幸的是,目前,ASCII单引号仍未被视为当前已经受支持的ASCII双引号(可标记文字文本)和反斜杠(在许多语言使用的字符串常量中也必须转义,包括JSON、C、C++、PHP、JavaScript、Lua)的简单替代方法(例如,双引号在其他用途​​中是强制性的,例如JSON、C、C++等语言中的字符串值的定界)。 因此,您仍然无法在不使用反斜杠转义的情况下嵌入任何文字双引号(或者也可以使用其他弯引号、角形引号或方引号)。

{{#time: Y-m-d }}2023-12-07
{{#time: [[Y]] m d }}2023 12 07
{{#time: [[Y (year)]] }}2023 (23UTCpmThu, 07 Dec 2023 21:01:29 +0000)
{{#time: [[Y "(year)"]] }}2023 (year)
{{#time: i's" }}01'29"

date/time object可以是任何PHP strtotime()函数接受的格式。 绝对(如20 December 2000)、相对(如+20 hours)和混合时间(如30 July +1 year)格式均是可以的。

{{#time: r|now}}Thu, 07 Dec 2023 21:01:48 +0000
{{#time: r|+2 hours}}Thu, 07 Dec 2023 23:01:49 +0000
{{#time: r|now + 2 hours}}Thu, 07 Dec 2023 23:01:49 +0000
{{#time: r|20 December 2000}}Wed, 20 Dec 2000 00:00:00 +0000
{{#time: r|December 20, 2000}}Wed, 20 Dec 2000 00:00:00 +0000
{{#time: r|2000-12-20}}Wed, 20 Dec 2000 00:00:00 +0000
{{#time: r|2000 December 20}}错误:时间无效。

ISO 639-3(?)中的language code允许字符串显示为指定语言。

{{#time:d F Y|1988-02-28|nl}}28 februari 1988
{{#time:l|now|uk}}четвер
{{#time:d xg Y|20 June 2010|pl}}20 czerwca 2010

local参数指定date/time object是指本地时区还是UTC时间。

这是一个布尔参数,其值是通过转换(casting)参数值来确定的(有关如何将字符串转换为布尔值的详细信息,请参阅官方PHP文档)。

请注意,如果$wgLocaltimezone设为UTC,则当local设为truefalse时输出无区别。

参考下面的详细示例:

{{#time: Y F d H:i:s|now|it|0}}2023 dicembre 07 21:01:50
{{#time: Y F d H:i:s|now|it|1}}2023 dicembre 08 05:01:51
{{#time: Y F d H:i:s|+2 hours||0}}2023 12月 07 23:01:51
{{#time: Y F d H:i:s|+2 hours||1}}2023 12月 08 07:01:51
{{#time:c|2019-05-16T17:05:43+02:00|it}}2019-05-16T15:05:43+00:00
{{#time:c|2019-05-16T17:05:43+02:00|it|0}}2019-05-16T15:05:43+00:00
{{#time:c|2019-05-16T17:05:43+02:00|it|true}}2019-05-16T23:05:43+08:00

如果你已经计算了Unix时间戳,你可以通过添加@符号前缀来在日期计算中使用。

{{#time: U | now }}1701982912
{{#time: r | @1701982889 }}Thu, 07 Dec 2023 21:01:29 +0000

可以指定完整的或部分绝对的日期;函数会使用“当前”值“填充”日期中未被指定的部分。

{{#time: Y | January 1 }}2023

4位数字总是被解读为年分,而不是小时和分钟:

{{#time: Y m d H:i:s | 1959 }}1959 12 07 00:00:00

6位数字尽量被解读为小时、分钟、秒,不然会被解读为错误(而不是年份和月份):

{{#time: Y m d H:i:s | 195909 }}2023 12 07 19:59:09 输入被视为时间而不是年+月代码。
{{#time: Y m d H:i:s | 196009 }}错误:时间无效。 虽然19:60:09不是有效时间,但196009不被解读为1960年9月。

该函数执行一定数量的日期算数:

{{#time: d F Y | January 0 2008 }}31 12月 2007
{{#time: d F | January 32 }}错误:时间无效。
{{#time: d F | February 29 2008 }}29 2月
{{#time: d F | February 29 2007 }}01 3月
{{#time:Y-F|now -1 months}}2023-11月

#time调用的格式字符串的总长度限制为6000个字符。

时区问题

#time解析器函数有个bug(尤其是PHP DateTime),不允许传入非整数的相对时区偏移。这个问题不适用于使用基于小时的时区,例如EDT。例如:

  • {{#time:g:i A | -4 hours }} → 5:01 PM

但是,印度(India)是UTC +5.5个小时的时间偏移,因此使用时区不会正常地计算相对时区偏移。因此:

  • {{#time:g:i A | +5.5 hours }} → 9:01 PM

要解决这个问题,可将时间简单转换为分钟或者秒,像这样:

  • {{#time:g:i A | +330 minutes }} → 2:31 AM
  • {{#time:g:i A | +19800 seconds }} → 2:31 AM

(Tim Starling,该函数的开发者,提供了该解决方案的准确语法。)

#timel

该函数等价于{{#time: ... }},其中local参数设置为true,因此总是使用wiki的本地时间($wgLocaltimezone中设置的)。

该函数的语法为:

{{#timel: format string }}
{{#timel: format string | date/time object }}
{{#timel: format string | date/time object | language code }}
请注意,如果变量$wgLocaltimezone设为UTC,则当local设为truefalse时输出无区别。
使用#time和#timel解析器函数的示例,其中服务器处于非UTC时区

例如,参考以下示例:

{{#time:c|now|it}}2023-12-07T21:01:58+00:00
{{#time:c|now|it|0}}2023-12-07T21:01:58+00:00
{{#time:c|now|it|1}}2023-12-08T05:01:58+08:00
{{#timel:c|now|it}}2023-12-08T05:01:58+08:00

#titleparts

此函数将页面标题根据斜杠划分成多个分段,然后输出返回这些分段中的部分。

{{#titleparts: 页面名称 | 需要返回的分段数量 | 要返回的第一个分段 }}

如果没有指定要返回的分段数量参数,则默认为“0”,会从要返回的第一个分段(包含)开始返回所有分段。如果要返回的第一个分段参数没有指定或者为“0”,则默认为“1”。

{{#titleparts: Talk:Foo/bar/baz/quok }}Talk:Foo/bar/baz/quok
{{#titleparts: Talk:Foo/bar/baz/quok | 1 }}Talk:Foo See also {{ROOTPAGENAME}}.
{{#titleparts: Talk:Foo/bar/baz/quok | 2 }}Talk:Foo/bar
{{#titleparts: Talk:Foo/bar/baz/quok | 2 | 2 }}bar/baz
{{#titleparts: Talk:Foo/bar/baz/quok | | 2 }}bar/baz/quok
{{#titleparts: Talk:Foo/bar/baz/quok | | 5 }}

两个值都接受负值。要返回的分段数量参数的负值会从字符串的最后开始“剥离”分段。要返回的第一个分段参数的负值解释为“从这一分段开始,从右边开始计数”:

{{#titleparts: Talk:Foo/bar/baz/quok | -1 }}Talk:Foo/bar/baz 从字符串的末尾剥离一段 参见{{BASEPAGENAME}}。
{{#titleparts: Talk:Foo/bar/baz/quok | -4 }} 从字符串的末尾剥离所有4段
{{#titleparts: Talk:Foo/bar/baz/quok | -5 }} 从字符串的末尾剥离5段(多于已存在的)
{{#titleparts: Talk:Foo/bar/baz/quok | | -1 }} quok 返回最后一段。 参见{{SUBPAGENAME}}。
{{#titleparts: Talk:Foo/bar/baz/quok | -1 | 2 }} bar/baz 从字符串的末尾剥离一段,然后返回第二段及以后的段
{{#titleparts: Talk:Foo/bar/baz/quok | -1 | -2 }} baz 从倒数第二个元素开始复制;从字符串的末尾剥离一段

处理前,页面名称参数是HTML解码的:如果包含一些标准的HTML字符实体,将被转换为纯字符(内部使用UTF-8编码,也就是与使用解析器函数的MediaWiki源页面中的编码相同)。

例如,页面名称中出现了&quot;&#34;&#x22;的地方,都会替换为"
不会执行从HTML到纯文本的其他转换,因此即使HTML标签在页面标题中无效,在此初始步骤中也会保持不变。

解码后的页面名称会尽可能标准化为MediaWiki支持的标准页面名称:

  1. 所有下划线都自动替换为空格:
    {{#titleparts: Talk:Foo/bah_boo|1|2}}bah boo 不是bah_boo,尽管原来的内容有下划线。
  2. 字符串最多分割25此;更多的斜杠都会忽略,第25个元素将会包含字符串的剩余内容。 字符串也限制在255个字符内,因为要被视为页面标题
    {{#titleparts: a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z/aa/bb/cc/dd/ee | 1 | 25 }}y/z/aa/bb/cc/dd/ee
    如果出于某些原因确实要将此函数推到极限(尽管不太可能),可以通过嵌套函数调用来绕过只能分割25此的限制:
    {{#titleparts: {{#titleparts: a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z/aa/bb/cc/dd/ee| 1 | 25 }} | 1 | 2}}z
  3. 最后,第一个子字符串根据本地wiki的大小写设置进行大写(如果该子字符串也以本地命名空间名称开头,则该命名空间名称也被标准化)。
    {{#titleparts: talk:a/b/c }}Talk:A/b/c


字符串函数

所有这些函数(len, pos, rpos, sub, replace, explode)都融合在了StringFunctions扩展中,但是只有在管理员在LocalSettings.php中启用了$wgPFEnableStringFunctions = true;的情况下才能使用。

所有这些函数都以O(n)的时间复杂度运行,使其能够抵御DoS攻击。

  1. 这些函数的部分参数通过全局设置进行限制,以防止滥用。 参见后面的限制段落。
  2. 对于区分大小写的函数,在某些情况下,可以使用魔术字{{lc:string}}来解决。
  3. 要确定MediaWiki服务器是否启用这些功能,请检查Special:Version中支持的扩展解析器函数列表。
  4. 字符串长度限制为$wgPFStringLengthLimit变量,默认为1000

#len

#len解析器函数是在1.2.0版本从nsp=0扩展合并的。

#len函数返回指定字符串的长度。 语法为:

{{#len:string}}

返回值始终是源string中的字符数量(扩展模板调用之后、转换为HTML之前的字符数量)。 如果未指定字符串,则返回值为零。

  • 此函数可安全处理UTF-8多字节字符。 例如:
    • 88
  • 前导和尾随的空格或换行不计算在内,但会考虑中间的空格和换行。 例如:
    • 88
    • 205 - 2个字符之间3个空格
  • 通过引用给出的字符不会转换,而是根据其源格式进行计数。
    • 106 - 命名的字符引用
    • 95 - 数字字符引用,不被忽略,尽管它在此处指定了一个空格。
  • <nowiki>和其他标签扩展的长度总是为零,因为这些内容对解析器而言是隐藏的。 例如:
    • 374

#pos

#pos解析器函数是在1.2.0版本从nsp=0扩展合并的。

#pos函数返回给定搜索词在字符串中的位置。 语法为:

{{#pos:string|搜索词|offset}}

offset参数如果指定了,则会表明函数应该开始搜索的起始位置。

如果找到了搜索词,则返回的值是字符串string中的位置(从0开始数)。

如果没有找到搜索词,函数返回空字符串。

  • 该函数是大小写敏感的。
  • 搜索词允许的最大长度限制取决于全局设置$wgStringFunctionsLimitSearch
  • 此函数可安全处理UTF-8多字节字符。 示例: {{#pos:Žmržlina|žlina}}返回3。
  • #len一样,<nowiki>和其他标签扩展在计算字符位置时都被视为长度为1。 例如: {{#pos:<nowiki>This is a </nowiki>test|test}}返回1。

#rpos

#rpos解析器函数是在1.2.0版本从nsp=0扩展合并的。

#rpos函数返回给定搜索词在字符串中的最后位置。 语法为:

 {{#rpos:string|搜索词}}

如果找到了搜索词,则返回的值是字符串string中的最后位置(从0开始数)。

如果没有找到搜索词,函数返回-1。

使用该函数搜索最后一个分隔符时,给结果添加+1以检索最后一个分隔符之后的位置。 这在找不到分隔符时也有效,因为“-1 + 1”为零,也就是指定值的开头。 → 使用该函数搜索最后一个分隔符时,给结果添加+1以检索最后一个分隔符之后的位置。 这在找不到分隔符时也有效,因为“-1 + 1”为零,也就是指定值的开头。

  • 该函数是大小写敏感的。
  • 搜索词允许的最大长度限制取决于全局设置$wgStringFunctionsLimitSearch
  • 此函数可安全处理UTF-8多字节字符。 例如: {{#rpos:Žmržlina|lina}}返回4。
  • #len一样,<nowiki>和其他标签扩展在计算字符位置时都被视为长度为1。 例如: {{#rpos:<nowiki>This is a </nowiki>test|test}}返回1。

#sub

#sub解析器函数是在1.2.0版本从nsp=0扩展合并的。

#sub函数返回指定字符串中的子字符串(substring)。 语法为:

{{#sub:string|start|length}}

start参数,如果为正(或者零),则会指定要返回的第一个字符的索引(从0开始数)。

例如: {{#sub:Icecream|3}}返回cream

{{#sub:Icecream|0|3}}返回Ice

如果start参数为负,则指定要返回从末尾开始的多少个字符。

例如: {{#sub:Icecream|-3}}返回eam

length参数,如果存在且为正数,则会指定返回的字符串的最大长度。

例如: {{#sub:Icecream|3|3}}返回cre

如果length参数为负,则指定忽略从末尾开始的多少个字符。

例如: {{#sub:Icecream|3|-3}}返回cr

如果start参数为负,则指定要返回从末尾开始的多少个字符。 length参数,如果存在且为正数,则会指定返回的字符串从开始点开始的最大长度。

例如: {{#sub:Icecream|-3|2}}返回ea

  • 如果length参数为零,则完全不会用于截断。
    • 例如: {{#sub:Icecream|3|0}}返回cream{{#sub:Icecream|0|3}}返回Ice
  • 如果start表示一个超出了由负的length参数从末尾截断的位置,则将返回一个空字符串。
    • 例如: {{#sub:Icecream|3|-6}}返回空字符串
  • 此函数可安全处理UTF-8多字节字符。 例如: {{#sub:Žmržlina|3}}返回žlina
  • #len一样,<nowiki>和其他标签扩展在计算字符位置时都被视为长度为1。 例如: {{#sub:<nowiki>This is a </nowiki>test|1}}返回test

#count

#count解析器函数是在1.2.0版本添加到nsp=0扩展中的。

#count函数返回指定子字符串在提供的文本中出现的次数。

{{#count:string|substring}}

#replace

#replace解析器函数是在1.2.0版本从nsp=0扩展合并的。

#replace函数返回指定的字符串,并将所有搜索词出现的地方替换成替换词。

{{#replace:string|search term|replacement term}}

如果search term未指定或者为空,则搜索单个空格。

如果replacement term未指定或者为空,则所有search term都会从string中移除。

  • 该函数是大小写敏感的。
  • search term允许的最大长度限制取决于全局设置$wgStringFunctionsLimitSearch
  • replacement term允许的最大长度限制取决于全局设置$wgStringFunctionsLimitReplace
  • 即使replacement term是空格,也会使用空字符串。 * 这是MediaWiki解析器的副作用。 如要在replacement term中使用空格,将其放在nowiki标签中。
    • 例如: {{#replace:My_little_home_page|_|<nowiki> </nowiki>}}返回My little home page
    • 如果不起作用,尝试使用带有两个自我闭合标签的{{#replace:My_little_home_page|_|<nowiki/> <nowiki/>}}
    • 注意在替换词中这是唯一可以使用nowiki的地方',因为其他的nowiki都会被用来绕过$wgStringFunctionsLimitReplace,将任意大量的字符串注入到输出中。 因此,在替换词中所有出现<nowiki>或其他标签扩展的地方都会替换为空格。
  • 此函数可安全处理UTF-8多字节字符。 例如: {{#replace:Žmržlina|ž|z}}返回Žmrzlina
  • 如果单个文本字符串中的多个项都要替换,可以考虑Extension:ReplaceSet。 该扩展会添加一个空余替换序列的解析器函数。
忽略大小写的替换

当前该语法不提供开关大小写敏感设置的选项。 但你可以使用格式化的魔术字来解决。 (例如,{{lc:你的字符串}}) 例如,如果想从字符串中删除单词“Category:”而不管其大小写,可以输入:

{{#replace:{{lc:{{{1}}}}}|category:|}}

但缺点就是输出的都会变成小写。 如果想在替换后保留大小写,则必须使用多个嵌套级别(即多次替换调用)来实现相同的目的。

#explode

#explode解析器函数是在1.2.0版本从nsp=0扩展合并的。

#explode函数将指定的字符串分成多个片段,返回其中一段。 语法为:

{{#explode:string|delimiter|position|limit}}

delimiter参数指定一个用来将string划分成段的字符串。 这个delimiter字符串不是任何片段的一部分,如果有两个delimiter彼此相邻,会在二者之间创建一个空片段。 如果该参数未指定,则使用单个空格。 limit参数仅在解析器函数中可用,在独立的字符串函数版本中不可用,允许你限制返回的部分的数量,所有剩余文本都包含在最终部分中。

position参数指定了返回哪一个片段。 片段是从0开始数的。 如果参数未指定,则使用第一个片段(数字0的片段)。 如果position使用负值,则片段会从最后开始数。 这种情况下,第-1个片段表示最后一段。 例如:

  • {{#explode:And if you tolerate this| |2}} 返回 you
  • {{#explode:String/Functions/Code|/|-1}} 返回 Code
  • {{#explode:Split%By%Percentage%Signs|%|2}} 返回 Percentage
  • {{#explode:And if you tolerate this thing and expect no more| |2|3}} 返回 you tolerate this thing and expect no more

返回的值是第position个片段。如果片段数量少于position指定的,则返回空字符串。

  • 该函数是大小写敏感的。
  • delimiter允许的最大长度限制由全局设置$wgStringFunctionsLimitSearch指定。
  • 该函数可以安全处理UTF-8多字节字符,例如{{#explode:Žmržlina|ž|1}}返回lina

#urldecode

#urldecode将“URL编码的转义字符转换回原来的可读字符。语法为:

{{#urldecode:值}}

注意:

  • 该函数是通过直接暴露PHP的urldecode()函数来运作的。
  • 字符代码参考可参见www.w3schools.com
  • 与此相反的urlencode,已经融合在了MediaWiki的1.18版本中,具体示例可参见帮助:魔术字。
  • urldecode是在2010年从字符串函数通过commit 1b75afd18d3695bdb6ffbfccd0e4aec064785363合并的。

限制

本模块定义三个全局设置:

这些用于限制一些函数的部分参数以确保函数在O(n)时间复杂度内运行,因此可避免Dos攻击,确保安全。

$wgStringFunctionsLimitSearch

#pos#rpos#replace#explode都使用了此设置。所有这些函数在运行时都会在更大的字符串中搜索子字符串,这可以在O(n*m)内运行,因此使软件更容易受到DoS攻击。将此值设置为特定的更小的数,可将时间复杂度降低到O(n)。

此设置限制了所搜索字符串的最大允许长度。

默认值为30个多字节字符。

$wgStringFunctionsLimitReplace

#replace使用了此设置。此函数将一个字符串的所有出现的地方替换为另一个字符串,这样将能够快速生成非常大量的数据,因此使软件更容易受到DoS攻击。此设置限制了替换字符串的最大允许长度。

默认值为30个多字节字符。

一般帮助

替换引用

在井号前面添加subst:可以将字符串函数替换引用

{{subst:#ifexist: Help:解析器函数 | [[Help:解析器函数]] | Help:解析器函数 }} → 将在文本中插入代码[[Help:解析器函数]],因为Help:解析器函数存在。

<ref>open…</ref></ref>内的替换引用不起作用,如要使用,可以使用{{subst:#tag:ref|}}

重定向

特别地,{{#time:…|now-…}}可以方便地重定向到包含日期的页面,但这不起作用。

在表格中转义管道符

解析器函数会破坏wikitable语法和管道字符(|),将所有的原始管道字符视为参数分隔符。 为了避免这个,很多wiki使用模板Template:!,其内容仅为一个管道符(|),自MediaWiki 1.24开始被{{! 魔术字}}取代。 这会从MediaWiki解析器中“隐藏”管道符号,确保在展开页面上的所有模板和变量之前不考虑它。 然后将被解释为表格的行或列分隔符。 你也可以使用原始的HTML表格语法,尽管这并不直观而且容易出错。

对于需要显示的管道字符,可以使用HTML实体进行转义,显示为纯粹的、未被解释的字符:&#124;

说明 您输入的 您输出的
将管道字符转义为表格行/列分隔符
{{!}}
|
将管道字符转义为纯字符
&#124;
|


除去空白字符

空白字符(whitespace),包括换行符、制表符和空格,在这些解析器函数的所有参数的开头和结尾处,都会被除去。如果不希望这样,可以将字符串放在引号中后进行比较。

{{#ifeq: foo           |           foo | equal | not equal }}equal
{{#ifeq: "foo          " | "          foo" | equal | not equal }}not equal

要避免修整then和else部分,一些人为达到目的,会使用<nowiki> </nowiki>而非空格。

foo{{#if:|| bar }}foofoobarfoo
foo{{#if:||<nowiki /> bar <nowiki />}}foofoo bar foo

然而,这种方法只能用于渲染单个空白字符,因为解析器函数会将一行中的多个空白字符挤压成一个。

<span style="white-space: pre;">foo{{#if:||<nowiki/>      bar      <nowiki/>}}foo</span>
foo bar foo

在本例中,white-space: pre样式用来强制浏览器保留空白,但即使使用它,也不会显示空格。发生这种情况是因为这些空格在发送到浏览器之前,就已经被软件除去了。

要解决此问题,可以将空白字符替换为&#32;可折行空格)或者&nbsp;不可折行空格),因为这些字符不会被软件修改:

<span style="white-space: pre;">foo{{#if:||&#32;&#32;&#32;bar&#32;&#32;&#32;}}foo</span>foo bar foo
foo{{#if:||&nbsp;&nbsp;&nbsp;bar&nbsp;&nbsp;&nbsp;}}foofoo   bar   foo

请注意,不是所有的参数都是一样的。在解析器函数中,开头和结尾的空白总是被剥离。在模板中,命名的参数和命名的非命名参数的开头和结尾的空白会被剥离,但非命名的参数则不会。

foo模板链接:{{1x|content= bar }}foofoo{{{1}}}foo
foo模板链接:{{1x|1= bar }}foofoobarfoo
foo模板链接:{{1x| bar }}foofoo bar foo

参见