Manual:Parser functions/zh

解析器函数（Parser function），加入于MediaWiki 1.7，是一种与解析器紧密集成的扩展. 短语“解析器函数”不应与混淆，后者是简单解析器函数的集合. （请参阅. ）

描述
虽然标签扩展需要获取未处理的文本并将超文本标记语言返回给浏览器，但解析器函数可以与页面中的其他wiki元素“交互”. 例如，解析器函数的输出可以用作模板参数或构造链接.

解析器函数的典型语法是：

有关更多信息，请参阅的. 本文档说明：


 * 回調函數應具有以下形式：
 * 或者 :
 * 或者 :

The first variant of the call passes all arguments as plain text. The second passes all arguments as an array of s, except for the first, which is currently text, though this may change in the future. These represent the unexpanded wikitext. The  parameter can be used to expand these arguments as needed. This is commonly used for conditional processing so that only the "true" case is evaluated with an if- or switch-like parser function. The frame object can also climb up the document tree to get information about the caller and has functions to determine and manage call depth, time-to-live, and whether the result of the parser function is volatile.

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



简单例子
下面是一個創建解析器函數的擴展示例.

註冊分別進入extension.json和src/ExampleExtensionHooks.php：

擴展目錄（不在src/子目錄中）的另一個文件ExampleExtension.i18n.php應該包含：

啟用此擴展程序後，



生产：


 * param1 is hello and param2 is hi and param3 is hey

Within LocalSettings.php
Magic words and their handling parser functions can be defined entirely in.



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

把它放在你的 文件中：
 * 請參閱：編寫事件處理程序以獲取其他樣式.

然後把它放在你的 文件中：

缓存
與標記擴展名一樣，$parser->disableCache可用於禁用動態擴展的緩存.

这对性能有显着的负面影响，因此仅在必要时使用.



解析器接口


控制輸出的解析
要使解析器函數返回的wiki文本得到完全解析（包括擴展模板），請在返回時將 選項設置為false：

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

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

命名
默认情况下，MW 会在每个解析器函数的名称中添加一个哈希字符（数字符号，“#”）. 要抑制该添加（并获得没有“#”前缀的解析器函数），请在 setFunctionHook 的可选标志参数中包含 SFH_NO_HASH 常量，如 below 所述.

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



setFunctionHook掛鉤
有關解析器接口的更多詳細信息，請參閱includes/Parser.php.中setFunctionHook的文檔. 這是這些評論的副本（可能是註明日期）：

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


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

返回值：此名稱的舊回調函數（如果有）

創建一個函數，例如. 回調函數應具有以下形式：

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


 * forceRawInterwiki
 * Force interwiki transclusion to be done in raw mode, not rendered.


 * found
 * 返回的文本有效，停止處理模板. 默認情況下啟用此選項.


 * isChildObj
 * The text is a DOM node needing expansion in a child frame.


 * isHTML
 * 返回的文本是HTML，裝備它反對wikitext轉換 But see discussion


 * isLocalObj
 * The text is a DOM node needing expansion in the current frame.


 * noparse
 * 不應剝離不安全的HTML標籤等.


 * nowiki
 * 應該轉義返回值中的Wiki標記


 * preprocessFlags
 * Use these flags when parsing the returned text. This only applies when noparse is.


 * text
 * The text returned from the function. If isChildObj or isLocalObj are specified, this should be a DOM node instead.


 * title
 * The Title object where the text came from.

Expensive parser functions
Some parser functions represent a significant use of a wiki's resources and should be marked as "expensive". The number of expensive parser functions on any given page is limited by the setting. What counts as expensive is left up to the function itself, but typically, anything that is likely to cause a delay that extends beyond simple processing of data should be considered. This includes things like database reads and writes, launching a shell script synchronously, or file manipulation. On the other hand, not all such functions should necessarily be tagged. Semantic MediaWiki, for example, only marks a percentage of its database reads as expensive. This is due to the fact that on certain data-intensive pages, it could easily overflow the normal expensive parser function limits. In cases like this, the potential for noticeably slower performance that doesn't get flagged as expensive is a trade-off to having the functionality that SMW offers.

To mark your parser function as expensive, from within the body of your parser function code, use. The return value will be  if the expensive function limit has been reached or exceeded.



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



参见

 * ParserFunctions擴展是一個眾所周知的解析器函數集合.
 * - an (incomplete) list of parser functions provided by core and extensions
 * Parser Hooks PHP 库，为声明性解析器钩子提供面向对象的接口
 * ParserFunctions擴展是一個眾所周知的解析器函數集合.
 * - an (incomplete) list of parser functions provided by core and extensions
 * Parser Hooks PHP 库，为声明性解析器钩子提供面向对象的接口
 * ParserFunctions擴展是一個眾所周知的解析器函數集合.
 * - an (incomplete) list of parser functions provided by core and extensions
 * Parser Hooks PHP 库，为声明性解析器钩子提供面向对象的接口
 * Parser Hooks PHP 库，为声明性解析器钩子提供面向对象的接口