如何在 Timber 中正确使用 tax_query 过滤自定义文章类型

本文详解 timber 框架下 `tax_query` 的标准语法结构，指出常见错误（将 tax_query 写为单层数组），并提供符合 wordpress 查询规范的嵌套数组写法，确保自定义分类法筛选正常生效。

在 Timber 开发中，通过 tax_query 关联自定义分类法（Taxonomy）筛选自定义文章类型（如 collaborateur）是高频需求。但一个极易被忽略的关键点是：tax_query 参数必须是一个「数组的数组」——即外层数组包含一个或多个查询子数组，每个子数组定义一条独立的分类法匹配规则。

你原始代码中的问题正源于此：

'tax_query' => array(   'taxonomy' => 'expertise-collaborateur',   'field'    => 'term_id',   'terms'    => Array(11), ),

这段写法将 tax_query 直接设为一个关联数组，而非数组集合。wordPress 查询引擎会因此忽略整个 tax_query，导致筛选失效（即使其他参数如 post_type 正确，结果仍返回未过滤的全部文章）。

✅ 正确写法如下（注意内层 array(…)）：

$args = array(   'post_type'   => 'collaborateur',   'post_status' => 'publish',   'order'       => 'DESC',   'posts_per_page' => -1, // 可选：避免分页截断   'tax_query'   => array(     array(       'taxonomy' => 'expertise-collaborateur',       'field'    => 'term_id',     // 支持 'term_id', 'slug', 'name'       'terms'    => array(11),     // 可传单值（11）或数组（[11, 12]）       'operator' => 'IN'           // 默认值，也可用 'AND', 'NOT IN' 等     )   ) );  $context['teamfilter'] = Timber::get_posts($args);

? 进阶提示：动态绑定 ACF 字段值
你提到 $expertise_team = get_field(‘categorie_dexpertise’) 获取的是 ACF 分类字段值。若该字段返回的是 term Object 或 term ID（推荐），可直接用于 terms：

// 假设 ACF 字段返回的是 term_id（数字） if ($expertise_team && is_numeric($expertise_team)) {   $args['tax_query'][0]['terms'] = array((int)$expertise_team); }  // 若返回的是 term slug（字符串），则需同步修改 field： // 'field' => 'slug'  $context['teamfilter'] = Timber::get_posts($args);

⚠️ 注意事项

• tax_query 必须是二维数组结构，哪怕只有一条规则；
• terms 接受整数、字符串或数组，但类型需与 field 严格一致（term_id → 数字，slug → 字符串）；
• 使用 Timber::get_posts() 时，确保目标分类法 expertise-collaborateur 已在 wordpress 中正确定义，并已为 collaborateur 类型注册；
• 调试建议：临时添加 ‘suppress_filters’ => false 并用 WP_Query 原生对象检查 sql，或使用 Query Monitor 插件验证实际执行的查询语句。

掌握这一语法规范，即可稳定实现基于分类法的精准内容聚合，大幅提升 Timber 主题的灵活性与专业性。