云策 WordPress 开发者社区

钩子文档

query_loop_block_query_vars

查看官方原文 ↗
💡 云策文档标注

概述

query_loop_block_query_vars 是一个 WordPress 过滤器，用于修改传递给 Query Loop Block 的 WP_Query 参数。它允许开发者扩展 Query Loop Block 的功能，例如添加自定义设置或元查询，但仅影响前端渲染，不影响编辑器预览。

关键要点

  • 过滤器用于调整 Query Loop Block 的 WP_Query 参数，需与 WP_Query API 兼容。
  • 仅影响前端查询渲染，编辑器预览不受影响，因为预览使用 REST API。
  • 参数包括 $query（WP_Query 参数数组）、$block（WP_Block 实例）和 $page（当前查询页码）。
  • 可用于实现自定义排序、元查询等高级功能，如基于自定义字段排序或排除过期事件。

代码示例

add_filter( 'query_loop_block_query_vars', 'wpdocs_filter_query' );
function wpdocs_filter_query( $query ) {
    if ( 'wpdocs_event' !== $query['post_type'] ) {
        return $query;
    }
    $query['meta_key'] = 'eventDate';
    $query['meta_value'] = date( 'Y-m-d' );
    $query['meta_compare'] = '>=';
    if ( 'date' === $query['orderby'] ) {
        $query['orderby'] = 'meta_value';
    }
    return $query;
}

注意事项

  • 过滤器修改的参数应同时兼容 REST API，以确保前后端查询一致。
  • 编辑器预览基于 REST API，因此过滤器不会改变预览效果。
📄 原文内容

Filters the arguments which will be passed to WP_Query for the Query Loop Block.

Description

Anything to this filter should be compatible with the WP_Query API to form the query context which will be passed down to the Query Loop Block’s children.
This can help, for example, to include additional settings or meta queries not directly supported by the core Query Loop Block, and extend its capabilities.

Please note that this will only influence the query that will be rendered on the front-end. The editor preview is not affected by this filter. Also, worth noting that the editor preview uses the REST API, so, ideally, one should aim to provide attributes which are also compatible with the REST API, in order to be able to implement identical queries on both sides.

Parameters

$queryarray
Array containing parameters for WP_Query as parsed by the block context.
$blockWP_Block
Block instance.
$pageint
Current query’s page.

Source

return apply_filters( 'query_loop_block_query_vars', $query, $block, $page );

View all references View on Trac View on GitHub

Used by Description
build_query_vars_from_query_block()wp-includes/blocks.php

Helper function that constructs a WP_Query args array from a Query block properties.

Changelog

Version Description
6.1.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    nicktrosnant


    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

    Here is an example of handing a custom post type which holds an event date field in metadata and where I wanted the Query Loop to display posts sorted by the event date rather than the post date. I also wanted to exclude dates in the past.

    add_filter( 'query_loop_block_query_vars', 'wpdocs_filter_query' );
function wpdocs_filter_query( $query ) {
    // ignore if the query block is not using this post type
    if ( 'wpdocs_event' !== $query['post_type'] ) {
        return $query;
    }

    // always exclude events with dates in the past
    $query['meta_key'] = 'eventDate';
    $query['meta_value'] = date( 'Y-m-d' );
    $query['meta_compare'] = '>=';

    // If date order was chosen in the block settings, change to use the Event date instead of Post date
    if ( 'date' === $query['orderby'] ) {
        $query['orderby'] = 'meta_value';
    }

    return $query;
}

  2. Skip to note 4 content


    WebMan Design | Oliver Juhas


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Example of modifying the query based on the class name set on the Post Template block:

    function wpdocs_randomize_query( $query, $block ) {

	$block = $block->parsed_block;

	if (
		isset( $block['attrs']['className'] )
		&& false !== strpos( $block['attrs']['className'], 'randomize-content' )
	) {
		$query['orderby'] = 'rand';
	}

	return $query;
}

add_filter( 'query_loop_block_query_vars', 'wpdocs_randomize_query', 10, 2 );