动作 Action

动作钩子的两种类型之一,它们提供了一种在执行WordPress核心、插件和主题的特定点上运行函数的方法。动作的回调函数不会将任何内容返回给调用动作的钩子。它们是过滤器的对应项。这里是对动作和过滤器之间差异的复习。

 

添加动作

添加动作的过程包括两个步骤:

 

创建回调函数

首先,创建一个回调函数。此函数将在其挂钩的动作运行时运行。

回调函数就像普通函数一样:它应该有前缀,并且应该在functions.php中或可调用的地方。它应该接受的参数将由您正在挂钩的动作定义,大多数钩子都定义得很好,因此请查看钩子文档,以查看您选择的动作将传递给函数的参数。

 

分配(挂钩)回调函数

其次,将回调函数添加到动作中,这称为挂钩,并告诉动作在运行时调用回调函数。

当回调函数准备好后,使用add_action()将其挂接到所选的动作钩子,add_action()至少需要两个参数:

  1. string $hook_name这是您要挂接的动作钩子的名称
  2. callable $callback回调函数的名称。

当执行init钩子时,下面的示例将运行wporg_callback()

function wporg_callback() {
    // do something
}
add_action( 'init', 'wporg_callback' );

您可以参考钩子一章以获取可用钩子的列表。

随着您获得更多经验,浏览WordPress核心源代码将让您找到最合适的钩子。

 

其他参数

add_action()可以接受两个额外的参数,int $priority表示赋予回调函数的优先级,以及int $accepted_args表示将传递给回调函数的参数数量。

 

优先级

许多回调函数可以连接到单个动作。例如,init钩子得到了大量的使用。在某些情况下,您可能需要确保回调函数在其他回调函数之前或之后运行,即使这些其他函数可能尚未挂接。

WordPress基于两件事确定回调函数的运行顺序:第一种方法是手动设置优先级。这是使用add_action()的第三个参数完成的。

以下是关于优先级的一些重要事项:

  • 优先级是正整数,通常在1到20之间
  • 默认优先级(即当没有手动提供priority值时分配的优先级)为10
  • 优先级值没有理论上限,但实际上限为100

优先级为11的函数将在优先级为10的函数之后运行,优先级为9的函数将在优先级为10的函数之前运行。

确定回调函数顺序的第二种方法是简单地根据它在相同优先级值内注册的顺序。因此,如果两个回调函数以相同的优先级为同一个钩子注册,它们将按照注册到钩子的顺序运行。

例如,以下回调函数都注册到
init挂钩,但优先级不同:

add_action('init', 'wporg_callback_run_me_late', 11);
add_action('init', 'wporg_callback_run_me_normal');
add_action('init', 'wporg_callback_run_me_early', 9);
add_action('init', 'wporg_callback_run_me_later', 11);

在上述示例中:

  • 第一个函数将运行wporg_call_backrun_me_early(),因为它的手动优先级为9
  • 其次,wporg_callback_run_me_normal(),,因为它没有手动优先级,所以它的优先级是10
  • 接下来,运行wporg_callback_run_me_late(),因为它的手动优先级为11
  • 最后,运行wporg_callback_run_me_later():它的优先级也为11,但它挂在wporg_callback_run_me_late()之后。

 

参数数量

有时,回调函数需要接收一些与所挂接的动作相关的额外数据。

例如,当WordPress保存文章并运行save_post钩子时,它将两个参数传递给回调函数:保存的文章的ID和文章对象本身:

do_action( 'save_post', $post->ID, $post );

当为save_post钩子注册回调函数时,它可以指定希望接收这两个参数。它通过(在本例中)将2作为第四个参数来告诉add_action期望它们:

add_action('save_post', 'wporg_custom', 10, 2);

为了在回调函数中实际接收这些参数,请修改回调函数将接受的参数,如下所示:

function wporg_custom( $post_id, $post ) {
    // do something
}
Tip:最好将回调函数参数的名称与传递的参数相同,或者尽可能接近。