分类： WordPress 钩子

除了知道如何向钩子注册回调函数外，在使用 WordPress 钩子时，你还需要了解一些其他事项。

在本课中，你将学习钩子优先级、钩子参数和钩子顺序。

钩子优先级

我们先从钩子优先级开始。

如果你查看 add_action 的文档，你会看到在钩子名称和回调函数之后，还有两个额外的函数参数。

第三个参数是钩子优先级，它是一个整数，默认值为 10。这意味着如果你在代码中注册一个动作时没有指定优先级，它将以优先级 10 被注册。

add_filter 函数也有一个优先级参数，其工作方式相同。

钩子优先级允许你确定你的钩子回调相对于可能注册在给定钩子上的其他钩子回调（无论是 WordPress 核心、其他主题还是插件）的执行顺序。

钩子按优先级数字顺序执行，从 1 开始。通常将优先级保留为默认值 10 是安全的，除非你特别想改变回调函数的执行顺序。

例如，在动作课程中的 after_setup_theme 示例中，你可能希望确保注册的回调函数仅在 WordPress 核心注册的任何回调之后运行。

因为 WordPress 核心以默认优先级 10 注册所有钩子回调，如果你指定优先级为 11，就可以确保你的回调函数在所有核心回调完成后运行。

add_action( 'after_setup_theme', 'wp_learn_setup_theme', 11 );

或者，如果你想确保回调在 WordPress 核心之前运行，你可以设置一个较低的优先级，比如 9。

add_action( 'after_setup_theme', 'wp_learn_setup_theme', 9 );

你经常会看到回调以高优先级注册，比如 99 或 9999。

add_action( 'after_setup_theme', 'wp_learn_setup_theme', 9999 );

这是因为插件或主题开发者希望确保这个回调在所有其他回调函数之后运行。然而，你永远无法知道其他第三方插件或主题可能以什么优先级注册它们的回调。

钩子参数

现在让我们看看钩子参数。

add_action 和 add_filter 函数中的第四个参数是回调函数可以接受的参数数量。

为了更好地理解这是如何工作的，让我们看看一个与内容相关的过滤器钩子 get_the_excerpt。

该过滤器定义在 wp-includes/post-template.php 文件的第 436 行。

return apply_filters( 'get_the_excerpt', $post->post_excerpt, $post );

这个过滤器定义在 get_the_excerpt 函数中，而该函数又从 the_excerpt 函数中调用。

这个函数通常用于显示搜索结果时，此时显示文章摘要而不是文章内容很有用。

apply_filters 函数注册了一个过滤器钩子，并带有两个与该过滤器相关的变量：$post_excerpt 字符串变量和 $post 对象。

在定义动作或过滤器钩子时，可以添加任意数量的可能参数。然而，传递给接受参数参数的数字决定了其中有多少个被传递给钩子回调函数。

如果你查看 add_filter 的文档，你会看到接受参数数量的默认值是 1，这意味着如果你不为此参数指定值，第一个参数将可用于传递给回调函数。

在 get_the_excerpt 过滤器中，有两个可能的变量可以被接受。

如果你在不设置参数数量的情况下注册回调，那么只有第一个参数（在本例中是 post_excerpt）会在回调函数中可用。

add_filter( 'get_the_excerpt', 'wp_learn_amend_the_excerpt', 10 );
function wp_learn_amend_the_excerpt( $post_excerpt ) {
    // 对 $post_excerpt 进行处理
}

为了接受更多可用的参数，你需要指定要接受的参数数量。

add_filter( 'get_the_excerpt', 'wp_learn_amend_the_excerpt', 10, 2 );

然后你可以在回调函数中使用这些参数。

function wp_learn_amend_the_excerpt( $post_excerpt, $post ) {

}

能够确定回调函数需要哪些参数，并在注册钩子时正确设置参数数量，是一项非常有价值的技能。

例如，假设你只想在摘要后面添加一段简单的文字。在这种情况下，你只需要 $post_excerpt 参数，因此可以省略接受参数的设置。

add_filter( 'get_the_excerpt', 'wp_learn_amend_the_excerpt', 11 );
function wp_learn_amend_the_excerpt( $post_excerpt ) {
    $additional_content = '<p>由搜索引擎验证</p>';
    $post_excerpt       = $post_excerpt . $additional_content;

    return $post_excerpt;
}

注意，优先级也做了调整。这样做是为了确保这段文字在核心过滤器回调函数（已分配给该过滤器）执行完毕后再被添加。

让我们在搜索结果中看看效果。

但是，如果你想包含文章中的某些内容，比如文章标题，该怎么办呢？

在这种情况下，你需要更新回调函数，使其接受钩子中的两个参数，以便从 $post 对象中获取文章标题。

add_filter( 'get_the_excerpt', 'wp_learn_amend_the_excerpt', 11, 2 );
function wp_learn_amend_the_excerpt( $post_excerpt, $post ) {
    $additional_content = '<p>'. $post->post_title . ' 由搜索引擎验证</p>';
    $post_excerpt       = $post_excerpt . $additional_content;

    return $post_excerpt;
}

让我们看看更新后的搜索结果是什么样子。

你会注意到，这段代码对传递给回调函数的参数使用了相同的变量名，即 $post_excerpt 和 $post。

这并不是强制要求，在注册回调函数时，你可以为它们任意命名。但使用相同的名称有助于记住每个变量的用途。

钩子顺序

根据你的具体需求，你可能首先需要确定使用哪个操作或过滤器是正确的。

幸运的是，WordPress 开发者文档中有一个“常见 API”部分的钩子页面，其中列出了所有操作和过滤器钩子，并按照它们在 WordPress 站点不同请求中的执行顺序排列。

你可以使用这个列表来检查你想使用的钩子何时执行，然后根据这些信息判断它是否满足你的需求。

WordPress 钩子有两种类型：动作钩子和过滤器钩子。

在本课中，我们将重点介绍过滤器，但关于动作钩子的更多信息，请查看动作钩子课程。

什么是过滤器钩子？

过滤器允许你在特定时间点修改或过滤某些数据，这些数据将在后续被使用。

要使用过滤器，你需要在代码中将一个函数注册到已有的过滤器钩子上，这个函数被称为回调函数。

为了更好地解释这一点，我们来看一个名为 the_content 的过滤器。

这个过滤器定义在 wp-includes/post-template.php 文件中，位于一个函数内部。当主题模板需要渲染任何文章或页面内容时，就会调用这个函数。

在该函数内部，我们可以看到以下代码：

$content = apply_filters( 'the_content', $content );

这里，apply_filters 函数定义了一个过滤器钩子，钩子名称为 the_content。

你会注意到，一个 $content 变量作为 apply_filters 的参数传递，并且 apply_filters 的返回值被重新赋值给一个变量，在这里仍然是 $content 变量。

如果我们在这个函数中向上看一点，会发现 $content 变量被赋值为 get_the_content 函数的返回值。这是一个 WordPress 核心函数，用于从文章表中检索当前文章或页面的 post_content 字段值。

因此，apply_filters 函数注册了过滤器钩子，将代码执行到此时 $content 的值传递给注册在该钩子上的所有回调函数，并要求返回更新后的值。

使用过滤器钩子

要将回调函数注册到过滤器上，你需要使用 WordPress 的 add_filter 函数。

你需要将钩子名称和回调函数的名称作为参数传递给 add_filter 函数。

让我们看看在主题的 functions.php 文件中如何实现。

在代码编辑器中，导航到当前激活主题的 functions.php 文件，并打开它。

如果你的主题没有 functions.php 文件，你可以在主题目录的根目录下创建一个。确保它命名为 functions.php，并且在文件顶部包含 PHP 开始标签。

然后，将以下代码添加到你的 functions.php 文件中，以便将一个回调函数挂载到 the_content 过滤器钩子上。

add_filter( 'the_content', 'wp_learn_amend_content' );

然后，使用 PHP 函数语法创建回调函数，该函数接受来自过滤器的相关参数。

function wp_learn_amend_content( $content ) {
    // 执行一些更新 $content 的操作
    return $content;
}

你不必让参数名称与过滤器传递的变量名称相同，但这样做会让代码更易读。

注意，你必须返回更新后的数据。这样，从 apply_filters 调用中更新的原始变量才能获取到更新后的数据。

例如，假设你想在每篇文章内容的末尾添加一些内容，你可以像这样将其追加到 $content 变量中。

add_filter( 'the_content', 'wp_learn_amend_content' );
function wp_learn_amend_content( $content ) {
    $additional_content = '<!-- wp:paragraph --><p>通过 <i>the_content</i> 过滤</p><!-- /wp:paragraph -->';
    $content            = $content . $additional_content;

    return $content;
}

在这个例子中，你添加了一些文本到一个段落块中，这些文本会在前端每篇文章的底部显示。

始终从过滤器回调中返回某些内容非常重要，理想情况下是返回传递给过滤器的变量修改后的内容。如果不返回任何内容，会导致你的 WordPress 网站出现致命错误。

让我们看看这在我们的 WordPress 网站中是什么效果。

如果你在前端查看任何文章或页面，你会看到内容底部显示“通过 the_content 过滤”的文本。

所以，从这个例子可以看出，过滤器钩子允许你在代码执行的特定节点修改特定的数据片段。

WordPress 钩子有两种类型：动作钩子和过滤器钩子。通常简称为动作和过滤器。

本视频将重点讲解动作，但关于过滤器钩子的更多信息，请查看过滤器课程。

什么是动作钩子

顾名思义，动作允许你在 WordPress 请求执行过程中的特定时刻执行某些操作。

为了更好地解释这一点，我们来看一个例子。

在开发 WordPress 主题时，可以启用对不同文章格式的支持。

你可以在 WordPress 开发者文档的高级管理部分阅读更多关于文章格式的内容。

文章格式是一种方式，允许有权在 WordPress 网站上创建文章的用户从预定义的格式列表中选择。根据所选的文章格式，可以渲染不同的模板布局，以不同的格式显示文章。

要启用文章格式，文档指出你需要使用 add_theme_support 函数，并建议通过 after_setup_theme 动作钩子来注册。

这个钩子在 wp-settings.php 文件中定义，位于主题加载之后。

do_action( 'after_setup_theme' );

这里的 do_action 函数定义了动作钩子，钩子名称为 after_setup_theme。

我们还可以在开发者参考中这个钩子的参考页面阅读更多关于它的信息。

这里我们看到，这个钩子在每次页面加载时触发，在主题初始化之后，用于执行主题的基本设置、注册和初始化操作。

使用动作钩子

要使用动作，你需要在代码中将一个函数注册到已有的动作钩子上，这个函数被称为回调函数。

要将回调函数注册到动作上，你需要使用 WordPress 的 add_action 函数。

你需要将钩子名称和回调函数的名称作为参数传递给 add_action 函数。

让我们看看在主题的 functions.php 文件中是什么样子。

在你的代码编辑器中，导航到当前激活主题的 functions.php 文件并打开它。

如果你的主题没有 functions.php 文件，你可以在主题目录的根目录下创建一个。只需确保它命名为 functions.php，并在文件顶部包含 PHP 开始标签。

然后，将以下代码添加到你的 functions.php 文件中，将一个回调函数挂载到 after_setup_theme 动作钩子上。

add_action( 'after_setup_theme', 'wp_learn_setup_theme');

接下来你需要定义回调函数。

为此，使用 PHP 函数语法，并指定你要定义的函数名称。

function wp_learn_setup_theme() {

}

然后在回调函数内部添加 add_theme_support 函数调用。对于这个例子，你可以从文章格式文档中复制代码。

function wp_learn_setup_theme() {
    add_theme_support( 'post-formats', array( 'aside', 'gallery' ) );
}

在你的激活主题中添加这段代码后，如果你现在在 WordPress 仪表盘中创建一篇新文章，你会看到文章编辑器中出现文章格式选择框，你可以选择所需的文章格式。

这里你可以看到你在回调函数中启用的两种文章格式。

从这个例子中你学到，你可以使用动作来执行某些操作，无论是启用某个已有功能，还是在请求执行中添加一些内容。