Manual:魔术字

魔術字是MediaWiki連結到特定功能或回傳值的文字串,例如目前日期和時間、頁面標題、網站資訊等等。 它們可以被視為是特殊的命令或變數,在頁面呈現的過程中可以動態內容生成以及與MediaWiki軟體互動。

從技術觀點來看,魔術字將一連串的wiki文字串映射成獨特的內部識別碼 (ID),然後將其與特定功能相關聯。 這個ID會指示MediaWiki執行相應的操作或返回特定的值。變數 (輸出動態的值)和解析器函數 (執行運算或條件式邏輯)都使用了這種映射技術。

映射到该ID的所有文本都将替换为函数的返回值。 文本字符串和ID之间的映射存储在某個文件裏內的变量$magicWords中,该文件可以使用$wgExtensionMessagesFiles 加载。

默认魔术字在CoreParserFunctions.php 裏实现的。

每当MediaWiki在一對雙花括号间寻找文本时({{XXX ...}}),它必须裁決XXX是变量?解释器功能?又或者是模板?因此,它会詢問一系列的问题:

1. 它是否有关联到某個魔术字ID?作为解决{{XXX...}}形式标记的第一步,MediaWiki尝试将XXX翻译成魔术字ID。這個翻译表由$magicWords定义。
   • 如果没有魔术单词ID与"XXX"相关联,则"XXX"會被假定为模板。

   
   

2. 它是变量吗?如果魔术字ID有被找到,MediaWiki接下来会检查它是否有任何参数。
   • 如果没有找到参数,MediaWiki会检查魔术单词ID是否已被声明为变量ID。‎ 为了检查这一点,它通过调用MagicWord::getVariableIDs()来检索魔术单词列表。 这个方法从一个硬编码的变量id列表(参见Help:Variables )和钩子MagicWordwgVariableIDs 所附带的所有函数所提供的自定义变量id列表中获取变量id列表。
     • 如果确认魔术字ID是变量,MediaWiki将调用ParserGetVariableValueSwitch 函数获取与变量名相关联的值。

   
   

3. 它是解析器函数吗?如果这个魔术字包含任意参数,或者变量魔术字ID列表中缺少对应的魔术字ID,则MediaWiki假定该魔术字是解析器函数或模板。 如果在声明的解析器函数列表中找到其魔术字ID,则将其视为解析器函数,并以名为$renderingFunctionName的函数來呈现。 否则,它将被假定为模板。

为了让魔术字起到它的作用,我们必须做到以下事情:

Wiki文本与魔术字ID互相映射 魔术字ID与相关的php设置映射

变量$magicWords用来将每个魔术词语ID与一个依赖语言的数组关联在一起,该数组描述了所有映射到魔术词语ID的所有文本字符串。 重要:这仅设置了后端i18n映射,你仍然需要继续编写其他代码来让MediaWiki在其他地方使用该魔术字。 此外,请确保在添加特定于语言的值之前将$magicWords初始化为空数组,否则在尝试加载魔术字时会遇到错误,并且需要重建本地化缓存才能正常工作。

此数组的第一个元素是一个整数标志,指示魔术字是否区分大小写。其余元素是应该与魔术字ID相关联的文本列表。如果区分大小写标志为0,则数组中名称的任何大小写变体都将匹配。如果区分大小写标志为1,则只有大小写完全匹配的项才会与魔术字ID相关联。 因此格式为$magicWords['en'] = [ 'InternalName' => [ 0, 'NameUserTypes', 'AdditionalAliasUserCanType' ] ];

此关联由$magicWords使用$wgExtensionMessagesFiles 注册的文件中创建。

在下面的示例中,安装西班牙语MediaWiki会将魔术字ID ‘MAG_CUSTOM’与"personalizado"、"custom"、"PERSONALIZADO"、"CUSTOM"和所有其他大小写变体相关联。 在英文MediaWiki中,只有各种大小写组合中的"custom"才会映射到"MAG_CUSTOM":

文件Example.i18n.magic.php:

<?php
$magicWords = [];
$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, 'custom' ],
];
$magicWords['es'] = [
	'MAG_CUSTOM' => [ 0, 'personalizado' ],
];

在extension.json 文件的一部分:

"ExtensionMessagesFiles":{
"ExampleMagic":"Example.i18n.magic.php"
}

请注意,"ExampleMagic"与用于普通国际化文件的键值不同(通常只是扩展名的标题,即"Example")。"Magic"是故意附加的,因此不会导致键值覆盖。

您可以在 PHP 中内置关联的魔术词,而不是通过 i18n 文件。 这在在LocalSettings.php 中定义钩子时很有用,但不应在扩展中完成。

$contentLanguage = MediaWiki\MediaWikiServices::getInstance()->getContentLanguage();
$contentLanguage->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];

将魔术字ID与呈现函数关联的机制取决于魔术字是用作解析器函数还是变量。有关更多信息,请参阅:

• Manual:解析器函数
• Manual:Variables

参见Help:魔术字#本地化来寻求帮助。

您可以在Manual:系统消息API 、手册:语言#命名空间、避免在消息中使用{{SITENAME}}中阅读有关用于本地化的魔术字的定义和用法的更多信息。

行为开关是一种特殊类型的魔术字。可以通过使用双下划线(而不是双花括号)来辨别它们。 例如: __NOTOC__

这些魔术字通常不输出任何内容,而是更改页面的行为和/或设置页面属性。 这些魔术字在MagicWordFactory::mDoubleUnderscoreIDs中列出,也列在帮助:魔术字#行为开关中。 大多数标准行为开关的效果都在Parser::handleDoubleUnderscore()中定义。 如果没有定义具体的效果,魔术字将简单地在 page_props 表中设置一个页面属性。 以后也可以通过测试$parser->getOutput()->getPageProperty( 'MAGIC_WORD' )是否为null或空字符串来检查这一点

下面是一个实现自定义__CUSTOM__行为开关的示例扩展

MyExt/extension.json - 这只是牛刀小試,真正的扩展會填写更多欄位。

{
"name":"MyExt",
"type":"parserhook",
"AutoloadNamespaces":{
"MediaWiki\\Extension\\MyExt\\":"includes/"
},
"Hooks":{
"GetDoubleUnderscoreIDs":"main",
"ParserAfterParse":"main"
},
"HookHandlers":{
"main":{
"class":"MediaWiki\\Extension\\MyExt\\Hooks"
}
},
"ExtensionMessagesFiles":{
"MyExtMagic":"MyExt.i18n.magic.php"
},
"manifest_version":2
}

MyExt/MyExt.i18n.magic.php

<?php
$magicWords = [];
$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, '__CUSTOM__' ],
];

MyExt/includes/Hooks.php

<?php
namespace MediaWiki\Extension\MyExt;
use MediaWiki\Hook\GetDoubleUnderscoreIDsHook;
use MediaWiki\Hook\ParserAfterParseHook;
use MediaWiki\Parser\Parser;
use MediaWiki\Parser\StripState;
class Hooks implements GetDoubleUnderscoreIDsHook, ParserAfterParseHook {
	/**
	 * @param string[] &$doubleUnderscoreIDs
	 * @return bool|void
	 */
	public function onGetDoubleUnderscoreIDs( &$ids ) {
		$ids[] = 'MAG_CUSTOM';
	}
	/**
	 * @param Parser $parser
	 * @param string &$text
	 * @param StripState $stripState
	 * @return bool|void
	 */
	public function onParserAfterParse( $parser, &$text, $stripState ) {
		if ( $parser->getOutput()->getPageProperty( 'MAG_CUSTOM' ) !== null ) {
			// 在这里实现行为开关......
			// e.g. If you wanted to add some JS, you would do $parser->getOutput()->addModules( [ 'moduleName' ] );
		}
	}
}

• Help:魔术字 - 类似{{PAGENAME}}以及{{SERVER}}的变量列表。
• Manual:MagicWord.php

• Pages using deprecated NoteTA template
• Customization techniques/zh
• Magic words/zh