QueryControls

目录

Development Guidelines

Usage

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 } )
            }
        />
    );
};

Multiple category selector

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.

Props

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: number

The maximum number of items.

minItems: number

The minimum number of items.

numberOfItems: number

The selected number of items to retrieve via the query.

onAuthorChange: ( newAuthor: string ) => void

A 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 ) => void

A 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' ) => void

A 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' ) => void

A 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: number

The selected author ID.

selectedCategories: Category[]

The selected categories for the categorySuggestions prop.

selectedCategoryId: number

The selected category for the categoriesList prop.

版本号 #2
由 壳壳虫 创建于 2026-10-31 18:14:19 UTC
由 壳壳虫 更新于 2026-10-31 18:14:20 UTC