78 lines
2.6 KiB
ReStructuredText
78 lines
2.6 KiB
ReStructuredText
.. include:: /Includes.rst.txt
|
|
|
|
.. _feature-101507-1690808401:
|
|
|
|
=============================
|
|
Feature: #101507 - Hotkey API
|
|
=============================
|
|
|
|
See :issue:`101507`
|
|
|
|
Description
|
|
===========
|
|
|
|
TYPO3 provides the :js:`@typo3/backend/hotkeys.js` module that allows developers
|
|
to register custom keyboard shortcuts in the TYPO3 backend.
|
|
|
|
It is also possible and highly recommended to register hotkeys in a dedicated
|
|
scope to avoid conflicts with other hotkeys, perhaps registered by other
|
|
extensions.
|
|
|
|
The module provides an enum with common modifier keys (:kbd:`Ctrl`, :kbd:`Meta`,
|
|
:kbd:`Alt`, and :kbd:`Shift`), and also a public property describing the common
|
|
hotkey modifier based on the user's operating system: :kbd:`Cmd` (Meta) on macOS,
|
|
:kbd:`Ctrl` on anything else. Using any modifier is optional, but highly
|
|
recommended.
|
|
|
|
A hotkey is registered with the :js:`register()` method. The method takes three
|
|
arguments:
|
|
|
|
* :js:`hotkey` - An array defining the keys that must be pressed
|
|
* :js:`handler` - A callback that is executed when the hotkey is invoked
|
|
* :js:`options` - Object that configured a hotkey's behavior.
|
|
|
|
* :js:`scope` - The scope a hotkey is registered in
|
|
* :js:`allowOnEditables` - If :js:`false` (default), handlers are not executed when an editable element is focussed
|
|
* :js:`allowRepeat` - If :js:`false` (default), handlers are not executed when the hotkey is pressed for a long time
|
|
* :js:`bindElement` - If given, an `aria-keyshortcuts` attribute is added to the element. This is recommended for accessibility reasons.
|
|
|
|
.. code-block:: js
|
|
|
|
import Hotkeys, {ModifierKeys} from '@typo3/backend/hotkeys.js';
|
|
|
|
Hotkeys.register(
|
|
[Hotkeys.normalizedCtrlModifierKey, ModifierKeys.ALT, 'e'],
|
|
function (keyboardEvent) => {
|
|
console.log('Triggered on Ctrl/Cmd+Alt+E');
|
|
},
|
|
{
|
|
scope: 'my-extension/module',
|
|
bindElement: document.querySelector('.some-element')
|
|
}
|
|
);
|
|
|
|
// Get the currently active scope
|
|
const currentScope = Hotkeys.getScope();
|
|
|
|
// Make use of registered scope
|
|
Hotkeys.setScope('my-extension/module');
|
|
|
|
.. note::
|
|
|
|
TYPO3 specific hotkeys may be registered in the reserved `all` scope.
|
|
When invoking a hotkey from a different scope, the `all` scope is handled in
|
|
any case at first.
|
|
|
|
|
|
Impact
|
|
======
|
|
|
|
If properly used, common functionality is easier to access with hotkeys. The
|
|
following hotkeys are configured within TYPO3:
|
|
|
|
* :kbd:`Ctrl/Cmd` + :kbd:`K` - open LiveSearch
|
|
* :kbd:`Ctrl/Cmd` + :kbd:`S` - save current document opened in FormEngine
|
|
|
|
|
|
.. index:: Backend, JavaScript, ext:backend
|