Компонент KeyboardShortcuts в WordPress используется для отслеживания и обработки сочетаний клавиш в пределах области, где он был отрендерен. Этот компонент реализует библиотека Mousetrap и позволяет удобно добавлять функциональные клавиатурные сочетания в ваши WordPress-приложения. Рассмотрим детально все параметры KeyboardShortcuts и приведем уникальные примеры его использования.
Основные Возможности
При добавлении детей (children) компонент отслеживает события клавиш только в пределах этих элементов. Если дети не переданы, он будет отслеживать события по всему документу. KeyboardShortcuts идеально подходит для создания интерактивного интерфейса с поддержкой удобных и интуитивно понятных сочетаний клавиш.
Импорт компонента KeyboardShortcuts
import { KeyboardShortcuts } from '@wordpress/components';
import { useState } from 'react';
Пример базового использования KeyboardShortcuts
Создадим пример, в котором при нажатии комбинации клавиш будет выполнено конкретное действие.
const BasicShortcutsExample = () => {
const [text, setText] = useState('Нажмите Ctrl+K, чтобы изменить текст.');
const handleShortcut = () => {
setText('Вы использовали сочетание клавиш Ctrl+K!');
};
return (
<div>
<KeyboardShortcuts
shortcuts={ {
'mod+k': handleShortcut,
} }
/>
<p>{ text }</p>
</div>
);
};
В этом примере сочетание клавиш Ctrl+K (на Windows) или Cmd+K (на Mac) изменяет текст. Это возможно благодаря свойству shortcuts, которое связывает комбинацию клавиш с функцией-обработчиком.
Параметры компонента KeyboardShortcuts
Рассмотрим доступные параметры KeyboardShortcuts и их настройки.
- children
Дочерние элементы, в которых будут отслеживаться события нажатия клавиш. Если этот параметр не задан, отслеживание событий будет происходить на уровне документа.- Тип:
ReactNode - Обязательный: Нет
- Тип:
<KeyboardShortcuts shortcuts={ { 'mod+s': saveDocument } }>
<div>Нажмите Cmd+S или Ctrl+S, чтобы сохранить документ</div>
</KeyboardShortcuts>
- shortcuts
Объект, содержащий комбинации клавиш в качестве ключей и функции-обработчики в качестве значений. Эти функции будут вызываться при нажатии соответствующих клавиш. Важно: Используйте неизменяемую ссылку на функцию, а не анонимные функции, чтобы гарантировать корректное удаление привязок при размонтировании компонента.- Тип:
Object - Обязательный: Да
- Тип:
const MyComponent = () => {
const [isShortcutTriggered, setIsShortcutTriggered] = useState(false);
const toggleShortcut = () => setIsShortcutTriggered((prev) => !prev);
return (
<div>
<KeyboardShortcuts
shortcuts={ {
'alt+c': toggleShortcut,
} }
/>
{isShortcutTriggered ? 'Комбинация Alt+C сработала!' : 'Нажмите Alt+C'}
</div>
);
};
- bindGlobal
Определяет, будет ли обработчик срабатывать при нажатии клавиш в редактируемых полях (например,inputилиtextarea). ЕслиbindGlobalустановлен вtrue, события клавиш будут отслеживаться глобально, включая такие поля.- Тип:
Boolean - Обязательный: Нет
- Значение по умолчанию:
false
- Тип:
const GlobalShortcutExample = () => {
const [message, setMessage] = useState('Введите текст и нажмите Shift+Enter.');
const handleGlobalShortcut = () => {
setMessage('Сочетание Shift+Enter сработало даже в текстовом поле!');
};
return (
<div>
<KeyboardShortcuts
shortcuts={ { 'shift+enter': handleGlobalShortcut } }
bindGlobal={true}
/>
<textarea placeholder="Пробуйте использовать сочетание Shift+Enter" />
<p>{message}</p>
</div>
);
};
- eventName
Определяет, какое событие будет использоваться для вызова функции-обработчика. По умолчанию это событиеkeydown, но его можно изменить на другие, например,keyupилиkeypress, в зависимости от требований вашего приложения.- Тип:
String - Обязательный: Нет
- Значение по умолчанию:
keydown
- Тип:
const KeyupShortcutExample = () => {
const [info, setInfo] = useState('Нажмите Esc, чтобы сбросить текст.');
const handleKeyUp = () => {
setInfo('Сочетание клавиш Esc было нажато!');
};
return (
<div>
<KeyboardShortcuts
shortcuts={ { 'esc': handleKeyUp } }
eventName="keyup"
/>
<p>{info}</p>
</div>
);
};
Пример 1: Управление несколькими сочетаниями клавиш
Этот пример демонстрирует, как обрабатывать несколько комбинаций клавиш одновременно.
const MultiShortcutExample = () => {
const [message, setMessage] = useState('Попробуйте различные сочетания клавиш: Ctrl+B или Ctrl+I.');
const handleBoldShortcut = () => setMessage('Вы выбрали жирный текст с Ctrl+B');
const handleItalicShortcut = () => setMessage('Вы выбрали курсив с Ctrl+I');
return (
<div>
<KeyboardShortcuts
shortcuts={ {
'mod+b': handleBoldShortcut,
'mod+i': handleItalicShortcut,
} }
/>
<p>{message}</p>
</div>
);
};
В этом примере Ctrl+B вызывает функцию для отображения текста о жирном шрифте, а Ctrl+I — о курсе.
Пример 2: Отслеживание сочетаний клавиш в определенном контейнере
Этот пример демонстрирует использование параметра children, чтобы отслеживать события клавиш только внутри определенного контейнера.
const ContainerShortcutExample = () => {
const [status, setStatus] = useState('Нажмите Alt+D в пределах этого контейнера.');
const handleShortcutInContainer = () => {
setStatus('Сочетание клавиш Alt+D было нажато внутри контейнера!');
};
return (
<KeyboardShortcuts
shortcuts={ { 'alt+d': handleShortcutInContainer } }
>
<div style={{ padding: '20px', border: '1px solid #ddd' }}>
{status}
</div>
</KeyboardShortcuts>
);
};
Тут сочетание клавиш Alt+D работает только в пределах div, а не по всему документу.
Заключение
Компонент KeyboardShortcuts предоставляет WordPress-разработчикам гибкие инструменты для создания более удобного и доступного пользовательского интерфейса с поддержкой сочетаний клавиш. С помощью параметров shortcuts, bindGlobal, eventName и children можно настроить функционал для разных ситуаций, будь то глобальная или локальная обработка клавиш.