WordPress插件开发：钩子（Hook）

钩子介绍

WordPress的钩子（Hook）系统是其插件架构和主题定制功能的基石，它允许开发者在特定的时间点“注入”自己的代码（动作钩子），或者“修改”即将被使用的数据（过滤器钩子），而无需修改WordPress核心文件。

钩子有两种类型：动作钩子和过滤器钩子。要使用任何一个，你需要编写一个称为回调函数（Callback）的自定义函数，然后用 WordPress 钩子注册，用于特定的动作或过滤器。

动作钩子允许你添加数据或更改WordPress的运行方式，比如将输出回传给用户或向数据库插入某些内容。
过滤器钩子让你能够在运行 WordPress Core 时更改数据，Filter的回调函数会接受变量，修改后返回。

WordPress提供了许多钩子供你使用，你也可以自己创建，这样其他开发者可以扩展和修改你的插件或主题。

动作与过滤器

这是一个清晰的对比表格，帮助你快速理解 WordPress 中动作钩子（Action Hook）和过滤器钩子（Filter Hook）的核心差异。

特性维度	动作钩子 (Action Hook)	过滤器钩子 (Filter Hook)
核心目的	执行代码。在特定的时间点或事件发生时，添加一段功能或逻辑。	修改数据。在数据被使用（输出、保存等）前，拦截并修改它。
回调函数要求	不需要返回值。其作用是执行一系列操作（如输出HTML、写入日志、发送邮件）。	必须返回一个值（通常是修改后的第一个参数 `$value`）。其作用是对输入值进行加工并返回。
执行流程	单向流程。`do_action` 触发后，按优先级依次调用所有挂载的函数。像一个事件发布/订阅系统。	链式流程。`apply_filters` 将初始值 `$value` 依次传递给所有挂载的函数，每个函数的返回值作为下一个函数的输入值。像一个数据处理管道。
典型应用场景	– `wp_head` / `wp_footer`：在页面头部/底部添加代码（如CSS、JS、元标签）。 – `init`： WordPress初始化时执行自定义代码。 – `save_post`：文章保存时执行额外操作。	– `the_title` / `the_content`：修改即将显示的文章标题或内容。 – `excerpt_length`：修改摘要长度。 – `body_class`：向body标签添加自定义CSS类。
简单比喻	“做事”：像是设置了一个闹钟（`do_action`），铃响时（钩子触发），你就去做一件事（回调函数）。	“加工”：像是有一条流水线（`apply_filters`），原材料（`$value`）经过每个工位（回调函数）都会被加工一次，最后得到成品。

核心区别总结

你可以将过滤器钩子视为一种特殊类型的动作钩子，它强制要求回调函数必须有一个返回值，并且这个值会在所有函数间传递。理解这个差异是掌握WordPress钩子系统的关键。

一句话概括：当你需要在某个时刻“做点什么”时，用动作钩子；当你需要“修改什么数据”时，用过滤器钩子。

语法

钩子系统相关的主要函数位于 wp-includes/plugin.php 文件中。其核心是四个函数：add_action()、do_action()、add_filter() 和 apply_filters()。

将一个函数挂载到指定的动作钩子上： add_action( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 ): true。

执行一个动作钩子，调用所有被挂载的函数： do_action( string $tag, mixed ...$arg ): void。；

将一个函数挂载到指定的过滤器钩子上：add_filter( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 ): true。

应用一个过滤器钩子，将所有挂载的函数应用于传入的值，并返回修改后的值：apply_filters( string $tag, mixed $value, mixed ...$args ): mixed。

参数说明

参数	类型	说明
`$tag`	字符串	钩子的名称。由WordPress核心、主题或插件定义。
`$function_to_add`	可调用类型	当钩子触发时执行的回调函数。
`$priority`	整数	执行的优先级。数字越小，越早执行（默认为10）。
`$accepted_args`	整数	回调函数接受的参数数量。必须与`do_action`或`apply_filters`传递的参数数量匹配。

返回值：add_action和add_filter始终返回true。apply_filters返回被所有过滤函数处理后的最终值。