Bricks 中文文档：bricks/helpers/get_posts_args

{
  "name": "bricks/helpers/get_posts_args",
  "kind": "filter",
  "url": "https://academy.bricksbuilder.io/developer/hooks/filters/bricks-helpers-get_posts_args/",
  "scraped_at": "2026-08-29",
  "hook_name": "bricks/helpers/get_posts_args",
  "description": {
    "en": "The bricks/helpers/get_posts_args filter allows you to modify the query arguments used when Bricks retrieves posts in the builder via AJAX . This includes scenarios such as: This hook gives you full control over the underlying WP_Query arguments before the query is executed. When WordPress queries with post_type set to any , the results may include attachments. This example excludes media items unless the caller explicitly requests the attachment post type.",
    "zh": "筛选 Bricks 中可用的多语言（Multilingual）选项。"
  },
  "parameters": [
    {
      "name": "query_args",
      "type": "array",
      "type_zh": null,
      "description": {
        "en": "Array of arguments passed to get_posts() .",
        "zh": "传递给 get_posts() 的参数数组。"
      }
    }
  ],
  "example_usage": "add_filter( 'bricks/helpers/get_posts_args', function( $query_args ) {\n    // If no post type is provided, treat it as \"any\" for safety.\n    $post_type_arg = $query_args['post_type'] ?? 'any';\n\n\n    // Detect whether the caller explicitly requested the attachment post type.\n    $has_attachment = false;\n\n\n    if ( is_array( $post_type_arg ) ) {\n        $has_attachment = in_array( 'attachment', $post_type_arg, true );\n    } else {\n        $has_attachment = ( $post_type_arg === 'attachment' );\n    }\n\n\n    // If attachment was explicitly requested, do nothing.\n    if ( $has_attachment ) {\n        return $query_args;\n    }\n\n\n    // Get all public post types once. We only use this when expanding \"any\".\n    $public_post_types = array_values(\n        array_diff(\n            get_post_types( [ 'public' => true ], 'names' ),\n            [ 'attachment' ]\n        )\n    );\n\n\n    // CASE 1: post_type = 'any'\n    if ( $post_type_arg === 'any' ) {\n        $query_args['post_type'] = $public_post_types;\n    }\n\n\n    // CASE 2: post_type is an array\n    elseif ( is_array( $post_type_arg ) ) {\n        $normalized_post_types = array_diff( $post_type_arg, [ 'attachment' ] );\n\n\n        // Defensive handling: if \"any\" exists in the array, replace it with\n        // all public post types except attachment.\n        if ( in_array( 'any', $normalized_post_types, true ) ) {\n            $normalized_post_types = array_diff( $normalized_post_types, [ 'any' ] );\n            $normalized_post_types = array_merge( $normalized_post_types, $public_post_types );\n        }\n\n\n        $query_args['post_type'] = array_values( array_unique( $normalized_post_types ) );\n    }\n\n\n    return $query_args;\n} );"
}

前言

筛选 Bricks 中可用的多语言（Multilingual）选项。

用法

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

add_filter( 'bricks/helpers/get_posts_args', function( $query_args ) {
    // If no post type is provided, treat it as "any" for safety.
    $post_type_arg = $query_args['post_type'] ?? 'any';


    // Detect whether the caller explicitly requested the attachment post type.
    $has_attachment = false;


    if ( is_array( $post_type_arg ) ) {
        $has_attachment = in_array( 'attachment', $post_type_arg, true );
    } else {
        $has_attachment = ( $post_type_arg === 'attachment' );
    }


    // If attachment was explicitly requested, do nothing.
    if ( $has_attachment ) {
        return $query_args;
    }


    // Get all public post types once. We only use this when expanding "any".
    $public_post_types = array_values(
        array_diff(
            get_post_types( [ 'public' => true ], 'names' ),
            [ 'attachment' ]
        )
    );


    // CASE 1: post_type = 'any'
    if ( $post_type_arg === 'any' ) {
        $query_args['post_type'] = $public_post_types;
    }


    // CASE 2: post_type is an array
    elseif ( is_array( $post_type_arg ) ) {
        $normalized_post_types = array_diff( $post_type_arg, [ 'attachment' ] );


        // Defensive handling: if "any" exists in the array, replace it with
        // all public post types except attachment.
        if ( in_array( 'any', $normalized_post_types, true ) ) {
            $normalized_post_types = array_diff( $normalized_post_types, [ 'any' ] );
            $normalized_post_types = array_merge( $normalized_post_types, $public_post_types );
        }


        $query_args['post_type'] = array_values( array_unique( $normalized_post_types ) );
    }


    return $query_args;
} );

参数

• $query_args (array)：传递给 get_posts() 的参数数组。

示例代码

筛选返回值

add_filter( 'bricks/helpers/get_posts_args', function( $query_args ) {
    // If no post type is provided, treat it as "any" for safety.
    $post_type_arg = $query_args['post_type'] ?? 'any';


    // Detect whether the caller explicitly requested the attachment post type.
    $has_attachment = false;


    if ( is_array( $post_type_arg ) ) {
        $has_attachment = in_array( 'attachment', $post_type_arg, true );
    } else {
        $has_attachment = ( $post_type_arg === 'attachment' );
    }


    // If attachment was explicitly requested, do nothing.
    if ( $has_attachment ) {
        return $query_args;
    }


    // Get all public post types once. We only use this when expanding "any".
    $public_post_types = array_values(
        array_diff(
            get_post_types( [ 'public' => true ], 'names' ),
            [ 'attachment' ]
        )
    );


    // CASE 1: post_type = 'any'
    if ( $post_type_arg === 'any' ) {
        $query_args['post_type'] = $public_post_types;
    }


    // CASE 2: post_type is an array
    elseif ( is_array( $post_type_arg ) ) {
        $normalized_post_types = array_diff( $post_type_arg, [ 'attachment' ] );


        // Defensive handling: if "any" exists in the array, replace it with
        // all public post types except attachment.
        if ( in_array( 'any', $normalized_post_types, true ) ) {
            $normalized_post_types = array_diff( $normalized_post_types, [ 'any' ] );
            $normalized_post_types = array_merge( $normalized_post_types, $public_post_types );
        }


        $query_args['post_type'] = array_values( array_unique( $normalized_post_types ) );
    }


    return $query_args;
} );

根据条件短路返回原值

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

add_filter( 'bricks/helpers/get_posts_args', function( $value, $query_args ) {
    if ( is_admin() ) { return $value; }
    // TODO: custom logic here
    return $value;
} );

补充说明

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