13 · Estrutura e shell

Hotkey

atalho global de teclado · evento ou %JS{} · in_inputs

Atalho global de teclado que empurra um evento para a LiveView ou roda um %JS{}; o elemento fica oculto.

Atalho que empurra um evento para a LiveView

Aperte Alt + J (ou Alt + Shift + J) em qualquer lugar da página.

0 acionamentos
.heex
<%!-- on_press como nome de evento: chega em handle_event("hit", %{"key" => combinação}, socket) --%>
<.live_component module={LedgerShowcaseWeb.Demos.HotkeyDemo} id="hk-event" variant={:event} />

Atalho que roda um %JS{} (Alt+M)

Aperte Alt + M: o atalho roda um %JS no navegador, sem ida ao servidor.

.heex
<%!-- on_press como %JS{}: roda no navegador, sem ida ao servidor --%>
<.live_component module={LedgerShowcaseWeb.Demos.HotkeyDemo} id="hk-js" variant={:js} />

Também ao digitar (in_inputs)

Com in_inputs o atalho dispara também com o foco no campo. 0 salvamentos

.heex
<%!-- in_inputs: dispara também com o foco num campo --%>
<.live_component module={LedgerShowcaseWeb.Demos.HotkeyDemo} id="hk-inputs" variant={:inputs} />

Uso

<.hotkey id="save" keys="Mod+s" on_press="save" />

Regras

  • Mod é Cmd no macOS e Ctrl nos demais; os modificadores têm de bater exatamente (Mod+j não dispara com Mod+Shift+j).
  • Com o foco num campo, o atalho é ignorado, a não ser que use in_inputs.
  • A combinação que bate chama preventDefault: o atalho do navegador (Ctrl+J abre os downloads no Chrome) não roda.

Referência da API

Todos os function components, atributos, valores e slots que este componente cobre.

hotkey/1: a global keyboard shortcut that pushes an event to the LiveView or runs a %JS{}.

<.hotkey id="aw-hotkey" keys="Mod+j" on_press={JS.push("aw_toggle")} />
<.hotkey id="new-chat" keys="Mod+Shift+k, Alt+n" on_press="new_conversation" target={@myself} />
<.hotkey id="save" keys="Mod+s" on_press="save" in_inputs />

Renders a hidden element; the hook LedgerUI.Hotkey (priv/static/ledger_ui/hooks/hotkey.js) listens to keydown on the document and removes the listener when the element leaves the DOM.

keys is one or more combinations separated by commas. A combination is modifiers and a key joined by +: Mod, Ctrl, Cmd (or Meta), Alt, Shift, then the key (j, Enter, Escape, ArrowUp, /, Space...). Mod is Cmd on macOS and Ctrl elsewhere. The modifiers must match exactly (Mod+j does not fire on Mod+Shift+j).

A press while the focus is in an input, select, textarea or contenteditable element is ignored, unless in_inputs is set. A matching press calls preventDefault, so the browser's own shortcut (Ctrl+J opens the downloads in Chrome) does not run.

on_press is an event name, pushed with %{"key" => combination} (to target when given: a selector or a component id, as for phx-target), or a %JS{} run on the element (JS.push("evt", target: @myself) carries its own target).

<.hotkey>

Attr Type Default Values / notes
id (required) :string Needed by the hook.
keys (required) :string Combinations separated by commas, e.g. "Mod+j, Mod+Shift+k".
on_press (required) :any An event name or a %JS{}.
target :any nil phx-target of the event name (a selector or @myself).
in_inputs :boolean false Also fires while typing in a field.

Any other HTML/phx attribute goes to the root element.