按 ACF 字段筛选 WooCommerce 产品:类型、设置与修复
使用 HUSKY 可以按 ACF 字段值筛选 WooCommerce 产品,但前提是该字段保存的值可以被数据库查询进行比较。单值字段(下拉选择、单选按钮、真/假、数字、文本、日期选择器)可以正常筛选。复选框字段,以及开启了选择多个 (Select Multiple)的下拉选择字段,要么根本不会出现在筛选器中,要么显示的选项永远找到 0 个产品。下面介绍 HUSKY 如何读取 ACF 数据、哪些字段类型可用、如何设置每一种,以及如何处理多值字段。
HUSKY 读取 ACF 字段的两种方式
ACF 将每个字段保存为普通的产品元数据:在 wp_postmeta 表中占一行,以字段的字段名称 (Field Name)为键,保存的值为内容。HUSKY 有两个内置扩展可以按这样的行进行筛选。两者都是系统扩展,始终处于启用状态,无需开启。
- ACF 扩展(ACF 字段 (ACF fields))会自动找到您的 ACF 字段组,并在结构 (Structure)选项卡上以字段标签(字段组标题) (Field label (Group title))的形式列出其中的下拉选择、单选按钮和真/假字段。将字段旁边的下拉菜单设为是 (Yes)并保存,该字段就进入了筛选器。其他字段类型则完全不会列出。详情请见 ACF 扩展页面。
- 元数据选项卡(元数据筛选 (Meta filter)扩展)适用于任何元数据键,无论是否来自 ACF。您自己添加键,并选择它的显示方式:滑块 (Slider)、文本搜索 (Search by text)、复选框 (Checkbox)、下拉菜单 (Drop-down)、多选下拉菜单 (Multi Drop-down)或日期选择器 (Datepicker),以及它保存的数据类型:number、string或date。参见按元字段筛选。
ACF 扩展设置起来更快,但它有三条规则,可以解释大多数“找不到字段”和“0 个产品”的反馈:
- 字段组必须按文章类型分配。HUSKY 只会读取位置 (Location)规则中包含文章类型等于产品 (Post Type is equal to Product)的字段组。仅通过产品分类之类规则显示的字段组会被跳过,因此它的字段永远不会出现在结构 (Structure)选项卡上。
- 每个选项的值必须与其标签一致。在 ACF 中,写成
xl : Extra large的选项会在产品上保存xl,但 ACF 扩展搜索的是标签Extra large,因此什么也找不到。每行只写一个词的选项(值和标签相同),或者仅大小写不同的选项(如red : Red)可以正常工作。包含引号字符的标签永远无法匹配。 - “选择多个”必须关闭。开启了选择多个 (Select Multiple)的下拉选择字段仍会被列出,但找不到任何产品,原因见下文。
如果某个字段违反了其中任何一条规则,请改用元数据选项卡来筛选,在那里您可以控制键和确切的值。
哪些 ACF 字段类型可以筛选
| ACF 字段类型 | 产品上保存的内容 | 如何在 HUSKY 中筛选 |
|---|---|---|
| 下拉选择(单选)、单选按钮 | 一个选项值 | ACF 扩展,或元数据的下拉菜单 (Drop-down) / 多选下拉菜单 (Multi Drop-down) |
| 按钮组 | 一个选项值 | 元数据的下拉菜单 (Drop-down) / 多选下拉菜单 (Multi Drop-down) |
| 真 / 假 | 1 或 0 | ACF 扩展,或元数据的复选框 (Checkbox) |
| 数字、范围 | 一个数字 | 元数据的滑块 (Slider),类型为number |
| 文本、电子邮件、URL | 一个字符串 | 元数据的文本搜索 (Search by text),或列出各个值的下拉菜单 (Drop-down) |
| 日期选择器 | 形如 20250131 的日期(Ymd) | 元数据的日期选择器 (Datepicker)加一个钩子(见下文) |
| 复选框、开启选择多个 (Select Multiple)的下拉选择、多值的关系 / 文章对象 / 分类法 | 一个序列化数组 | 无法用普通比较实现;参见下面的两种解决办法 |
| 重复器、灵活内容 | 带编号的行,如 specs_0_width | 无法作为单个字段来筛选 |
组字段内部的字段以 groupname_fieldname 的形式保存,并按其自身类型进行筛选。日期时间选择器保存的是 2025-01-31 14:00:00 这样的文本,日期选择器筛选无法对其进行比较。
为什么复选框和多选字段找不到任何内容
当一个字段可以保存多个值时,ACF 会以 PHP 序列化格式将它们打包成一个字符串。一辆带空调和座椅加热的汽车会得到这样的一行元数据:
a:2:{i:0;s:2:"ac";i:1;s:12:"heated_seats";}
ACF 扩展以及下拉菜单、多选下拉菜单和复选框视图,向数据库查询的是值与所选选项相等的行。ac 不等于整个字符串,因此结果为 0。在 ACF 中关闭选择多个 (Select Multiple)并不能修复已有产品:它们的值保持序列化状态,直到每个产品以单个值重新保存。
在元数据选项卡上设置 ACF 字段
- 找到真实的元数据键。它是字段在 ACF 中的字段名称 (Field Name)(例如
body_type),而不是标签。在元数据 (Meta Data)选项卡上,通过产品 ID 获取任意产品的键 (Get keys from any product by its ID)会列出某个产品的所有键。每个 ACF 字段会出现两次:body_type保存值,_body_type保存 ACF 的内部字段引用。请使用不带下划线的键。键区分大小写,且从不包含空格或括号。 - 添加该键:使用手动添加自定义键 (Add Custom key by hands)或从列表中选择,输入标题,并选择视图和类型。对于文本值,请选择string。如果选择number,MySQL 会在比较之前把
Coupe这样的文本转换为 0,筛选器就会返回所有带有该键的产品,看起来就像“筛选器没有任何作用”。 - 列出选项,适用于下拉菜单 (Drop-down)和多选下拉菜单 (Multi Drop-down)。元字段是自由文本,因此 HUSKY 无法自行生成值列表;需要由您书写,并用逗号分隔。当显示的标题与保存的值不同时,使用
title^value。对于 ACF 选项coupe : Coupe和suv : SUV / Crossover,写法如下:Coupe^coupe,SUV / Crossover^suv^后面的部分必须与 ACF 保存的内容完全一致,即选项值,而不是它的标签。 - 保存,打开结构 (Structure)选项卡,将新项目设为是 (Yes),拖到合适的位置并再次保存。旁边的齿轮图标包含该视图自己的选项,例如复选框的搜索选项 (Search option)和搜索值 (Search value),或者文本搜索 (Search by text)的文本搜索条件 (Text search conditional)(LIKE 或 EXACT)。
复选框 (Checkbox)是针对一个键的单个复选框。它会找到值为 1(真/假字段)、另一个搜索值 (Search value)(如 yes)的产品,或者在搜索选项 (Search option)设为值存在 (Value exists)时,找到该字段已填写的所有产品。
如果保存的值本身包含逗号,请更改所有下拉菜单和多选下拉菜单列表的分隔符,然后用 | 重写这些列表:
/*
* HUSKY: separate meta filter options with | instead of a comma.
* Child theme functions.php or a code snippets plugin.
* Example list afterwards: Wood, oak|Wood, pine|Metal
*/
add_filter( 'woof_meta_options_separator', function ( $separator ) {
return '|';
} );
数字和范围字段适合使用滑块 (Slider);范围、步长和小数请参阅属性和元字段的范围滑块筛选器。
按 ACF 日期字段筛选
日期选择器筛选默认比较 Unix 时间戳,而 ACF 的日期选择器将日期保存为 20250131。钩子 woof_meta_use_acf_dateformat 会让筛选器在搜索之前把所选日期转换为相同的格式:
/*
* HUSKY: Datepicker meta filters search ACF Date Picker values (Ymd).
* Child theme functions.php or a code snippets plugin.
*/
add_filter( 'woof_meta_use_acf_dateformat', '__return_true' );
在元数据选项卡上添加 ACF 键,视图选择日期选择器 (Datepicker),类型保持为number:转换后的日期是按数字比较的,而date类型在这里无法得到可用的日期。该钩子对站点上的每个日期选择器筛选器都生效,因此之后它们都必须指向 ACF 日期选择器字段。对于有效期(起/止),请把开始字段和结束字段添加为两个独立的筛选器。
复选框和多选字段:两种解决办法
推荐:把值移到分类法中
每个产品有多个值的数据,正是分类法的用武之地。使用分类法,您可以为每个值得到一个复选框、计数、所选值之间的 AND 或 OR 逻辑,以及对涡轮模式的支持,这些都是元字段无法提供的。您不必放弃使用 ACF 进行编辑:
- 创建一个产品分类法,例如设备 (Equipment),可以是自定义分类法,也可以是产品 → 属性 (Products → Attributes)下的全局属性。
- 在 ACF 中,用指向它的分类法 (Taxonomy)字段替换复选框字段,并开启保存术语 (Save Terms)和加载术语 (Load Terms)。这样 ACF 会把所选术语分配给产品,而不是保存一个数组。
- 产品在重新保存时会获得它们的术语;对于大型商品目录,请批量操作。之后该分类法会像其他分类法一样出现在 HUSKY 的结构 (Structure)选项卡上。
保留字段:在已保存的数组中搜索
如果字段必须保持原样,可以更改比较方式。下面的代码片段会把 HUSKY 对所列键的“等于”条件,变成对带引号值的 LIKE 搜索,于是 ac 变成 LIKE '%"ac"%',能够匹配序列化字符串内部的元素,但不会匹配 ac_rear。它同时也修正了选项的计数。
/*
* HUSKY: Drop-down / Multi Drop-down meta filters for ACF Checkbox
* and Select Multiple fields (values stored as serialized arrays).
* Child theme functions.php or a code snippets plugin.
*/
function my_husky_serialized_keys() {
return array( 'equipment' ); // ACF field names
}
function my_husky_match_serialized( $meta_query ) {
if ( ! is_array( $meta_query ) ) {
return $meta_query;
}
foreach ( $meta_query as $i => $clause ) {
if ( ! is_array( $clause ) ) {
continue;
}
if ( isset( $clause['key'], $clause['value'], $clause['compare'] )
&& '=' === $clause['compare']
&& is_scalar( $clause['value'] )
&& in_array( $clause['key'], my_husky_serialized_keys(), true ) ) {
$meta_query[ $i ]['compare'] = 'LIKE';
$meta_query[ $i ]['value'] = '"' . $clause['value'] . '"';
$meta_query[ $i ]['type'] = 'CHAR';
} else {
$meta_query[ $i ] = my_husky_match_serialized( $clause );
}
}
return $meta_query;
}
// Products found by the filter
add_filter( 'woof_get_meta_query', 'my_husky_match_serialized', 100 );
// Counts next to the options (Show count + Dynamic recount)
add_filter( 'woof_dynamic_count_attr', function ( $args ) {
if ( isset( $args['meta_query'] ) ) {
$args['meta_query'] = my_husky_match_serialized( $args['meta_query'] );
}
return $args;
}, 100 );
然后在元数据选项卡上将 equipment 添加为下拉菜单 (Drop-down)或多选下拉菜单 (Multi Drop-down),类型为string,并在 ^ 后填写 ACF 选项值,例如 Air conditioning^ac,Heated seats^heated_seats。请了解其局限:多选下拉菜单找到的是拥有所选值中任意一个的产品,而不是全部;LIKE '%…%' 搜索无法使用数据库索引,在大型商品目录上会变慢;并且该代码片段在涡轮模式下不生效。有关该钩子的更多信息,请见 woof_get_meta_query 页面。
变体、涡轮模式和自定义产品网格
- 变体上的值不会被搜索。商店查询返回的是父产品,并检查父产品自身的元数据。属性对变体有效,是因为父产品带有其所有变体的术语;元数据值则不是这样。请把值放在父产品上。
- 涡轮模式在浏览器中根据自己的数据文件进行筛选,该文件只包含在元数据选项卡上添加的键。通过 ACF 扩展显示的字段,以及上面代码片段这样的 PHP 钩子,在其中都不会被使用。参见涡轮模式故障排除。
- URL 变了,但仍显示所有产品。这时问题并不出在字段上:页面构建器的网格或自定义模板运行着自己的查询,并忽略所有筛选。解决办法见筛选器 URL 改变但产品未被筛选。
如果 ACF 筛选器仍然找不到产品
- 检查实际保存的内容。在 phpMyAdmin 或类似工具中,使用产品 ID(以及您的表前缀)运行
SELECT meta_key, meta_value FROM wp_postmeta WHERE post_id = 123。以a:开头的值是序列化数组;如果键与您预期的不同,说明 ACF 以另一个名称保存。 - 元数据选项卡:键不带开头的下划线,大小写一致;文本使用string类型;
^后面是保存的选项值。 - 对于 ACF 扩展:字段组的位置为文章类型等于产品 (Post Type is equal to Product),选项值与标签一致,选择多个 (Select Multiple)已关闭,并且更改之后产品已重新保存。
- 值在父产品上,而不是在变体上。
- 同一页面上的分类法筛选器可以正常工作。如果不能,请先修复产品网格。
如果所有要点都已核对而筛选器仍找不到任何内容,请到 HUSKY 支持论坛发起一个主题,附上字段的类型和设置、元数据键以及保存值的示例,我们会进行查看。