Realms

Versionsstand

Versionsstand: UIX 8.4.0. Frühere Beta-Versionshinweise kennzeichnen die Einführung einzelner Funktionen; diese sind in der stabilen Version enthalten.

Der realm einer Interaktion legt fest, wo Broker lauscht und wie listen interpretiert wird.

Realm	listen	Event-Quelle	Anchor-Unterstützung
browser	DOM-Event wie click oder show-dialog	Browser-Events auf window in der Capture-Phase	Event-Pfad-Ausdrücke aus dem composed path und select_tree
shortcut	Tinykeys-Tastenkürzel wie "$mod+Shift+K"	Browser-Keyboard-Event	Event-Pfad-Ausdrücke und select_tree
server	Home-Assistant-Event-Bus-Event wie state_changed, component_loaded oder call_service	Aktive Frontend-Verbindung	Nur select_tree

Alle Realms unterstützen Regeln und Direktiven. Der gewählte Interaction Anchor befindet sich immer im aktuellen Browser. Auch ein Event aus dem server-Realm kann daher ein Browser-Element aktualisieren oder ein Event darauf auslösen.

Browser

browser lauscht auf window während der Capture-Phase. Nutze ihn für DOM-Events wie click, change, show-dialog und benutzerdefinierte Home-Assistant-Browser-Events.

- realm: browser
  listen: show-dialog
  anchor: '&home-assistant $ hui-dialog-create-card'
  debug: true
  rules:
    - '@captured.dialogTag': hui-dialog-create-card
  directives:
    - type: property
      set: _currTab
      value: card

Das detail-Objekt des Browser-Events ist die Wurzel der Captured Data. Siehe Captured-Data-Regeln und Event-Direktive.

UIX-Styling-Lebenszyklus-Events

UIX Styling löst am <uix-node> folgende Browser-Events mit bubbles: true und composed: true aus:

• uix-applied: Nachdem UIX an ein Element angehängt oder erneut angewendet wurde. Kann bei Host-Updates oder erneut angewendeter Konfiguration wieder auftreten; Direktiven sollten deshalb idempotent sein.
• uix-styles-update: Wenn der UIX-Knoten seinen gerenderten CSS-Text aktualisiert, auch durch Templates. Der aktuelle Text steht in detail.uix_node._rendered_styles, Lit hat das <style>-Element aber noch nicht übernommen. Um anschließend berechnete Styles auszulesen, verwende zuerst eine action: javascript-Direktive mit data.code: "return event.detail.uix_node.updateComplete;". Die Aktion wartet auf dieses Promise, bevor die nächste Direktive läuft.
• uix-theme-update: Nachdem der UIX-Knoten ein Theme-Update verarbeitet hat; auch wenn sich das resultierende CSS nicht geändert hat.

Alle drei Events stellen den ursprünglichen <uix-node> als detail.uix_node bereit. Der Event-Pfad-Anchor "< target" wählt dessen übergeordnetes Element, auf das UIX angewendet wird — sowohl im Light DOM als auch im Shadow Root.

Dieses Originalbeispiel setzt themeMode einer Karte, wenn UIX angewendet oder das Theme aktualisiert wird:

- realm: browser
  listen:
    - uix-applied
    - uix-theme-update
  anchor: "< target"
  rules:
    - hui-map-card
  directives:
    - type: property
      anchor: "$ ha-map"
      set: themeMode
      value: dark

Shortcut

shortcut nutzt Tinykeys und registriert ein Tastenkürzel auf window. $mod bedeutet Meta auf macOS und Control unter Windows und Linux.

- realm: shortcut
  listen: "$mod+Shift+Y"
  anchor: target
  directives:
    - type: call
      method: focus

Tastenkürzel können Tasten, Codes, Modifikatoren und Sequenzen nutzen. Home Assistant nutzt ebenfalls Tinykeys. Verwende daher Kombinationen, die nicht mit Home Assistant, dem Browser oder dem Betriebssystem kollidieren. Home-Assistant-Tastenkürzel können für den Browser deaktiviert werden; UIX Broker kann seine Tastenkürzel dann weiterhin registrieren.

Das auslösende KeyboardEvent steht JavaScript-Actions als event zur Verfügung. Sein composed path kann auch von Interaction Anchors genutzt werden.

Server

server abonniert den Home-Assistant-Event-Bus über die aktive Frontend-Verbindung. Es gibt kein Browser-Event-Ziel, daher muss der Interaction Anchor select_tree nutzen.

- realm: server
  listen: state_changed
  anchor: "&home-assistant $$ dynamic-custom-card"
  rules:
    - type: captured
      path: data.entity_id
      match: light.kitchen
  directives:
    - type: property
      set: customCardProperty
      value: "@captured.data.entity_id"

Bei Server-Interaktionen enthält Captured Data unter data die Home-Assistant-Eventdaten, zum Beispiel data.entity_id oder data.new_state.state. In Regeln und Direktiven kann mit "@captured.data..." darauf verwiesen werden. Die Anführungszeichen sind in YAML wegen @ erforderlich.

Blocking

Die Direktive block ist in den Realms browser und shortcut verfügbar. Anchor und Host-Element-Regeln werden synchron aufgelöst. Wenn ein select_tree-Anchor nicht sofort gefunden wird, wird die ganze Interaktion übersprungen. Server-Events können nicht blockiert werden.

INFO

Tinykeys ignoriert Tastendrücke in input, textarea, select und contenteditable. Ein shortcut-Realm mit block läuft dort daher nicht. Um Tasten in solchen Bereichen zu blockieren, nutze den browser-Realm mit listen: keydown.

Wenn ein Shortcut ausgeführt wird, verhindert block die native Standardaktion und spätere Listener auf window. Einen bereits ausgeführten Home-Assistant-Shortcut-Handler kann es nicht rückgängig machen.

Templates

UIX Broker stellt bewusst keinen Realm bereit, der direkt Jinja2-Templates abonniert. Nutze stattdessen ein Script, eine Automation oder eine Template-Entität mit Trigger, löse ein eigenes Home-Assistant-Event aus und lausche im server-Realm darauf.

Die template-Direktive kann während einer Interaktion einmalig ein Template rendern. Sie beobachtet keine späteren Änderungen. Für reaktives Verhalten kann beispielsweise ein eigenes Event uix-update aus Home Assistant ausgelöst werden.

TIP

Die Integration custom_event kann eigene Events auf dem Home-Assistant-Event-Bus auslösen, auf die UIX Broker im server-Realm reagieren kann.