本文详解如何在 woocommerce 商品分类归档页中精准输出当前分类的直接子分类，并安全截取其描述文本，避免误调全部分类或参数错误导致的空白/报错问题。

本文详解如何在 woocommerce 商品分类归档页中精准输出当前分类的直接子分类，并安全截取其描述文本，避免误调全部分类或参数错误导致的空白/报错问题。

在 WooCommerce 主题开发中，常需在父级商品分类（如“Electronics”）页面展示其直属子分类（如“Smartphones”、“Laptops”），而非全站所有分类。原始代码使用 get_terms('product_cat') 无差别获取全部分类，且 category_description($category_id) 中 $category_id 未定义，导致描述无法渲染甚至 PHP 警告。

正确的实现应基于当前请求的分类上下文动态获取子分类。核心步骤如下：

✅ 正确获取当前分类的子分类

使用 get_queried_object() 获取当前页面对应的分类对象，再通过 get_term_children() 获取其子分类 ID 列表。注意：get_term_children( $parent_id, $taxonomy ) 的第一个参数是父分类 ID，而非当前分类 ID —— 因此需传入 $main_term->term_id（当处于父分类页时，其自身即为父级；若需严格限定仅显示“直接子级”，应确保 $main_term 是父分类）：

<?php // 确保在 product_cat 分类归档页执行
if ( ! is_tax( 'product_cat' ) ) {
    return;
}

$main_term = get_queried_object();
if ( ! $main_term || ! isset( $main_term->term_id ) ) {
    return;
}

// 获取当前分类的所有直接子分类 ID（返回数组）
$child_ids = get_term_children( $main_term->term_id, 'product_cat' );

if ( ! empty( $child_ids ) && ! is_wp_error( $child_ids ) ) {
    foreach ( $child_ids as $child_id ) {
        $child_term = get_term_by( 'id', $child_id, 'product_cat' );
        if ( ! $child_term || is_wp_error( $child_term ) || ! $child_term->count ) {
            continue; // 跳过无效或无商品的子分类
        }

        $term_link = esc_url( get_term_link( $child_term ) );
        $thumbnail_id = get_term_meta( $child_term->term_id, 'thumbnail_id', true );
        $thumbnail_url = $thumbnail_id 
            ? wp_get_attachment_image_url( $thumbnail_id, 'woocommerce_thumbnail' )
            : wc_placeholder_img_src();

        // 截取描述：使用 category_description() 需传入 term object 或 ID，推荐传 object 更可靠
        $desc = category_description( $child_term );
        $trimmed_desc = $desc ? wp_trim_words( $desc, 20, '…' ) : '';
        ?>
        <div class="blog-archive-single" onclick="location.href='<?php echo $term_link; ?>';">
            <a href="<?php%20echo%20%24term_link;%20?>">
                <div class="blog-archive-single-image">
                    <?php if ( $thumbnail_url ) : ?><img src="<?php%20echo%20esc_url(%20%24thumbnail_url%20);%20?>" alt="<?php echo esc_attr( $child_term->name ); ?>"><?php else : ?><?php echo wc_placeholder_img( 'woocommerce_thumbnail' ); ?><?php endif; ?>
</div>
                <div class="blog-archive-single-content">
                    <div class="single-tile-heading small-heading">
                        <h3 class="title">
<?php echo esc_html( $child_term->name ); ?></h3>
                    </div>
                    <div class="blog-archive-content">
                        <p><?php echo $trimmed_desc; ?></p>
                    </div>
                    <div class="blog-archive-button">
                        <div class="blog-archive-button-inner">
                            <span class="read-more-button">View Details</span>
                            <div class="blog-button-icon">
                                <i class="fa-solid fa-chevron-right"></i>
                            </div>
                        </div>
                    </div>
                </div>
            </a>
        </div>
        <?php }
} else {
    // 可选：无子分类时的友好提示
    echo '<p class="no-children">No subcategories available.';
}
?>

⚠️ 关键注意事项

• get_term_children() 返回的是 ID 数组，必须用 get_term_by( 'id', $id, 'product_cat' ) 转换为完整 term 对象才能安全访问 name、description 等属性；
• 避免硬编码 $category_id：原代码中 category_description($category_id) 的变量未定义，应改为 category_description($child_term)（支持 term object 或 ID）；
• 图片处理建议：WooCommerce 分类支持自定义缩略图（存储于 thumbnail_id term meta），优先使用该值；fallback 到占位图更专业；
• 空值防护：始终检查 get_queried_object()、get_term_by() 及 category_description() 的返回值，防止 Notice 级错误；
• 性能考虑：get_term_children() 已缓存，无需额外优化；但若子分类极多，可配合 wp_list_categories() 的 child_of 参数替代（需调整 HTML 结构）。

掌握这一模式后，你不仅能准确呈现层级关系，还能为后续添加分类图标、计数 badge 或 AJAX 加载等扩展打下坚实基础。