MediaWiki中的Magic Words（魔术字）技术解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00635/article/details/148524057

MediaWiki中的Magic Words（魔术字）技术解析

mediawiki 🌻 The collaborative editing software that runs Wikipedia. Mirror from https://gerrit.wikimedia.org/g/mediawiki/core. See https://mediawiki.org/wiki/Developer_access for contributing. 项目地址: https://gitcode.com/gh_mirrors/me/mediawiki

什么是Magic Words

Magic Words（魔术字）是MediaWiki系统中一种特殊的本地化关键词，用于在维基文本（wikitext）中执行特定功能或获取特定值。它们可以被看作是MediaWiki内置的一套特殊指令系统，通过简单的语法就能实现复杂的功能。

Magic Words主要应用于以下场景：

解析器函数名称（如{{urlencode:...}}）
系统变量名称（如{{CURRENTDAY}}）
双下划线行为开关（如__NOTOC__）
图片链接参数名称

Magic Words的核心特性

每个Magic Word都具备以下关键属性：

同义词列表：包含一个规范英文单词（必须存在）和其他语言或形式的同义词
大小写敏感标志：决定匹配时是否区分大小写
唯一ID：通常使用小写的规范英文同义词作为ID

MagicWord类提供了将这些魔术字转换为正则表达式进行匹配的功能，这是其实现的核心机制。

如何添加自定义Magic Words

在扩展中添加Magic Words

要为你的MediaWiki扩展添加新的Magic Words，需要遵循以下步骤：

创建一个i18n魔法文件（通常命名为ExtensionName.i18n.magic.php）
在扩展的extension.json中注册这个文件
实现对应的处理逻辑

示例实现

首先创建魔法文件ExtensionName.i18n.magic.php：

<?php
$magicWords = [];

// 英文版本定义
$magicWords['en'] = [
    // 0表示不区分大小写，1表示区分大小写
    'mag_custom' => [ 0, 'custom' ],
];

// 西班牙语版本定义
$magicWords['es'] = [
    'mag_custom' => [ 0, 'aduanero' ],
];

在extension.json中注册：

{
    "ExtensionMessagesFiles": {
        "ExtensionNameMagic": "ExtensionName.i18n.magic.php"
    },
    "Hooks": {
        "ParserFirstCallInit": "MyExtensionHooks::onParserFirstCallInit"
    }
}

注意：ExtensionNameMagic这个键必须是唯一的，不能与其他扩展冲突。

实现处理类：

<?php
class MyExtensionHooks {
    public static function onParserFirstCallInit( $parser ) {
        $parser->setFunctionHook( 'mag_custom', [ self::class, 'expandCustom' ] );
        return true;
    }

    public static function expandCustom( $parser, $var1, $var2 ) {
        return "custom: var1 is $var1, var2 is $var2";
    }
}

在核心中添加Magic Words

如果需要在MediaWiki核心中添加Magic Words，应该编辑MessagesEn.php文件中的$magicWords数组，并按照文件中的注释说明进行操作。

Magic Words的类型详解

MediaWiki中的Magic Words主要分为三大类：

解析器函数：以{{函数名:参数}}形式调用，执行特定功能
变量：以{{变量名}}形式调用，返回特定值
行为开关：以__开关名__形式使用，影响页面渲染行为

解析器函数示例

{{#urlencode:Hello World}} → Hello+World
{{#formatnum:1234567}} → 1,234,567

变量示例

{{CURRENTYEAR}} → 2023
{{PAGENAME}} → 当前页面名称

行为开关示例

__NOTOC__ → 禁用目录自动生成
__NOEDITSECTION__ → 禁用章节编辑链接

最佳实践

命名规范：Magic Words的ID应使用小写字母和下划线组合
国际化：为所有支持的语言提供翻译
性能考虑：频繁使用的Magic Words应考虑缓存结果
安全性：处理用户输入时要进行适当的过滤和转义

常见问题解决

Magic Word不生效：
- 检查是否正确定义了大小写敏感标志
- 确认扩展已正确加载
- 检查是否有命名冲突
国际化问题：
- 确保所有支持的语言都有对应的翻译
- 检查语言文件是否被正确加载
性能问题：
- 复杂的Magic Words实现应考虑使用缓存
- 避免在Magic Words中进行耗时的数据库查询

通过深入理解MediaWiki的Magic Words机制，开发者可以创建更加强大和灵活的扩展功能，同时为用户提供更好的编辑体验。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考