Bricks 前端按日期选择器字段过滤文章（URL 状态同步）

本文为付费教程的骨架翻译：场景与步骤按原文梳理，锁定部分的代码按 Bricks 官方钩子补全实现，并已注明「补全实现」。未复制原文代码。

场景：按日期范围筛活动

事件、课程、排期类站点的常见需求：让访客在前端按「活动日期」筛选文章——选一个具体日期，或选一个起止范围，列表实时更新。数据基础是每个活动（Events CPT）上挂一个日期类型自定义字段（如 ACF 的 Date Picker）。

付费原文同时要求支持浏览器前进/后退按钮，即筛选状态要同步到 URL，页面刷新、分享链接后筛选条件不丢。

Step 1：准备 CPT 与日期字段

1. 用 ACF（或其他自定义字段插件）创建 Events CPT 和对应的活动日期字段（Event Date）。
2. 关键设置：字段的 Return Format 选 Ymd（如 20250713）。存成这种紧凑格式，后续字符串比较、meta_query 范围查询都简单可靠。
3. 添加若干活动文章并填充日期字段。

可选：在 CPT 设置里启用归档（Archive），归档 slug 设为 events，这样查询循环直接挂在归档模板上；用普通页面也可以，只是要自己配一个自定义查询。

Step 2：URL 参数规范

原文约定的参数（也是前端和 PHP 之间的契约）：

• ?from=2025-07-13 —— 起始日期筛选
• ?to=2025-08-15 —— 截止日期筛选
• ?date=2025-07-20 —— 精确日期筛选
• ?from=2025-07-13&to=2025-08-15 —— 日期范围筛选

前端日期选择器改变时，通过 history.pushState 更新 URL 并触发列表刷新；页面加载时从 URL 读取参数回填筛选器。这样前进/后退按钮天然可用，条件也藏在链接里可分享。

Step 3：查询与前端联动（补全实现）

付费原文锁定，这里按官方钩子补全。PHP 侧用 bricks/query/run 拦截查询，依据 URL 参数注入 meta_query：

// 补全实现：按 URL 日期参数过滤 Bricks 查询
add_filter( 'bricks/query/run', function( $query, $settings, $element_id ) {
    // 限定只作用于 Events 查询（按你的 query 类型/元素调整）
    if ( empty( $query['post_type'] ) || ! in_array( 'events', (array) $query['post_type'] ) ) {
        return $query;
    }

    $meta_query = [];

    if ( ! empty( $_GET['date'] ) ) {
        $date = sanitize_text_field( $_GET['date'] ); // 2025-07-20
        $meta_query[] = [
            'key'     => 'event_date',
            'value'   => str_replace( '-', '', $date ),
            'compare' => '=',
        ];
    } elseif ( ! empty( $_GET['from'] ) || ! empty( $_GET['to'] ) ) {
        $from = ! empty( $_GET['from'] ) ? str_replace( '-', '', sanitize_text_field( $_GET['from'] ) ) : '';
        $to   = ! empty( $_GET['to'] )   ? str_replace( '-', '', sanitize_text_field( $_GET['to'] ) )   : '';

        $range = [ 'key' => 'event_date' ];
        if ( $from ) { $range['value'] = $from; $range['compare'] = '>='; }
        if ( $to )   { $range['value'] = $to;   $range['compare'] = '<='; }
        $meta_query[] = $range;
    }

    if ( $meta_query ) {
        $query['meta_query'] = array_merge( (array) ( $query['meta_query'] ?? [] ), $meta_query );
    }

    return $query;
}, 10, 3 );

前端侧（页面自定义代码或 Code 元素）绑定日期选择器的 change 事件：写 URL 参数 → history.pushState → 重新触发筛选（Bricks 自带 Filter 交互可配合，或直接刷新查询区）。加载时反向解析参数回填选择器。存储格式统一用 Ymd，所以参数里的 - 在比较前去掉即可对齐。

原理说明

• Ymd 存储格式让日期变成可字典序比较的字符串，meta_query 的 >= / <= 直接按字符串比大小，无需时间戳换算。
• bricks/query/run 是官方提供的查询参数过滤器，返回数组会合并进该元素的最终 WP_Query 参数，是注入 meta 条件的最正入口。
• URL 状态同步（pushState + popstate）是让前进/后退可用的关键，也顺带获得可分享、可收藏的筛选链接。
• 只对目标 post type 生效的守卫条件很重要，避免影响页面里其他查询循环。

小结

「前端日期筛选 + URL 状态」是一套完整交互：字段存 Ymd、PHP 用 bricks/query/run 注入 meta_query、JS 用 pushState 同步状态。锁定部分按官方钩子补全实现，字段名、参数名、post type 请按你的站点替换。

小结：日期筛选的关键是存储格式（Ymd）与 URL 参数契约；查询注入走 bricks/query/run，状态同步走 pushState。这套骨架可直接落地，前端 JS 按需补全。