本教程详细介绍了如何在wordpress自定义文章类型（cpt）的单页模板中正确显示其关联的自定义分类法（custom taxonomy）术语。文章将纠正使用`the_category()`函数显示自定义分类法时常见的错误，并指导读者如何通过`get_the_terms()`函数及相关代码实现准确的术语列表展示，同时涵盖自定义文章类型和自定义分类法的正确注册方法及重要注意事项。
在WordPress开发中，自定义文章类型（Custom Post Type, CPT）和自定义分类法（Custom Taxonomy）是扩展网站功能的强大工具。它们允许开发者创建高度定制化的内容结构。然而，在为自定义文章类型创建了自定义分类法后，许多开发者可能会遇到一个常见问题：如何在其单页模板（如single-{post-type}.php）中正确显示这些自定义分类法的术语（terms）。本文将提供一个完整的教程，详细说明如何注册自定义文章类型和自定义分类法，并演示如何在前端正确显示它们。
1. 注册自定义文章类型（Custom Post Type）
首先，我们需要注册一个自定义文章类型。这里以一个名为“Members”的自定义文章类型为例。在你的主题的functions.php文件或一个自定义插件中添加以下代码：
function register_members_post_type() {
$labels = array(
'name' => 'Members',
'singular_name' => 'Member',
'all_items' => '所有成员',
'add_new_item' => '添加新成员',
'edit_item' => '编辑成员',
'view_item' => '查看成员',
'search_items' => '搜索成员',
'not_found' => '未找到成员',
'not_found_in_trash' => '回收站中未找到成员',
);
$args = array(
'labels' => $labels,
'public' => true, // 是否公开显示在前端
'has_archive' => true, // 是否有文章归档页
'query_var' => true, // 允许通过查询变量访问
'rewrite' => array('slug' => 'members'), // 自定义URL重写规则
'supports' => array('title', 'editor', 'thumbnail'), // 支持的编辑器功能
'menu_icon' => 'dashicons-groups', // 后台菜单图标
'hierarchical' => false, // 是否支持层级结构（如页面）
);
register_post_type('members', $args);
// 刷新重写规则，确保自定义文章类型URL生效。
// 注意：在开发环境中，每次注册新的CPT或Taxonomy后可能需要运行一次，
// 但不建议在生产环境的每次页面加载时都运行，因为它会消耗资源。
// 通常在插件激活或主题设置更新时触发。
// flush_rewrite_rules(false);
}
add_action('init', 'register_members_post_type');重要提示：
- flush_rewrite_rules(false); 函数用于刷新WordPress的URL重写规则。在首次注册自定义文章类型或分类法，或者更改其rewrite参数后，需要运行一次此函数以确保新的URL结构生效。在开发阶段，你可以在代码中暂时启用它，但在生产环境中，建议仅在插件激活或主题设置更新等特定时机调用，以避免不必要的性能开销。你也可以在WordPress后台的“设置”->“固定链接”页面点击“保存更改”按钮来手动刷新重写规则。
2. 注册自定义分类法（Custom Taxonomy）
接下来，为我们的“Members”自定义文章类型注册一个自定义分类法。这里我们创建一个名为“My Categories”的分类法，其slug为my_categories。
function register_members_taxonomies() {
$labels = array(
'name' => '我的分类',
'singular_name' => '我的分类',
'search_items' => '搜索我的分类',
'all_items' => '所有我的分类',
'parent_item' => '父级我的分类',
'parent_item_colon' => '父级我的分类:',
'edit_item' => '编辑我的分类',
'update_item' => '更新我的分类',
'add_new_item' => '添加新我的分类',
'new_item_name' => '新我的分类名称',
'menu_name' => '我的分类',
);
$args = array(
'labels' => $labels,
'public' => true, // 是否公开显示在前端
'hierarchical' => true, // 是否支持层级结构（如分类目录）
'show_ui' => true, // 是否在后台显示用户界面
'show_admin_column' => true, // 是否在文章列表页显示为列
'query_var' => true, // 允许通过查询变量访问
'rewrite' => array('slug' => 'my-categories'), // 自定义URL重写规则
);
// 将 'my_categories' 分类法关联到 'members' 文章类型
register_taxonomy('my_categories', array('members'), $args);
}
add_action('init', 'register_members_taxonomies');重要提示：
- 自定义分类法的slug（这里是my_categories）必须是唯一的，并且不能与WordPress内置的分类法（如category或post_tag）冲突。
- 'hierarchical' => true 表示这是一个层级分类法，类似WordPress的“分类目录”。如果设置为false，则是一个非层级分类法，类似“标签”。
3. 创建并分配自定义分类术语
完成上述注册后，请在WordPress后台：
- 导航到“成员” -> “添加新成员”，创建一个新的“成员”文章。
- 在右侧边栏，你会看到一个新的元框，标题为“我的分类”（或你自定义的标签）。
- 在此元框中，为你的“成员”文章分配一个或多个“我的分类”术语。
4. 在单页模板中显示自定义分类术语
这是最关键的一步。许多开发者可能会尝试使用the_category()函数来显示自定义分类法的术语，但这个函数是专为WordPress内置的“分类目录”（category taxonomy）设计的，它无法识别自定义分类法。
为了显示自定义分类法的术语，我们需要使用get_the_terms()函数。这个函数能够获取指定文章ID和分类法slug下的所有术语。
在你的single-members.php模板文件（或者任何你希望显示这些术语的模板，确保它在主循环内）中，使用以下代码：
<?php
if (have_posts()) :
while (have_posts()) : the_post();
?>
<h1><?php the_title(); ?></h1>
<div><?php the_content(); ?></div>
<?php
// 获取当前文章（$post）的 'my_categories' 分类法的所有术语
$categories = get_the_terms($post->ID, 'my_categories');
// 检查是否成功获取到术语，并且术语数组不为空
if (!empty($categories) && !is_wp_error($categories)) {
echo '<h3>关联的我的分类:</h3>';
echo '<ul>';
foreach ($categories as $cat) {
// $cat 是一个 WP_Term 对象，包含术语的各种信息
// print "<li>" . esc_html($cat->name) . "</li>"; // 仅显示名称
// 如果需要链接到分类归档页
print "<li><a href=\"" . esc_url(get_term_link($cat->term_id, 'my_categories')) . "\">" . esc_html($cat->name) . "</a></li>";
}
echo '</ul>';
} else {
echo '<p>此成员暂无关联的我的分类。</p>';
}
?>
<?php
endwhile;
endif;
?>代码解释：
- get_the_terms($post->ID, 'my_categories'): 这个函数接收两个参数。第一个是文章ID（$post->ID代表当前文章的ID），第二个是自定义分类法的slug（这里是my_categories）。它返回一个WP_Term对象数组，如果文章没有关联该分类法的术语，则返回false或WP_Error对象。
- !empty($categories) && !is_wp_error($categories): 这是一个重要的检查，用于确保get_the_terms()成功返回了术语，并且没有发生错误。
- foreach ($categories as $cat): 遍历获取到的每个术语。
- $cat->name: 获取术语的显示名称。
- get_term_link($cat->term_id, 'my_categories'): 生成该术语的归档页面链接，允许用户点击查看该分类下的所有成员。
总结与注意事项
- the_category() vs. get_the_terms(): 核心区别在于the_category()仅适用于WordPress内置的“分类目录”，而get_the_terms()是显示自定义分类法术语的正确方法。
- 分类法Slug的唯一性: 确保你的自定义分类法slug是唯一的，以避免与WordPress核心或其他插件/主题的分类法冲突。
- 刷新重写规则: 在注册或修改自定义文章类型和分类法后，务必刷新WordPress的固定链接重写规则，无论是通过后台“设置”->“固定链接”保存，还是在开发阶段使用flush_rewrite_rules()。
- 错误处理: 在前端显示数据时，始终进行empty()和is_wp_error()检查，以确保代码的健壮性，避免在没有数据时产生错误。
- 代码位置: 注册自定义文章类型和分类法的代码应放在主题的functions.php文件或一个自定义插件中，以确保它们在主题切换后仍然有效。
通过遵循本教程的步骤，你将能够成功地在WordPress自定义文章类型的单页模板中显示其关联的自定义分类法术语，从而为你的网站提供更灵活和强大的内容展示能力。
