Manual:Tag extensions/zh



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

一個簡單的標籤-{zh-hans:扩展; zh-hant:擴充功能;}-是由一個与解析器挂钩的回呼函式所構成，这样，在解析器运行时，它會找到所有特定标签的实例然後將它替换掉，透過调用相应的回呼函式來呈現實際的HTML.

-{zh-hans:示例; zh-hant:範例;}-
在extension.json中,設置钩子:

然後，新增一些钩子到PHP檔案裏

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


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

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

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

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

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

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



發佈您的扩展

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

另請參見發佈你的-{zh-hans:扩展; zh-hant:擴充功能;}-.

常见问题


安全問題
您將注意到上面的示例中的輸入在返回之前使用 進行轉義. 在將所有用戶輸入回送給客戶端之前，以這種方式處理所有用戶輸入是至關重要的，以避免引入任意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:擴充功能;}-通常需要擔心的事情.
 * 会将*转换为无序列表，并将以空格符为起始的一行转换为. 在某些-{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文件中定義. 如果省略此字段，則將使用 字段.



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

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



工具栏按钮
提供了一个编辑工具栏，用户只需点击一个按钮，就能在编辑器中添加标签. 如果你想为你的新标签创建一个工具栏按钮，请在扩展名的  文件夹中创建一个名为   的文件. 文件应该是这样的：

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上使用的解析器標籤列表.