Feature: #101507 - Hotkey API

See forge#101507

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

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:

  • Ctrl/Cmd + K - open LiveSearch

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