HUSKY - WooCommerce Product Filter Professional

按 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 个产品”的反馈:

  1. 字段组必须按文章类型分配。HUSKY 只会读取位置 (Location)规则中包含文章类型等于产品 (Post Type is equal to Product)的字段组。仅通过产品分类之类规则显示的字段组会被跳过,因此它的字段永远不会出现在结构 (Structure)选项卡上。
  2. 每个选项的值必须与其标签一致。在 ACF 中,写成 xl : Extra large 的选项会在产品上保存 xl,但 ACF 扩展搜索的是标签 Extra large,因此什么也找不到。每行只写一个词的选项(值和标签相同),或者仅大小写不同的选项(如 red : Red)可以正常工作。包含引号字符的标签永远无法匹配。
  3. “选择多个”必须关闭。开启了选择多个 (Select Multiple)的下拉选择字段仍会被列出,但找不到任何产品,原因见下文。

如果某个字段违反了其中任何一条规则,请改用元数据选项卡来筛选,在那里您可以控制键和确切的值。

哪些 ACF 字段类型可以筛选

ACF 字段类型产品上保存的内容如何在 HUSKY 中筛选
下拉选择(单选)、单选按钮一个选项值ACF 扩展,或元数据的下拉菜单 (Drop-down) / 多选下拉菜单 (Multi Drop-down)
按钮组一个选项值元数据的下拉菜单 (Drop-down) / 多选下拉菜单 (Multi Drop-down)
真 / 假1 或 0ACF 扩展,或元数据的复选框 (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 字段

  1. 找到真实的元数据键。它是字段在 ACF 中的字段名称 (Field Name)(例如 body_type),而不是标签。在元数据 (Meta Data)选项卡上,通过产品 ID 获取任意产品的键 (Get keys from any product by its ID)会列出某个产品的所有键。每个 ACF 字段会出现两次:body_type 保存值,_body_type 保存 ACF 的内部字段引用。请使用不带下划线的键。键区分大小写,且从不包含空格或括号。
  2. 添加该键:使用手动添加自定义键 (Add Custom key by hands)或从列表中选择,输入标题,并选择视图和类型。对于文本值,请选择string。如果选择number,MySQL 会在比较之前把 Coupe 这样的文本转换为 0,筛选器就会返回所有带有该键的产品,看起来就像“筛选器没有任何作用”。
  3. 列出选项,适用于下拉菜单 (Drop-down)和多选下拉菜单 (Multi Drop-down)。元字段是自由文本,因此 HUSKY 无法自行生成值列表;需要由您书写,并用逗号分隔。当显示的标题与保存的值不同时,使用 title^value。对于 ACF 选项 coupe : Coupe 和 suv : SUV / Crossover,写法如下:
    Coupe^coupe,SUV / Crossover^suv
    ^ 后面的部分必须与 ACF 保存的内容完全一致,即选项值,而不是它的标签。
  4. 保存,打开结构 (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 进行编辑:

  1. 创建一个产品分类法,例如设备 (Equipment),可以是自定义分类法,也可以是产品 → 属性 (Products → Attributes)下的全局属性。
  2. 在 ACF 中,用指向它的分类法 (Taxonomy)字段替换复选框字段,并开启保存术语 (Save Terms)和加载术语 (Load Terms)。这样 ACF 会把所选术语分配给产品,而不是保存一个数组。
  3. 产品在重新保存时会获得它们的术语;对于大型商品目录,请批量操作。之后该分类法会像其他分类法一样出现在 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 支持论坛发起一个主题,附上字段的类型和设置、元数据键以及保存值的示例,我们会进行查看。