Manual:Tag extensions/zh



个别项目经常会发现，用额外的功能來延伸擴大内嵌的wiki标签是很有用的，无论是简单的字符串处理、还是已發展完備的信息检索. 标签的扩展允许用户创建新的自定义标签，它做到这一点. 举例来说，人们可以使用一个标签-{zh-hans:扩展; zh-hant:擴充功能;}-来引入一个简单的标签，将一个捐赠表格插入到页面中. 這個-{zh-hans:扩展; zh-hant:擴充功能;}-，包括有解析器函数和钩子，是改变或增强MediaWiki功能的最有效方式. 你在开发-{zh-hans:扩展; zh-hant:擴充功能;}-之前，总是應該檢查一下，避免重做别人已做过的东西.

一個簡單的標籤-{zh-hans:扩展; zh-hant:擴充功能;}-包含一個与解析器挂钩的回呼函式，这样，当解析器运行时，它将找到并替换所有特定标签的实例，调用相应的回呼函式來呈現實際的HTML.

例子
In extension.json, set up the hooks:

And add the hook into a PHP file

此示例為標籤註冊回呼函式. 當用戶將標籤： 添加到頁面時，解析器將調用 函式，傳入四個參數：


 * $input : 和標籤之間輸入，如果標籤是“關閉”則輸入'null，即
 * $args : 標籤參數，像HTML標籤的屬性一樣輸入; 這是一個以屬性名稱作键的關聯數組（键-值对）.
 * $parser : 父解析器（一個解析器物件）; 更高級的-{zh-hans:扩展; zh-hant:擴充功能;}-使用它來獲取上下文標題、解析維基文本、展開大括號、註冊鏈接關係和依賴關係等.
 * $frame : 父框架（PPFrame物件）.  它與$parser一起使用，為解析器提供有關調用-{zh-hans:扩展; zh-hant:擴充功能;}-的上下文的更完整信息.

有關更詳細的示例，請參閱Tag扩展示例

属性
讓我們看另一個例子：

此示例轉儲傳遞給標籤的屬性及其值. 很明顯，這允許靈活地指定新的自定義標籤. 例如，您可以定義一個標籤扩展，允許用戶在其用戶頁面上註入聯繫表單，使用類似.

MediaWiki有一個名副其實的標籤扩展名，其中一些在本網站列出; 其他人可以通過快速網絡搜索找到. 雖然其中一些對於它們的使用案例非常專業，但是有許多廣受歡迎且使用良好的扩展提供不同程度的功能.

慣例
有關扩展的一般佈局和設置，請參閱.



發佈您的扩展

 * 1) 在此Wiki上創建一個名為Extension:&lt;extension_name>的新頁面，其中包含有關您的-{zh-hans:扩展; zh-hant:擴充功能;}-的信息，如何安裝它以及正在使用的屏幕截圖. 已創建一個方便的模板來保存名為的信息.  请参阅Help:指南了解更多信息.  您還應該盡可能多地向頁面正文添加詳細信息，並且明智地定期檢查以回復相關聯談話頁面上的用戶問題.  另外，請確保該頁面屬於.
 * 2) 在-{zh-hans:扩展; zh-hant:擴充功能;}-的代碼中創建新钩子的-{zh-hans:扩展; zh-hant:擴充功能;}-應該在extension hook registry上註冊它們.
 * 3) Notify mediawiki-l郵件列表.

另請參見發佈扩展.

常见问题


报告关注
您將注意到上面的示例中的輸入在返回之前使用 進行轉義. 在將所有用戶輸入回送給客戶端之前，以這種方式處理所有用戶輸入是至關重要的，以避免引入任意HTML插入的向量，這可能導致跨網站指令碼漏洞.



加載模塊
為扩展添加模塊的正確方法是將它們附加到ParserOutput而不是$wgOut. 然後，模塊列表將自動從ParserOutput對像中獲取，並且即使在預先緩存頁面呈現時也會添加到$wgOut. 如果您直接將模塊添加到$wgOut，它們可能不會緩存在解析器輸出中.



附带扩展
如果您更改扩展的代碼，理論上，使用該扩展的所有頁面都會立即反映新代碼的結果. 從技術上講，這意味著每次呈現包含扩展的頁面時都會執行代碼.

實際上，由於頁面緩存（通過MediaWiki軟件，瀏覽器或中間代理或防火牆）通常不是這種情況.

要繞過MediaWiki的解析器緩存並確保生成新版本的頁面，請單擊編輯，將“action=purge”替換為瀏覽器地址欄中顯示的網址中的“action=edit”並提交新網址. 將重新生成頁面及其引用的所有模板，忽略所有緩存的數據. 如果主頁面本身未被修改，則需要清除操作，但必須更改它的方式（扩展已被修改，或僅修改了引用的模板）.

如果這不足以為您提供頁面的新副本，則通常可以通過在上述URL的末尾添加“&rand=somerandomtext”來繞過中間緩存. 確保'somerandomtext'每次都不同.



如何使用我的扩展禁用頁面緩存？
從MediaWiki 1.5版開始，解析器作為第三個參數傳遞給扩展. 此解析器可用於使緩存無效，如下所示：



在編輯其他頁面時重新生成頁面
也許您不想完全禁用緩存，只需要在編輯其他頁面時重新生成頁面，類似於處理模板轉換的方式. 這可以使用傳遞給鉤子函數的解析器物件來完成. 以下方法取自並且似乎可以用於此目的.



緩存行為的細粒度調整
您可以使用緩存鍵來區分不同版本的扩展輸出，從而為扩展使用微量緩存. 渲染時，您可以通過向鉤子函數添加addExtraKey方法為每個特徵添加緩存鍵，例如：

然而，在解析期間修改意味著在嘗試獲取緩存頁面時不包括額外的選項鍵，只有在渲染頁面進入緩存時，才能使用钩子來設置額外的選項. PageRenderingHash在將頁面放入緩存並將其取出時都會運行，因此如果它們尚未存在，則僅向哈希添加新密鑰非常重要. 例如:

關於此的一些重要說明：


 * 在confstr中使用“!setting1=$value”而不僅僅是“!$value”可確保如果安裝了不同的扩展或其加載順序更改，則解析器緩存不會變得混亂. !用作不同渲染選項的分隔符
 * 有些人使用 而不是 . 請注意，addExtraKey不會告訴解析器緩存額外的密鑰正在使用中，因此如果您不小心，很容易導致破壞緩存.



如何在我的扩展中渲染wikitext？


自版本1.16起
解析器鉤子函數傳遞對解析器物件和幀物件的引用; 這些應該用於解析wiki文本.

自1.8版本開始出現. 它的優點包括簡單（它只需要一個參數並返回一個字符串）以及它解析 中的扩展標籤這一事實，因此您可以嵌套扩展標籤.

recursiveTagParse的第二個參數， 是MW 1.16 alpha (r55682)中引入的可選參數.


 * 如果提供 （使用傳遞給您的扩展的 的值），那麼 中的任何模板參數都將被展開. 換句話說，有如 的內容將被識別並轉換為適當的值.
 * 如果未提供 （例如，，或者 設置為false ，然後模板參數不會被展開; 不會被更動.  雖然這不太可能是理想的行為，但這是MW 1.16之前唯一可用的選擇.

然而，即使是使用recursiveTagParse，仍然會跳過標籤的一步解析，還是. preSaveTransform是解析的第一步，負責對即將保存的wiki文本進行永久性更改，例如：


 * 您现有的签名 (, ~ ,  )
 * 展開鏈接標籤，也稱為“管道技巧”（例如，將 Help:Contents 更改為 Contents ）.  如果沒有此步驟， Help:Contents 之類的速記鏈接將被視為無效，並在解析時保留為wiki文本格式.
 * 展開 模板.

對preSaveTransform的原始調用故意在所有扩展標籤內跳過此類轉換. 如果您需要執行預保存轉換，則應考慮使用解析器函式. 所有標籤的-{zh-hans:扩展; zh-hant:擴充功能;}-也可以使用 作為解析器函數調用，它將應用預保存轉換.



如何在扩展標籤中傳遞XML樣式參數？


自版本1.5起
從MediaWiki 1.5開始，支持XML樣式參數（標籤屬性）. 參數作為第二個參數傳遞給鉤子函數，作為關聯數組. 值字符串已經為您解碼了HTML字符實體，因此如果將它們發送回HTML，請不要忘記使用 ，以避免HTML注入的風險.



如何避免我的扩展的HTML輸出的修改？
標籤的-{zh-hans:扩展; zh-hant:擴充功能;}-的返回值被認為“幾乎是”解析的文本，這意味著它不被視為純HTML，但仍然略有修改. 對標籤的-{zh-hans:扩展; zh-hant:擴充功能;}-的輸出做了兩件主要的事情（以及其他一些小事）：


 * 替換strip marker. 條帶標記是在處理wikitext的各個階段插入的某些項目，以作為標記在以後重新插入刪除的內容.  這不是-{zh-hans:扩展; zh-hant:擴充功能;}-通常需要擔心的事情.
 * 会将*转换为无序列表，并将以空格符为开始的一行转换为&lt;pre&gt;. 在某些-{zh-hans:扩展; zh-hant:擴充功能;}-中，這有時可能是一個問題.

標籤的-{zh-hans:扩展; zh-hant:擴充功能;}-還支持返回數組而不僅僅是字符串（很像解析器函數），以便更改返回值的解釋方式. 陣列的第0個值必須是html. “markerType”鍵可以設置為 ，以便停止進一步解析. 執行類似 將確保$html值不會被進一步修改並視為純HTML.



如何讓我的扩展出現在Special:Version？
要使您的扩展顯示在MediaWikiSpecial:Version頁面上，您必須在PHP代碼中指定扩展credit.

為此，請在钩子行或函數定義之前添加 變量作為第一個可執行代碼行.

一個示例钩子credit是：

將 替換為以下之一（除非您的扩展屬於多個類&mdash;然後為「每一個」類創建一個credit）：


 * 'specialpage'&mdash;保留用於添加MediaWiki特殊頁面;
 * 'parserhook'&mdash;如果你的扩展修改、補充、或替換MediaWiki中的解析器函數，則使用它;
 * 'variable'&mdash;為MediaWiki添加多項功能的扩展;
 * 'media'&mdash;如果您的扩展是某種媒體handler，則使用它
 * '其他'&mdash;所有其他扩展.

是接口/i18n消息的名稱，它描述了您的扩展，需要在扩展的i18n.php文件中定義. 如果省略此字段，則將使用 字段.



在回呼函式中檢索標籤名稱
假設你有幾個共享相同回呼的標籤和，並且在回呼函數中，你想獲得調用回呼的「標籤名」.

簡短的回答是：標籤名稱（ 或 ）不存在於任何回呼的參數中. 但您可以通過為每個標籤動態構建單獨的回呼函式來解決此問題：

Toolbar buttons
provides an editing toolbar, allowing users to add tags into their editor by simply clicking a button. If you want a toolbar button for your new tag, create a file named something like  in your extension's   folder. The file should look like this:

Further details about customizing this file can be found here. Once you've created the file, you need to register it with so it will be delivered to visitors; this is done by editing your  :

Then, in your PHP file:



參見

 * – 特殊標籤/變量列表，如 ，  ，……
 * – 維基媒體wiki上使用的解析器標籤列表.