手册:解析器函数

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Manual:Parser functions and the translation is 97% complete.

Outdated translations are marked like this.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Tiếng Việt • ‎dansk • ‎español • ‎français • ‎polski • ‎português do Brasil • ‎русский • ‎ไทย • ‎中文 • ‎日本語 • ‎한국어
OOjs UI icon puzzle-ltr.svg 扩展: 开发 标签扩展 手册:解析器函数 钩子 特殊页面 手册:皮肤 手册:魔術字 API Content models
MediaWiki extensions

在MediaWiki 1.7中添加的解析器函數是一種與解析器緊密集成的擴展。 短語“解析器函數”不應與扩展:解析器函数 混淆,後者是簡單解析器函數的集合。 (請參閱幫助:扩展:解析器函數 。)

描述

雖然標籤擴展需要獲取未處理的文本並將超文本標記語言返回給瀏覽器,但解析器函數可以與頁面中的其他wiki元素“交互”。例如,解析器函數的輸出可以用作模板參數或構造鏈接

解析器函數的典型語法是:

{{ #functionname: param1 | param2 | param3 }}

有關更多信息,請參閱the documentationParser::setFunctionHook ( $id, $callback, $flags = 0 )。 本文檔說明:

回調函數應具有以下形式:
function myParserFunction( &$parser, $arg1, $arg2, $arg3 ) { ... }
或者和或者 SFH_OBJECT_ARGS:
function myParserFunction( $parser, $frame, $args ) { ... }"

創建解析器函數比創建新標記稍微複雜一些,因為函數名稱必須是魔術字,這是一個支持別名和本地化的關鍵字。

简单例子

下面是一個創建解析器函數的擴展示例。

註冊進入extension.json,代碼進入ExampleExtension.class.php

{
	"name": "ExampleExtension",
	"author": "Me",
	"version": "1.0.0",
	"url": "https://www.mediawiki.org/wiki/Extension:ExampleExtension",
	"descriptionmsg": "exampleextension-desc",
	"license-name": "GPL-2.0-or-later",
	"type": "parserhook",
	"MessagesDirs": {
		"ExampleExtension": [
			"i18n"
		]
	},
	"AutoloadClasses": {
		"ExampleExtensionHooks": "src/ExampleExtensionHooks.php"
	},
	"ExtensionMessagesFiles": {
		"ExampleExtensionMagic": "ExampleExtension.i18n.php"
	},
	"Hooks": {
		"ParserFirstCallInit": "ExampleExtensionHooks::onParserFirstCallInit"
	},
	"manifest_version": 1
}
<?php
class ExampleExtensionHooks {
   // 使用解析器註冊任何渲染回調
   public static function onParserFirstCallInit( Parser $parser ) {

      // 創建一個函數鉤子,將“示例”魔術詞與renderExample()相關聯
      $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
   }

   // 渲染{{#example:}}的輸出。
   public static function renderExample( Parser $parser, $param1 = '', $param2 = '', $param3 = '' ) {

      // 輸入參數是擴展了模板的wikitext,。
      // 輸出也應該是wikitext。
      $output = "param1 is $param1 and param2 is $param2 and param3 is $param3";

      return $output;
   }
}

另一個文件ExampleExtension.i18n.php應該包含:

<?php
/**
 * @license GPL-2.0-or-later
 * @author Your Name (YourUserName)
 */

$magicWords = [];

/** English
 * @author Your Name (YourUserName)
 */
$magicWords['en'] = [
   'example' => [ 0, 'example' ],
];

啟用此擴展程序後,

  • {{#example: hello | hi | hey}}

生产:

  • param1 is hello and param2 is hi and param3 is hey
這個magicWords數組不是可選的。 如果省略,解析器函數將無法工作; {{#example: hello | hi}}將被渲染,就像沒有安裝擴展一樣。

较长的函数

對於更長的函數,您可能希望將鉤子函數拆分為_body.php或.hooks.php文件,並使它們成為類的靜態函數。 然後你可以用$wgAutoloadClasses 加載類並在鉤子中調用靜態函數; 例如。:

把它放在你的extension.json文件中:

"Hooks": {
	"ParserFirstCallInit": "ExampleExtensionHooks::onParserFirstCallInit"
},
"AutoloadClasses": {
	"ExampleExtensionHooks": "src/ExampleExtensionHooks.php"
}

然後把它放在你的src/ExampleExtensionHooks.php文件中:

class ExampleExtensionHooks {
      public static function onParserFirstCallInit( Parser $parser ) {
           $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
      }
}


缓存

與標記擴展名一樣,$parser->disableCache()可用於禁用動態擴展的緩存。

解析器接口

控制輸出的解析

要使解析器函數返回的wiki文本得到完全解析(包括擴展模板),請在返回時將noparse選項設置為false:

return [ $output, 'noparse' => false ];

至少在某些情況下,有時是1.12版本左右,似乎noparse的默認值從false變為true。

相反,要使您的解析器函數返回仍未解析的超文本標記語言,而不是返回wiki文本,請使用以下命令:

return [ $output, 'noparse' => true, 'isHTML' => true ];

然而,

例如This is {{#example:hello | hi | hey }} a test.

會產生這樣的東西:

This is

參數1是哈囉,參數2是嗨,參數3是測試。

這是由於解析器函數的超文本標記語言輸出之前的硬編碼“\n\n”而發生的。 為避免這種情況並確保超文本標記語言代碼內嵌到周圍文本,您可以使用:

return $parser->insertStripItem( $output, $parser->mStripState );

命名

默認情況下,MW會在每個解析器函數的名稱中添加一個哈希字符(數字符號,“#”)。 要禁止添加(並獲得沒有“#”前綴的解析器函數), 在setFunctionHook的可選flags參數中添上SFH_NO_HASH'常量,如下邊所述。

在選擇沒有哈希前綴的名稱時,請注意,不再可能刪除名稱以該函數名稱開頭後跟冒號的頁面。 特別是,避免使用等於命名空間名稱的函數名稱。 在啟用interwiki transclusion [1] 的情況下,還要避免使用等於interwiki前綴的函數名稱。

setFunctionHook掛鉤

有關解析器接口的更多詳細信息,請參閱includes/Parser.php.中setFunctionHook的文檔。 這是這些評論的副本(可能是註明日期):

function setFunctionHook( $id, $callback, $flags = 0 ) 参数:

  • string $id - 魔術字標識符
  • mixed $callback - 要使用的回調函數(和對象)
  • integer $flags - 可選,將其設置為SFH_NO_HASH常量,以調用不帶“#”的函數。

返回值:此名稱的舊回調函數(如果有)

創建一個函數,例如{{#sum:1|2|3}}。 回調函數應具有以下形式:

function myParserFunction( $parser, $arg1, $arg2, $arg3 ) { ... }

回調可以返回函數的文本結果,也可以返回帶有文本的數組 在元素0中,以及其他元素中的許多標誌。 標誌的名稱是 在鍵中指定。 有效標誌是:

found 
返回的文本有效,停止處理模板。 默認情況下啟用此選項。
nowiki 
應該轉義返回值中的Wiki標記
noparse 
不應剝離不安全的HTML標籤等。
noargs 
不要在返回值中替換三重括號參數
isHTML 
返回的文本是HTML,裝備它反對wikitext轉換

命名參數

解析器函數不像模板和標記擴展那樣支持命名參數,但偶爾會偽造它。 用戶通常習慣使用豎線(|)來分隔參數,因此能夠在解析器函數上下文中做到這一點也很好。 以下是如何完成此操作的簡單示例:

function ExampleExtensionRenderParserFunction( &$parser ) {
	//Suppose the user invoked the parser function like so:
	//{{#myparserfunction: foo=bar | apple=orange | banana }}

	$options = extractOptions( array_slice(func_get_args(), 1) );

	#Continue writing your code...
}

/**
 * Converts an array of values in form [0] => "name=value" into a real
 * associative array in form [name] => value. If no = is provided,
 * true is assumed like this: [name] => true
 *
 * @param array string $options
 * @return array $results
 */
function extractOptions( array $options ) {
	$results = array();

	foreach ( $options as $option ) {
		$pair = explode( '=', $option, 2 );
		if ( count( $pair ) === 2 ) {
			$name = trim( $pair[0] );
			$value = trim( $pair[1] );
			$results[$name] = $value;
		}

		if ( count( $pair ) === 1 ) {
			$name = trim( $pair[0] );
			$results[$name] = true;
		}
	}
	//Now you've got an array that looks like this:
	//  [foo] => "bar"
	//	[apple] => "orange"
	//	[banana] => true

	return $results;
}

参见