本文详解如何通过 woocommerce_rest_prepare_product_cat 过滤器扩展 WooCommerce REST API 的 /wp-json/wc/v3/products/categories 端点，动态注入子分类（children）信息，包括数量统计与完整子项数组。
本文详解如何通过 `woocommerce_rest_prepare_product_cat` 过滤器扩展 woocommerce rest api 的 `/wp-json/wc/v3/products/categories` 端点，动态注入子分类（children）信息，包括数量统计与完整子项数组。
在 WooCommerce REST API 中，产品分类（product_cat）端点默认不返回嵌套子分类数据，这在构建树形导航、前端分类筛选或移动端层级菜单时尤为不便。与产品（product）端点可通过 woocommerce_rest_prepare_product_object 轻松扩展不同，分类端点的过滤器命名规则较为隐蔽——它基于注册的分类法（taxonomy）动态生成，即 woocommerce_rest_prepare_{taxonomy}。
对于标准产品分类，其 taxonomy 名为 product_cat，因此应使用如下过滤器：
add_filter('woocommerce_rest_prepare_product_cat', 'custom_change_category_response', 20, 3);该钩子在每个分类项序列化为 JSON 响应前触发，接收三个参数：$response（WP_REST_Response 对象）、$object（WP_Term 实例）、$request（WP_REST_Request 对象）。我们可直接修改 $response->data 数组，注入自定义字段。
以下是一个生产就绪的示例函数，它为每个分类添加两项关键数据：
- children_count：当前分类直系子分类数量；
- childs_array：包含所有子分类完整 WP_Term 对象的数组（含 id、name、slug、count 等原生字段）。
function custom_change_category_response($response, $object, $request) {
// 确保仅处理成功响应且数据存在
if (is_wp_error($response) || !isset($response->data['id'])) {
return $response;
}
$category_id = $response->data['id'];
// 查询直系子分类（不含深层嵌套，如需递归请另行实现）
$child_terms = get_terms([
'taxonomy' => 'product_cat',
'hide_empty' => false,
'orderby' => 'name',
'order' => 'ASC',
'child_of' => $category_id,
'parent' => $category_id, // 更精准限定为直接子级（推荐）
'fields' => 'all', // 返回完整 term 对象
]);
// 处理查询异常（如无子分类或权限限制）
if (is_wp_error($child_terms)) {
$child_terms = [];
}
// 注入自定义字段
$response->data['children_count'] = count($child_terms);
$response->data['children'] = array_map(function ($term) {
return [
'id' => (int) $term->term_id,
'name' => $term->name,
'slug' => $term->slug,
'count' => (int) $term->count,
'description' => $term->description,
'parent' => (int) $term->parent,
];
}, $child_terms);
return $response;
}
add_filter('woocommerce_rest_prepare_product_cat', 'custom_change_category_response', 20, 3);✅ 注意事项与最佳实践：
- child_of 参数会返回所有后代（含孙级），若仅需直接子分类，请改用 'parent' => $category_id（如上示例），语义更清晰且性能更优；
- get_terms() 默认受用户能力限制（如隐藏未发布分类），如需管理员视角数据，请确保调用上下文具备 manage_categories 权限，或在 pre_get_terms 钩子中临时调整查询条件；
- 若需支持深度递归（如完整分类树），建议改用 get_term_children() + 批量 get_term() 查询，避免 N+1 数据库问题；
- 前端消费时，请注意 children 字段为数组而非对象，且不含嵌套 children 子字段（如需完整树结构，应在服务端递归组装后统一返回）；
- 该扩展不影响原始端点兼容性：未订阅此钩子的客户端仍可正常解析原有字段，新增字段为完全向后兼容的增强。
通过以上方式，你即可在 /wp-json/wc/v3/products/categories 及其单个分类详情（如 /categories/123）响应中，稳定获取结构化的子分类数据，显著提升 Headless WooCommerce 架构下的分类交互体验。
