Help:链接解析器函数

这个页面【Help:链接解析器函数】是Vocawiki的帮助文档

本文用于介绍Vocawiki中一些特定功能的操作方法；
本文仅是一篇论述，不属于方针。如果本指南与相关方针发生冲突或存在不一致的情况，请以方针的条文为准。

本页介绍Vocawiki的LinkFunctions扩展提供的解析器函数。wikitext原生的[[ ]]与[ ]语法无法设定链接的HTML属性，本扩展补上了这一能力。

本扩展提供三个解析器函数：

解析器函数	对应原生语法	用途
`#link`	`[[ ]]`	内部链接
`#externallink`	`[ ]`	外部链接
`#plainlink`	无	朴素链接

内部链接

{{#link}}等价于[[ ]]，并可以设定HTML属性。

{{#link:页面名称|显示内容}}
{{#link:页面名称|显示内容|class=my-link}}
{{#link:页面名称|显示内容|class=my-link|style=color: red|title=提示}}
{{#link:#锚点|显示内容}}
{{#link:页面名称#锚点|显示内容}}

以下几点与原生链接略有不同，但通常正是你想要的效果：

显示内容必须写出来，不写不会和[[页面名称]]一样渲染为“页面名称”，而是会报错。如果链接不需要显示内容，也得写一个空参数：{{#link:页面名称|}}。可以承认这一点确实不符合预期，但这其实是为了和此扩展另外两个解析器函数以及{{#tag}}保持统一性，还使得#含等号的内容能够不用特殊处理。但其实影响不大，需要自定义链接的HTML属性的很多场景显示内容就是和页面名不一样。
{{#link:Category:示例|……}}等价于[[:Category:示例|……]]而不是[[Category:示例|……]]，因此它不会把当前页面加入该分类。
File:等命名空间、跨维基前缀、跨语言前缀同理。例如{{#link:File:示例.png|……}}渲染为链接，不会嵌入图片。
匿名参数两侧的空格不影响效果，{{#link: 页面名称 | …… }}与{{#link:页面名称|……}}等价。

抛开上面的这些，#link与[[ ]]几乎就完全等价了：支持跨维基链接、跨语言前缀、指向自身的链接（self-link），并且可以在Special:链入页面中查到。还兼容冒号技法——虽然你完全不需要这么做。

外部链接

{{#externallink}}等价于[ ]，并可以设定HTML属性。

{{#externallink:https://example.com|显示内容}}
{{#externallink:https://example.com|显示内容|class=my-link}}
{{#externallink:mailto:[email protected]|写信给我}}

与原生语法一致的几点：

URL必须带协议（https://、mailto:等）。
链接会被记录，可以在Special:链接搜索中查到。

不一致的：

显示内容必须写出来。如果链接不需要显示内容，也得写一个空参数：{{#externallink:https://example.com|}}。
由于解析器拿不到当前外链编号，所以不能像原生语法那样省略显示内容并显示成“[1]”“[2]”……
URL与显示内容之间用竖线|分隔，而不是空格。{{#externallink:https://example.com 显示内容}}会报错。

朴素链接

{{#plainlink}}不等价于外部链接：它不会在wiki中记录任何信息，也不会自动添加class、rel、target等属性。它只是生成一个带属性的<a>元素。

之所以需要它，是因为在wikitext里创建一个指向本站的有查询参数的链接（例如当前页面的编辑链接）以及其他wikitext内链表示不出来的链接相当麻烦：

<span class="plainlinks">[{{fullurl:Help:Links|action=edit}} 编辑本页]</span>

上面的写法还得靠CSS把外部链接伪装成内部链接。即便伪装了，它的target、rel也是错误的，这会导致体验割裂。有此扩展后改用{{#plainlink}}即可：

{{#plainlink:{{localurl:Help:Links|action=edit}}|编辑本页|class=my-link}}

用法：

{{#plainlink:URL|显示内容}}
{{#plainlink:URL|显示内容|class=my-link|style=color: red}}

出于安全考虑，URL必须是相对根的链接，以/开头。{{localurl:页面名称}}生成的URL就满足该规则。

HTML属性的写法

属性以命名参数的形式给出，可以写任意多个，不要给属性值加引号：

{{#link:页面名称|显示内容|class=my-link|id=link-1|title=提示|style=color: red}}

属性值里可以用<nowiki>。

布尔属性

布尔属性不需要专门的语法，写成|属性名=或|属性名=属性名即可：

{{#link:页面名称|显示内容|itemscope=}}
{{#link:页面名称|显示内容|itemscope=itemscope}}

MediaWiki已添加的属性

MediaWiki原生链接本身就会带上href以外的一些属性（例如class、title）。对于MediaWiki和编辑者都定义了的属性，处理方式如下：

属性	处理方式
`class`	附加，重复的类名会合并
`style`	附加（目前未见MediaWiki添加`style`，为增强稳健性而预留此特性）
其他属性，如`title`	覆盖MediaWiki的值

例如页面不存在时，{{#link:页面名称|显示内容|class=my-link}}的class为my-link new，其中的new来自MediaWiki。

允许的属性

出于安全考虑，解析器函数只允许MediaWiki的通用属性：

HTML
- id
- class
- style
- lang
- dir
- title
- tabindex
ARIA
- aria-describedby
- aria-flowto
- aria-hidden
- aria-label
- aria-labelledby
- aria-level
- aria-owns
- role
RDFa
- about
- property
- resource
- datatype
- typeof
Microdata
- itemid
- itemprop
- itemref
- itemscope
- itemtype

显示内容

能在链接外正常显示的内容，几乎都能在链接里正常显示，链接套链接除外：

'''粗体'''与''斜体''等wikitext；
图片，如[[File:图片.png|link=]]（请始终带上|link=）；
<nowiki>；
模板、解析器函数、解析器扩展标签；
MediaWiki允许的HTML标签。

{{#link:页面名称|'''粗体'''}}
{{#link:页面名称|<nowiki>'''不是粗体'''</nowiki>}}

含等号的内容

内容里的等号不会导致内容被识别为命名参数。

{{#link:页面名称|E=mc²}}

渲染为：E=mc²E=mc²。而

{{#link:页面名称|1=E=mc²}}

渲染为：1=E=mc²1=E=mc²。

参见