Feature: #101507 - Hotkey API¶

Description¶

TYPO3 provides the @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 (Ctrl, Meta, Alt, and Shift), and also a public property describing the common hotkey modifier based on the user's operating system: Cmd (Meta) on macOS, Ctrl on anything else. Using any modifier is optional, but highly recommended.

A hotkey is registered with the register() method. The method takes three arguments:

• hotkey - An array defining the keys that must be pressed
• handler - A callback that is executed when the hotkey is invoked

• options - Object that configured a hotkey's behavior.

  • scope - The scope a hotkey is registered in
  • allowOnEditables - If false (default), handlers are not executed when an editable element is focussed
  • allowRepeat - If false (default), handlers are not executed when the hotkey is pressed for a long time
  • bindElement - If given, an aria-keyshortcuts attribute is added to the element. This is recommended for accessibility reasons.

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');

Impact¶

If properly used, common functionality is easier to access with hotkeys. The following hotkeys are configured within TYPO3:

• Ctrl/Cmd + K - open LiveSearch
• Ctrl/Cmd + S - save current document opened in FormEngine