剖析 `comments_template()` 函数的源码，解释它是如何通过 `comments_template` 过滤器允许开发者自定义评论模板路径的？

嘿，各位代码界的弄潮儿们，今天咱们来聊聊 WordPress 评论模板的那些事儿。主题就是扒一扒 comments_template() 这个函数的底裤，看看它如何通过 comments_template 过滤器，让开发者们能随心所欲地定制评论模板的路径。

准备好了吗？咱们这就开始！

第一幕：comments_template() 的身世之谜

首先，咱们得认识一下今天的主角 comments_template()。这个函数位于 WordPress 的 /wp-includes/comment-template.php 文件中，它的主要职责就是加载评论模板。简单来说，就是让 WordPress 知道该用哪个文件来显示评论。

让我们先看看它的基本结构（以下代码简化了部分内容，只保留核心逻辑）：

function comments_template( $template = '/comments.php', $separate_comments = false ) {
    global $wp_query, $withcomments, $post, $wp_did_template_redirect;

    if ( ! ( is_singular() && ( have_comments() || 'open' == $post->comment_status ) ) ) {
        return;
    }

    $req = get_option('require_name_email');

    if ( ! isset($wp_did_template_redirect) ) {
        _doing_it_wrong( __FUNCTION__, sprintf( __( 'The %1$s function is being called incorrectly.' ), 'comments_template()' ), '3.0' );
        wp_die( __('Please see <a href="https://codex.wordpress.org/Debugging_in_WordPress">Debugging in WordPress</a> for more information.') );
        return;
    }

    $template = apply_filters( 'comments_template', $template );

    if ( empty( $template ) ) {
        return;
    }

    if ( file_exists( get_stylesheet_directory() . $template ) )
        $include = get_stylesheet_directory() . $template;
    elseif ( file_exists( get_template_directory() . $template ) )
        $include = get_template_directory() . $template;
    else
        $include = ABSPATH . WPINC . '/theme-compat/comments.php';

    include( $include );
}

这段代码做了几件事儿：

检查条件： 确保当前页面是文章页面，并且允许评论（要么已经有评论，要么评论是开放状态）。
应用过滤器： $template = apply_filters( 'comments_template', $template ); 这行代码就是关键！它会执行所有挂载到 comments_template 过滤器上的函数，允许我们修改 $template 变量的值。
查找模板： 按照以下顺序查找评论模板文件：
- 当前主题的样式表目录 (Child Theme)
- 当前主题的模板目录 (Parent Theme)
- WordPress 默认的兼容模板目录 (/wp-includes/theme-compat/comments.php)
加载模板： 找到模板文件后，使用 include() 函数加载它。

第二幕：comments_template 过滤器的威力

现在，咱们来深入了解 comments_template 过滤器。这个过滤器允许开发者在 comments_template() 函数查找和加载评论模板之前，修改模板的路径。

想象一下，你想要为你的 WordPress 站点创建一个完全定制的评论模板。你不喜欢默认的 comments.php，你想要用一个名为 my-custom-comments.php 的文件来显示评论。

你可以这样做：

add_filter( 'comments_template', 'my_custom_comments_template' );

function my_custom_comments_template( $template ) {
    // 检查是否为文章页面
    if ( is_singular() ) {
        // 构建自定义评论模板的路径
        $custom_template = get_stylesheet_directory() . '/my-custom-comments.php';

        // 检查自定义模板是否存在
        if ( file_exists( $custom_template ) ) {
            // 如果存在，则使用自定义模板
            return $custom_template;
        }
    }

    // 如果不是文章页面或自定义模板不存在，则返回原始模板
    return $template;
}

这段代码做了什么？

添加过滤器： add_filter( 'comments_template', 'my_custom_comments_template' ); 将 my_custom_comments_template() 函数挂载到 comments_template 过滤器上。这意味着当 comments_template() 函数执行到 apply_filters( 'comments_template', $template ); 这行代码时，my_custom_comments_template() 函数会被调用。
自定义函数： my_custom_comments_template() 函数接收一个参数 $template，这个参数是 comments_template() 函数传递过来的原始模板路径。
条件判断： if ( is_singular() ) 确保只在文章页面上使用自定义模板。
构建路径： $custom_template = get_stylesheet_directory() . '/my-custom-comments.php'; 构建自定义评论模板的完整路径。这里使用了 get_stylesheet_directory() 函数来获取当前主题的样式表目录（如果是子主题，则获取子主题的目录）。
检查文件是否存在： if ( file_exists( $custom_template ) ) 检查自定义模板文件是否存在。
返回自定义模板： 如果自定义模板存在，则 return $custom_template; 将 $template 变量的值修改为自定义模板的路径。
返回原始模板： return $template; 如果不是文章页面或自定义模板不存在，则返回原始的 $template 值，保持 WordPress 默认的行为。

第三幕：更高级的用法

comments_template 过滤器的用法远不止这些。你可以根据不同的条件，使用不同的评论模板。例如，你可以根据文章的分类、标签、作者等来选择不同的模板。

add_filter( 'comments_template', 'my_dynamic_comments_template' );

function my_dynamic_comments_template( $template ) {
    global $post;

    if ( is_singular() ) {
        // 根据文章分类选择不同的模板
        $categories = get_the_category( $post->ID );
        if ( ! empty( $categories ) ) {
            $category_slug = $categories[0]->slug;

            $custom_template = get_stylesheet_directory() . '/comments-' . $category_slug . '.php';

            if ( file_exists( $custom_template ) ) {
                return $custom_template;
            }
        }

        // 根据文章作者选择不同的模板
        $author_id = $post->post_author;
        $custom_template = get_stylesheet_directory() . '/comments-author-' . $author_id . '.php';

        if ( file_exists( $custom_template ) ) {
            return $custom_template;
        }
    }

    return $template;
}

这段代码做了什么？

根据分类选择模板： 它首先获取文章的分类，然后尝试加载名为 comments-{category_slug}.php 的模板。例如，如果文章的分类是 "news"，它会尝试加载 comments-news.php。
根据作者选择模板： 如果没有找到分类特定的模板，它会尝试加载名为 comments-author-{author_id}.php 的模板。例如，如果文章的作者 ID 是 1，它会尝试加载 comments-author-1.php。
返回原始模板： 如果以上两种模板都没有找到，则返回原始的 $template 值。

第四幕：注意事项

在使用 comments_template 过滤器时，需要注意以下几点：

确保自定义模板文件存在： 如果你指定的自定义模板文件不存在，WordPress 可能会显示一个错误。所以，一定要先创建好模板文件。
避免死循环： 不要在自定义模板中再次调用 comments_template() 函数，否则会导致死循环。
优先级： 如果有多个函数挂载到 comments_template 过滤器上，它们的执行顺序由优先级决定。你可以使用 add_filter() 函数的第三个参数来指定优先级。默认优先级是 10。
路径问题： 务必使用 get_stylesheet_directory() 或 get_template_directory() 函数来构建模板路径，以确保路径的正确性。

总结：comments_template 过滤器的解剖

为了更好地理解 comments_template 过滤器，咱们用一张表格来总结一下：

特性	描述
作用	允许开发者修改 `comments_template()` 函数加载的评论模板路径。
挂载点	`comments_template`
参数	`$template`：原始的评论模板路径。
返回值	修改后的评论模板路径。
使用场景	为不同的文章类型、分类、标签、作者等使用不同的评论模板。使用完全自定义的评论模板。 * 根据用户角色或权限显示不同的评论模板。
注意事项	确保自定义模板文件存在。避免死循环。注意优先级。使用正确的路径函数。
相关函数	`comments_template()`, `add_filter()`, `get_stylesheet_directory()`, `get_template_directory()`, `is_singular()`, `have_comments()`, `get_the_category()`, `get_the_tags()`, `get_current_user_id()`
代码示例	参见上面提供的代码示例。

第五幕：实战演练

咱们来做一个更实际的例子。假设你有一个在线课程网站，你想要为不同的课程类型使用不同的评论模板。

你的课程类型有：

编程 (programming)
设计 (design)
营销 (marketing)

你可以创建三个不同的评论模板：

comments-programming.php
comments-design.php
comments-marketing.php

然后，你可以使用以下代码来加载这些模板：

add_filter( 'comments_template', 'my_course_comments_template' );

function my_course_comments_template( $template ) {
    global $post;

    if ( is_singular( 'course' ) ) { // 假设你的课程文章类型是 'course'
        $course_type = get_post_meta( $post->ID, 'course_type', true ); // 假设你使用自定义字段 'course_type' 来存储课程类型

        if ( ! empty( $course_type ) ) {
            $custom_template = get_stylesheet_directory() . '/comments-' . $course_type . '.php';

            if ( file_exists( $custom_template ) ) {
                return $custom_template;
            }
        }
    }

    return $template;
}

这段代码做了什么？

检查文章类型： if ( is_singular( 'course' ) ) 确保只在课程页面上使用自定义模板。
获取课程类型： $course_type = get_post_meta( $post->ID, 'course_type', true ); 从自定义字段 course_type 中获取课程类型。
构建模板路径： $custom_template = get_stylesheet_directory() . '/comments-' . $course_type . '.php'; 根据课程类型构建模板路径。
检查文件是否存在： if ( file_exists( $custom_template ) ) 检查模板文件是否存在。
返回自定义模板： 如果模板文件存在，则 return $custom_template; 返回自定义模板的路径。
返回原始模板： 如果不是课程页面或自定义模板不存在，则返回原始的 $template 值。

第六幕：总结与展望

通过今天的讲解，相信大家对 comments_template() 函数和 comments_template 过滤器有了更深入的了解。掌握了这些技巧，你就可以随心所欲地定制 WordPress 评论模板，让你的网站更具个性化和专业性。

记住，代码的世界是充满乐趣的，只要你勇于探索，就能发现更多的可能性！

希望今天的分享对大家有所帮助。下次再见！祝大家编码愉快， Bug 永不相见！

发表回复 取消回复

发表回复取消回复