QueryControls 是 WordPress 组件库中的一个 React 组件，用于构建查询控制界面，支持排序、分类选择、项目数量设置等功能。文档提供了使用指南、代码示例和属性说明，帮助开发者快速集成和自定义查询控件。
import { useState } from 'react';
import { QueryControls } from '@wordpress/components';
const QUERY_DEFAULTS = {
category: 1,
categories: [
{
id: 1,
name: 'Category 1',
parent: 0,
},
{
id: 2,
name: 'Category 1b',
parent: 1,
},
{
id: 3,
name: 'Category 2',
parent: 0,
},
],
maxItems: 20,
minItems: 1,
numberOfItems: 10,
order: 'asc',
orderBy: 'title',
};
const MyQueryControls = () => {
const [ query, setQuery ] = useState( QUERY_DEFAULTS );
const { category, categories, maxItems, minItems, numberOfItems, order, orderBy } = query;
const updateQuery = ( newQuery ) => {
setQuery( { ...query, ...newQuery } );
};
return (
<QueryControls
{ ...{ maxItems, minItems, numberOfItems, order, orderBy } }
onOrderByChange={ ( newOrderBy ) => updateQuery( { orderBy: newOrderBy } ) }
onOrderChange={ ( newOrder ) => updateQuery( { order: newOrder } ) }
categoriesList={ categories }
selectedCategoryId={ category }
onCategoryChange={ ( newCategory ) => updateQuery( { category: newCategory } ) }
onNumberOfItemsChange={ ( newNumberOfItems ) =>
updateQuery( { numberOfItems: newNumberOfItems } )
}
/>
);
};import { useState } from 'react';
import { QueryControls } from '@wordpress/components';
const QUERY_DEFAULTS = {
category: 1,
categories: [
{
id: 1,
name: 'Category 1',
parent: 0,
},
{
id: 2,
name: 'Category 1b',
parent: 1,
},
{
id: 3,
name: 'Category 2',
parent: 0,
},
],
maxItems: 20,
minItems: 1,
numberOfItems: 10,
order: 'asc',
orderBy: 'title',
};
const MyQueryControls = () => {
const [ query, setQuery ] = useState( QUERY_DEFAULTS );
const { category, categories, maxItems, minItems, numberOfItems, order, orderBy } = query;
const updateQuery = ( newQuery ) => {
setQuery( { ...query, ...newQuery } );
};
return (
<QueryControls
{ ...{ maxItems, minItems, numberOfItems, order, orderBy } }
onOrderByChange={ ( newOrderBy ) => updateQuery( { orderBy: newOrderBy } ) }
onOrderChange={ ( newOrder ) => updateQuery( { order: newOrder } ) }
categoriesList={ categories }
selectedCategoryId={ category }
onCategoryChange={ ( newCategory ) => updateQuery( { category: newCategory } ) }
onNumberOfItemsChange={ ( newNumberOfItems ) =>
updateQuery( { numberOfItems: newNumberOfItems } )
}
/>
);
};
The QueryControls component now supports multiple category selection, to replace the single category selection available so far. To enable it use the component with the new props instead: categorySuggestions in place of categoriesList and the selectedCategories array instead of selectedCategoryId like so:
const QUERY_DEFAULTS = {
orderBy: 'title',
order: 'asc',
selectedCategories: [
{
id: 1,
value: 'Category 1',
parent: 0,
},
{
id: 2,
value: 'Category 1b',
parent: 1,
},
],
categories: {
'Category 1': {
id: 1,
name: 'Category 1',
parent: 0,
},
'Category 1b': {
id: 2,
name: 'Category 1b',
parent: 1,
},
'Category 2': {
id: 3,
name: 'Category 2',
parent: 0,
},
},
numberOfItems: 10,
};
const MyQueryControls = () => {
const [ query, setQuery ] = useState( QUERY_DEFAULTS );
const { orderBy, order, selectedCategories, categories, numberOfItems } = query;
const updateQuery = ( newQuery ) => {
setQuery( { ...query, ...newQuery } );
};
return (
<QueryControls
{ ...{ orderBy, order, numberOfItems } }
onOrderByChange={ ( newOrderBy ) => updateQuery( { orderBy: newOrderBy } ) }
onOrderChange={ ( newOrder ) => updateQuery( { order: newOrder } ) }
categorySuggestions={ categories }
selectedCategories={ selectedCategories }
onCategoryChange={ ( category ) => updateQuery( { selectedCategories: category } ) }
onNumberOfItemsChange={ ( newNumberOfItems ) =>
updateQuery( { numberOfItems: newNumberOfItems } )
}
/>
);
};
The format of the categories list also needs to be updated to match the expected type for the category suggestions.
authorList: Author[]An array of the authors to select from.
categoriesList: Category[]An array of categories. When passed in conjunction with the onCategoryChange prop, it causes the component to render UI that allows selecting one category at a time.
categorySuggestions: Record< Category[ 'name' ], Category >An object of categories with the category name as the key. When passed in conjunction with the onCategoryChange prop, it causes the component to render UI that enables multiple selection.
maxItems: numberThe maximum number of items.
minItems: numberThe minimum number of items.
numberOfItems: numberThe selected number of items to retrieve via the query.
onAuthorChange: ( newAuthor: string ) => voidA function that receives the new author value. If not specified, the author controls are not rendered.
onCategoryChange: ( newCategory: string ) => void | FormTokenFieldProps[ 'onChange' ]A function that receives the new category value. If not specified, the category controls are not rendered.
The function’s signature changes depending on whether multiple category selection is enabled or not.
onNumberOfItemsChange: ( newNumber?: number ) => voidA function that receives the new number of items. If not specified, then the number of items range control is not rendered.
onOrderChange: ( newOrder: 'asc' | 'desc' ) => voidA function that receives the new order value. If this prop or the onOrderByChange prop are not specified, then the order controls are not rendered.
onOrderByChange: ( newOrderBy: 'date' | 'title' ) => voidA function that receives the new orderby value. If this prop or the onOrderChange prop are not specified, then the order controls are not rendered.
order: 'asc' | 'desc'The order in which to retrieve posts.
orderBy: 'date' | 'title' | 'menu_order'The meta key by which to order posts.
orderByOptions: OrderByOption[]The meta key by which to order posts.
selectedAuthorId: numberThe selected author ID.
selectedCategories: Category[]The selected categories for the categorySuggestions prop.
selectedCategoryId: numberThe selected category for the categoriesList prop.
__next40pxDefaultSize: booleanStart opting into the larger default height that will become the default size in a future version.
false