TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:09 +02:00
commit af8cc155b5
6818 changed files with 642608 additions and 0 deletions
@@ -0,0 +1,77 @@
+.. 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