Manual:Hooks/zh



钩子可以让自定义的代码在某些特定事件发生时运行(例如保存页面或者用户登录). 例如，下列代码段将会在 钩子触发时调用函数，并将 特定的参数传入.

可以通过将钩子的名称映射到扩展的 文件中的回调函数来注册钩子：

MediaWiki 提供许多 钩子 来 扩展 MediaWiki 的功能. Assigning a function (known as an hook handler) to a hook will cause that function to be called at the appropriate point in the main MediaWiki code, to perform whatever additional task(s) the developer thinks would be useful at that point. 每个钩子可以有多个分配给它的处理程序，在这种情况下它将按照分配的顺序调用函数，并将先一个功能所做的修改传递给后面的功能.

Assign functions to hooks at the end of or in your own extension file at the file scope (not in a  function or the  hook). For extensions, if the hook function's behavior is conditioned on a setting in LocalSettings.php, the hook should be assigned and the function should terminate early if the condition was not met.

你也可以在你自己的扩展中创建新的钩子. It is registered in extension.json the same way as if you were registering a built-in MediaWiki hook to use in your extension. 然后你可以通过调用 在你的扩展中运行你的钩子. 最后，不要忘记把它们添加进.

背景
A hook is triggered by a call to HookContainer::run, usually via a method in HookRunner. HookContainer will find the hook handlers to run and call them with the parameters given to HookContainer::run. Hook handlers are registered via.

参见.

In this example from the  function in, doPurge calls HookRunner::onArticlePurge to run the  hook, passing   as argument:

The calls many hooks, but  can also call hooks.



撰寫钩子處理器
A hook handler is a function you register, which will be called whenever the hook in question is run.

For extensions, register your hook handlers in :

Hook handlers can also be registered via the global array. This is most commonly used for site-specific customizations in, or in legacy extensions that predate. All the following are valid ways to define a hook handler for the EventName hook, with two parameters passed:

Note that when an object is assigned, and you don't specify a method, the method called is "onEventName". For example "onArticleSave", "onUserLogin", etc.

The optional data is useful if you want to use the same function or object for different purposes. For example:

This code would result in  being run twice when a page is saved: once for 'TimStarling', and once for 'brion'.

Hook handler return values
Hook handlers can return one of three possible values:


 * (no return value, or null) - the hook handler has operated successfully. (Before MediaWiki 1.23, returning was required.)
 * "some string" - an error occurred; processing should stop and the error should be shown to the user
 * - the hook handler has done all the work necessary, or replaced normal handling. This will prevent further handlers from being run, and in some cases tells the calling function to skip normal processing.

Returning false makes less sense for hooks that run after an action is already completed. In those cases, the return value is often ignored.

Handling hooks in MediaWiki 1.35 and later
MediaWiki 1.35 introduces the HookHandlers system. This includes per-hook interfaces for improved static validation and discovery of parameter documentation. It also enables dependency injection by introducing an intermediary class instance that accepts a number of specified services (instead of static callbacks that explicitly access services from global state).

The approach from MediaWiki 1.34 and earlier, of registering hook handlers directly as static methods, remains supported and is not deprecated. Extension authors may opt-in to the new system are welcome to do so. To learn more, see the MediaWiki core: Hook specification and the announcement on wikitech-l.

Changes to hook names

Prior to MediaWiki 1.35, hooks sometimes included characters that could not be used in a class or method name, such as colons and dashes. With the introduction of per-hook interfaces, the canonical names of these hooks have been changed to use underscores instead. For example, the interface for ApiFeedContributions::feedItem is. Hook handers that are registered with the old names remain supported.

Registering hooks using HookHandlers

To adopt the new system, change your Hooks class to have regular methods instead of static methods and to be constructible. This class is then registered once, via the HookHandlers attribute in extension.json, using the  option as part of an ObjectFactory description where you can use the   option.

For example, to register the BeforePageDisplay hook:

Handling hooks using interfaces

To use hook interfaces, extensions should define a Hooks class in their namespace and implement one or more hook interfaces. Hook interfaces are named with the hook name followed by the word "Hook".

Convert an extension to the new hook system:

Follow these steps for each hook handling method:
 * identify the hook handler interface, and make the Hooks class implement this interface.
 * update the method name and signature to be exactly the same as in the interface.
 * change the "Hooks" section of extension.json to refer to the handler you specified in the "HookHandlers" section.

The process was demonstrated at the Wikimedia Hackathon 2021:
 * Example patch for an extension
 * Recording on YouTube

Hook behavior before MediaWiki 1.22 vs after
Extracted from: change 500542: for non-abortable hooks (most hooks) returning true has been redundant since MediaWiki 1.22 (in 2015). This was done to reduce chances of accidental failure because we had experienced several outages and broken features due to silent failures where e.g. one hook callback somewhere accidentally returned a non-bool or false instead of true/void and thus short-circuits the whole system.

(Returning non-true/non-void in a MediaWiki Hook is equivalent to  and   in JavaScript events, it kills other listeners for the same event).

For example, if  hook were to return false in MobileFrontend, it would mean Popups stops because its callback would no longer run. 假定钩子为 ，请参见下面的区别.

MediaWiki 1.22前：

或

MediaWiki 1.22+

文档
Currently, hooks in MediaWiki core have to be documented both in hook interface (in the source code repository) and here on MediaWiki.org. In some cases, one of these steps may not yet have been completed, so if a hook appears undocumented, check both.

Each hook provided by MediaWiki Core is defined in a hook interface. Typically, hook interfaces are located in a "Hook" sub-namespace inside the caller namespace. For example,. You can find a list of hook interfaces in the generated MediaWiki PHP documentation.

To document a hook on-wiki, use MediaWikiHook.

 Hook interface doc template 

In hook interfaces, doc comments specify the status, purpose, parameters, and behavior of the hook.



可用的钩子


以功能分类的钩子
Some of these hooks can be grouped into multiple functions.
 * Sections: Article Management  -  Edit Page  -  Page Rendering  -  User Interface  -  File Management  -  Special Pages  -  User Management  -  Logging  -  Skinning Templates  -  API  -  Import/Export  -  Diffs  -  Miscellaneous

Alphabetical list of hooks
For a complete list of hooks, use the, which should be kept more up to date.

參見

 * — specification of the hooks system
 * List of hook interfaces in MediaWiki Core
 * — contains examples of hooks
 * — the JavaScript/front-end system of hooks
 * — specification of the hooks system
 * List of hook interfaces in MediaWiki Core
 * — contains examples of hooks
 * — the JavaScript/front-end system of hooks