Bricks 中文文档：bricks/query/prepare_query_vars_from_settings

标签TAGS:

2026年8月30日

📄 原始资料 | 展开查看原始 JSON（bricks-query-prepare_query_vars_from_settings.json）{ “name”: “bricks/query/prepare_query_vars_from_settings”, “kind”: “filter”, “url”: “https://academy.bricksbuilder.io/developer/hooks/filters/bricks-query-prepare_query_vars_from_settings/”, “scraped_at”: “2026-08-29…

📄 原始资料 | 展开查看原始 JSON（bricks-query-prepare_query_vars_from_settings.json）

{
  "name": "bricks/query/prepare_query_vars_from_settings",
  "kind": "filter",
  "url": "https://academy.bricksbuilder.io/developer/hooks/filters/bricks-query-prepare_query_vars_from_settings/",
  "scraped_at": "2026-08-29",
  "hook_name": "bricks/query/prepare_query_vars_from_settings",
  "description": {
    "en": "Filters the element settings before they are converted into query variables. This runs early in the query setup process, allowing you to modify the raw query settings of an element.",
    "zh": "在元素设置被转换为查询变量之前对其进行筛选。这在查询设置过程的早期运行，允许你修改元素的原始查询设置。"
  },
  "parameters": [
    {
      "name": "settings",
      "type": "array",
      "type_zh": null,
      "description": {
        "en": "The element settings array. The query settings are typically located in $settings['query'] .",
        "zh": "元素设置数组。查询设置通常位于 $settings['query']。"
      }
    },
    {
      "name": "element_id",
      "type": "string",
      "type_zh": null,
      "description": {
        "en": "The ID of the element being queried.",
        "zh": "正在被查询的元素 ID。"
      }
    }
  ],
  "example_usage": "add_filter( 'bricks/query/prepare_query_vars_from_settings', function( $settings, $element_id ) {\n    // Example: Force a specific post type for a query element with ID 'my_query_element'\n    if ( $element_id === 'my_query_element' ) {\n        $settings['query']['post_type'] = 'my_custom_post_type';\n    }\n\n\n    return $settings;\n}, 10, 2 );"
}

前言

在元素设置被转换为查询变量之前对其进行筛选。这在查询设置过程的早期运行，允许你修改元素的原始查询设置。

用法

将代码加入子主题的 functions.php：

add_filter( 'bricks/query/prepare_query_vars_from_settings', function( $settings, $element_id ) {
    // Example: Force a specific post type for a query element with ID 'my_query_element'
    if ( $element_id === 'my_query_element' ) {
        $settings['query']['post_type'] = 'my_custom_post_type';
    }


    return $settings;
}, 10, 2 );

参数

$settings (array)：元素设置数组。查询设置通常位于 $settings[‘query’]。
$element_id (string)：正在被查询的元素 ID。

示例代码

筛选返回值

add_filter( 'bricks/query/prepare_query_vars_from_settings', function( $settings, $element_id ) {
    // Example: Force a specific post type for a query element with ID 'my_query_element'
    if ( $element_id === 'my_query_element' ) {
        $settings['query']['post_type'] = 'my_custom_post_type';
    }


    return $settings;
}, 10, 2 );

根据条件短路返回原值

根据条件跳过或修改返回值：

add_filter( 'bricks/query/prepare_query_vars_from_settings', function( $value, $settings ) {
    if ( is_admin() ) { return $value; }
    // TODO: custom logic here
    return $value;
} );

补充说明

更多细节可参考官方文档。