QueryControls — это компонент из библиотеки @wordpress/components, который предоставляет пользовательский интерфейс для управления параметрами выборки записей, такими как категории, авторы, количество элементов, порядок и способ сортировки. Этот компонент полезен для настройки запросов в редакторе Gutenberg, позволяя разработчикам создавать фильтры и условия для выборок данных.
Основы использования QueryControls
В этом разделе создадим базовый компонент, который использует QueryControls для настройки параметров запроса.
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={maxItems}
minItems={minItems}
numberOfItems={numberOfItems}
order={order}
orderBy={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 })}
/>
);
};
Пример с несколькими категориями
С версии, поддерживающей множественный выбор категорий, вы можете использовать QueryControls для выбора нескольких категорий. В этом примере будет использоваться массив selectedCategories и объект categorySuggestions, что позволяет выбрать несколько категорий сразу.
const QUERY_DEFAULTS = {
orderBy: 'title',
order: 'asc',
selectedCategories: [
{ id: 1, name: 'Category 1', parent: 0 },
{ id: 2, name: '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 MyQueryControlsMultiple = () => {
const [query, setQuery] = useState(QUERY_DEFAULTS);
const { orderBy, order, selectedCategories, categories, numberOfItems } = query;
const updateQuery = (newQuery) => {
setQuery({ ...query, ...newQuery });
};
return (
<QueryControls
orderBy={orderBy}
order={order}
numberOfItems={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 })}
/>
);
};
Описание параметров компонента QueryControls
QueryControls принимает следующие параметры:
- authorList:
Author[]
Список авторов для выбора.
Обязательный: Нет. - categoriesList:
Category[]
Список категорий, отображаемых в режиме одиночного выбора категории.
Обязательный: Нет. - categorySuggestions:
Record<Category['name'], Category>
Объект, где ключ — имя категории, используется для отображения категорий при множественном выборе.
Обязательный: Нет. - maxItems:
number
Максимальное количество элементов для выборки.
Обязательный: Нет.
По умолчанию: 100. - minItems:
number
Минимальное количество элементов для выборки.
Обязательный: Нет.
По умолчанию: 1. - numberOfItems:
number
Количество элементов для отображения.
Обязательный: Нет. - onAuthorChange:
(newAuthor: string) => void
Функция, вызываемая при изменении автора.
Обязательный: Нет. - onCategoryChange:
(newCategory: string) => void | FormTokenFieldProps['onChange']
Функция, вызываемая при изменении категории.
Обязательный: Нет. - onNumberOfItemsChange:
(newNumber?: number) => void
Функция, вызываемая при изменении количества элементов.
Обязательный: Нет. - onOrderChange:
(newOrder: 'asc' | 'desc') => void
Функция, вызываемая при изменении порядка.
Обязательный: Нет. - onOrderByChange:
(newOrderBy: 'date' | 'title') => void
Функция, вызываемая при изменении параметра сортировки.
Обязательный: Нет. - order:
'asc' | 'desc'
Определяет порядок выборки элементов: по возрастанию или убыванию.
Обязательный: Нет. - orderBy:
'date' | 'title'
Определяет параметр, по которому будет осуществляться сортировка.
Обязательный: Нет. - selectedAuthorId:
number
ID выбранного автора.
Обязательный: Нет. - selectedCategories:
Category[]
Список выбранных категорий при множественном выборе.
Обязательный: Нет. - selectedCategoryId:
number
ID выбранной категории при одиночном выборе.
Обязательный: Нет. - __next40pxDefaultSize:
boolean
Включает увеличение высоты, которое станет стандартным в будущих версиях.
Обязательный: Нет.
По умолчанию: false.
Заключение
Компонент QueryControls в WordPress предоставляет удобный и гибкий интерфейс для управления параметрами запроса. Он позволяет создавать сложные фильтры и настраивать параметры выборки, а также поддерживает расширенные возможности, такие как множественный выбор категорий и сортировка по нескольким критериям.