许多wordpress开发者在尝试为自定义分类（custom taxonomy）创建归档页面时，常遇到内容无法正确显示的问题。本文将深入探讨wordpress的模板层级机制，特别是针对分类归档页面的处理方式。我们将演示如何通过合理命名模板文件，并利用wordpress内置的查询功能，高效且准确地展示特定分类下的文章列表，避免手动查询的复杂性和潜在错误，从而优化页面内容的呈现。
在WordPress开发中，为自定义分类法（Custom Taxonomy）创建归档页面并显示该分类下的文章列表是一个常见需求。然而，不少开发者在尝试手动创建如pdf_cat.php这样的页面来处理分类过滤和内容展示时，往往会遇到内容不显示的问题。这通常是由于对WordPress的模板层级（Template Hierarchy）机制理解不足导致的。
理解WordPress模板层级与分类归档
WordPress有一套严格的规则来决定加载哪个模板文件来渲染特定URL的内容。当用户访问一个自定义分类的归档页面时（例如 yourdomain.com/taxonomy/pdf_cat/term-name），WordPress会按照预设的层级顺序查找对应的模板文件。
对于自定义分类归档，WordPress的查找顺序大致如下：
- taxonomy-{taxonomy}-{term}.php: 最具体，针对某个特定分类下的特定术语（term）。例如，taxonomy-pdf_cat-reports.php。
- taxonomy-{taxonomy}.php: 针对某个特定分类下的所有术语。例如，taxonomy-pdf_cat.php。
- taxonomy.php: 针对所有自定义分类的通用模板。
- archive.php: 针对所有归档类型的通用模板（包括分类、标签、作者、日期等）。
- index.php: 最终的通用回退模板。
关键在于，当WordPress加载了这些层级中的任何一个模板文件时，它已经自动识别了当前的分类和术语，并设置好了主查询（main query）。这意味着在这些模板文件中，你无需手动使用WP_Query来获取当前分类下的文章，只需直接使用WordPress的循环（The Loop）即可。
正确构建自定义分类归档页面
为了解决自定义分类归档页面不显示内容的问题，最核心的步骤是正确命名你的模板文件，并简化其内部逻辑。
假设你的自定义分类法slug是 pdf_cat，那么你应该将你的 pdf_cat.php 文件重命名为 taxonomy-pdf_cat.php，并将其放置在主题的根目录下。
示例：taxonomy-pdf_cat.php 的内容
<?php
/**
* Template Name: Custom Taxonomy Archive for pdf_cat
* Description: This template displays all posts belonging to a term in the 'pdf_cat' taxonomy.
*
* @package YourThemeName
*/
get_header(); // 引入主题的头部文件
?>
<div id="primary" class="content-area">
<main id="main" class="site-main">
<?php if ( have_posts() ) : ?>
<header class="page-header">
<?php
// 自动显示当前分类术语的标题和描述
the_archive_title( '<h1 class="page-title">', '</h1>' );
the_archive_description( '<div class="archive-description">', '</div>' );
?>
</header><!-- .page-header -->
<?php
// 开始WordPress循环，自动获取当前分类下的文章
while ( have_posts() ) : the_post();
// 根据你的主题结构，可以引入一个内容模板部分
// 例如：get_template_part( 'template-parts/content', get_post_type() );
?>
<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
<header class="entry-header">
<?php the_title( '<h2 class="entry-title"><a href="' . esc_url( get_permalink() ) . '" rel="bookmark">', '</a></h2>' ); ?>
</header><!-- .entry-header -->
<div class="entry-content">
<?php the_excerpt(); // 或者 the_content() ?>
</div><!-- .entry-content -->
</article><!-- #post-<?php the_ID(); ?> -->
<?php
endwhile;
// 分页导航
the_posts_pagination( array(
'prev_text' => __( 'Previous page', 'your-text-domain' ),
'next_text' => __( 'Next page', 'your-text-domain' ),
) );
else :
// 如果没有文章，显示“未找到”消息
get_template_part( 'template-parts/content', 'none' );
endif;
?>
</main><!-- #main -->
</div><!-- #primary -->
<?php
get_sidebar(); // 引入主题的侧边栏（如果需要）
get_footer(); // 引入主题的底部文件
?>关键点：
- 文件命名: 将文件命名为 taxonomy-{taxonomy-slug}.php (例如 taxonomy-pdf_cat.php) 或更通用的 taxonomy.php。
- 自动查询: 在这个模板文件中，WordPress已经自动设置了主查询，你只需直接使用 have_posts() 和 the_post() 即可遍历当前分类下的文章。无需手动调用 get_the_terms()、get_term_name()、get_term_ID() 或 new WP_Query()。
- the_archive_title() 和 the_archive_description(): 这些函数会自动获取并显示当前归档页面的标题（即分类术语名称）和描述。
下拉菜单的实现 (newsletter.php)
在 newsletter.php 中用于生成下拉菜单的代码，其逻辑是正确的。它利用 get_term_link($term->term_id) 生成了指向对应分类归档页面的URL，并通过JavaScript在选择变化时进行页面跳转。
newsletter.php 中的下拉菜单代码（无需修改）：
<select name="form" id="form">
<div class="options">
<option value="<?php echo home_url('/newsletter'); ?>" selected>一覧</option>
<?php
$args = array(
'orderby' => 'slug',
'order' => 'ASC',
'parent' => 0,
'hide_empty' => false
);
$terms = get_terms([
'taxonomy' => 'pdf_cat',
'hide_empty' => false,
]);
foreach( $terms as $term ){
// get_term_link() 会生成正确的分类归档URL
echo '<option class="ctg" value="'. get_term_link($term->term_id) .' ">' . $term->name . '</option>';
}
?>
</div>
</select>
<script type="text/javascript">
$("#form").change(function(){
var url = $(this).val();
location.assign(url); // JavaScript将用户重定向到选中的分类归档URL
});
</script>当用户从下拉菜单中选择一个分类时，JavaScript会获取 option 的 value (即由 get_term_link() 生成的分类归档URL)，然后浏览器会跳转到该URL。此时，WordPress会根据模板层级找到并加载 taxonomy-pdf_cat.php (或 taxonomy.php)，并自动显示该分类下的文章。
注意事项与最佳实践
- 避免使用 query_posts(): 在原始代码中使用了 query_posts()。这个函数强烈不建议在主题或插件中使用，因为它会修改WordPress的主查询，可能导致分页问题、性能下降以及与其他插件的冲突。对于自定义循环，应始终使用 WP_Query。但在分类归档模板中，由于主查询已自动设置，通常连 WP_Query 都不需要。
- 主题结构: 确保你的 taxonomy-pdf_cat.php 文件位于当前活动主题的根目录下，或者位于子主题的根目录下。
- 自定义文章类型 (post_type): 示例中假设你的自定义文章类型是 pdf。WordPress的分类归档模板会自动包含所有关联到该分类的自定义文章类型。如果你需要进一步过滤，可以在 pre_get_posts 钩子中修改主查询。
- 文本域: 在 the_posts_pagination 等函数中使用了 your-text-domain，请替换为你主题实际的文本域，以便国际化。
- 内容模板: get_template_part( 'template-parts/content', get_post_type() ); 是一种模块化开发的好习惯，它将文章的显示逻辑分离到单独的文件中，便于维护。
总结
解决WordPress自定义分类归档页面内容不显示的核心在于理解并遵循WordPress的模板层级机制。通过将你的分类归档文件正确命名为 taxonomy-{taxonomy-slug}.php (或 taxonomy.php)，并利用WordPress自动设置的主查询，你可以极大地简化代码，提高开发效率，并确保页面内容的正确显示。同时，避免使用 query_posts() 是维护WordPress网站健康和性能的关键最佳实践。
