Actions UIX

UIX propose plusieurs actions personnalisées utilisables dans les tableaux de bord Home Assistant. Elles sont appelées avec action: fire-dom-event ; l'objet uix: indique l'action et l'objet data: contient ses paramètres. Vous pouvez les utiliser avec toute carte prenant en charge fire-dom-event, notamment les cartes standard de Home Assistant.

INFO

Les paramètres de l'objet data: d'une action UIX dépendent de l'événement Home Assistant appelé et ne sont pas définis par UIX. La configuration comporte donc plusieurs clés action, ce qui peut prêter à confusion. Chacune a toutefois son rôle. En cas de problème, suivez la configuration indiquée pour l'action UIX concernée.

# ... card config
  tap_action:
    action: fire-dom-event
    uix:
      action: <action>
      data:
        <action-data>

INFO

action: clear_cache et action: more_info sont également acceptés et correspondent respectivement à action: clear-cache et action: more-info.

clear-cache — vider le cache du frontend Home Assistant

Cette action vide le cache de l'application frontend Home Assistant et recharge le navigateur, sans toucher à localStorage. Elle est pratique lorsque l'option est cachée dans un menu de débogage. Elle vide également d'autres données du cache de l'application ; localStorage, qui contient notamment l'identifiant du navigateur Browser Mod, reste intact.

Configuration	Paramètre	Valeur par défaut	Description
action: clear-cache	—	—	Vide le cache de l'application Home Assistant et recharge le navigateur.
data:	—	—	Non utilisé

Exemple de bouton pour vider le cache et recharger la page :

show_name: true
show_icon: true
type: button
name: Clear Frontend Cache
tap_action:
  action: fire-dom-event
  uix:
    action: clear-cache

event — envoyer un événement du navigateur

Envoie un CustomEvent sur window. Cela permet de relier l'action d'un bouton à une interaction UIX Broker dans le realm browser, sans ajouter d'écouteur fire-dom-event chargé de déballer un autre événement.

Configuration	Paramètre	Valeur par défaut	Description
action: event	—	—	Envoie un CustomEvent du navigateur sur window.
name	OBLIGATOIRE	—	Nom de l'événement.
data	—	{}	Propriété detail de l'événement.

Pour une action de tableau de bord classique, l'événement est envoyé sur window. Pour une directive button d'UIX Broker, UIX l'envoie automatiquement depuis le point d'insertion du bouton — sa cible after, sa cible before ou l'ancre de la directive — avec bubbles: true et composed: true. L'interaction Broker qui le reçoit peut donc utiliser une ancre de chemin d'événement telle que target, < ou <$, sans rechercher à nouveau un chemin absolu select_tree.

Par exemple, ce bouton Broker envoie l'événement toggle-yaml-mode depuis son point d'insertion :

- type: button
  before: $ ha-automation-sidebar $$ ha-automation-sidebar-card $ ha-dialog-header slot:nth-of-type(3) ha-dropdown
  icon: mdi:code-braces
  tap_action:
    action: fire-dom-event
    uix:
      action: event
      name: toggle-yaml-mode
      data:
        source: sidebar-button

Lorsqu'un spark Formulaire de Forge déclenche l'action event, ses valeurs actuelles sont ajoutées aux données de l'action et donc au detail de l'événement.

more-info — afficher les informations détaillées d'une entité

Affiche la boîte de dialogue Home Assistant des informations détaillées. Vous pouvez choisir la vue affichée à son ouverture.

Configuration	Paramètre	Valeur par défaut	Description
action: more-info	—	—	Affiche la boîte de dialogue des informations détaillées avec les options d'entité et de vue définies dans data:.
data:	—	—	Options d'entité et de vue pour les informations détaillées.
	entity	—	Identifiant de l'entité à afficher.
	view	info	Vue initiale de la boîte de dialogue : info, history, settings, related, add_to ou details.

Exemple d'affichage des informations détaillées avec la vue historique :

type: tile
entity: light.bed_light
tap_action:
  action: fire-dom-event
  uix:
    action: more-info
    data:
      entity: light.bed_light
      view: history

toast — afficher une notification Home Assistant

Affiche une notification temporaire (toast) de Home Assistant.

Configuration	Paramètre	Valeur par défaut	Description
action: toast	—	—	Affiche une notification temporaire Home Assistant avec les options de data:.
data:	—	—	Options de la notification.
	id	—	Identifiant de la notification. Réutilisez le même identifiant pour remplacer une notification existante.
	message	OBLIGATOIRE	Chaîne ou objet. Une chaîne n'est pas traduite. Pour utiliser une traduction Home Assistant, indiquez un objet avec translationKey et, éventuellement, args.
	duration	4000	Durée d'affichage en millisecondes. Toute valeur inférieure à 4 000 est ramenée à 4 000 (4 secondes). Utilisez -1 pour un affichage permanent ; une nouvelle notification la remplacera.
	dismissable	false	Affiche une icône de fermeture qui permet à l'utilisateur de masquer immédiatement la notification.
	bottomOffset	0	Décalage vertical positif par rapport au bas de la fenêtre du navigateur. Les notifications apparaissent à --ha-space-4 (16 px par défaut) au-dessus de la limite de la zone sûre.
	action	—	Si elle est définie, affiche un bouton qui exécute action.tap_action au clic.
	action.primary	—	Si la valeur est true, affiche le bouton action avec le style principal rempli. La variante du bouton est toujours brand.
	action.text	OBLIGATOIRE	Chaîne ou objet définissant le texte du bouton. Une chaîne n'est pas traduite ; pour utiliser une traduction Home Assistant, indiquez un objet avec translationKey et, éventuellement, args.
	action.tap_action	OBLIGATOIRE	Configuration d'action Home Assistant.
	secondary_action	—	Si elle est définie, affiche à gauche du bouton action un bouton qui exécute secondary_action.tap_action.
	secondary_action.primary	—	Si la valeur est true, affiche le bouton secondary_action avec le style principal rempli. La variante du bouton est toujours brand.
	secondary_action.text	OBLIGATOIRE	Chaîne ou objet définissant le texte du bouton. Une chaîne n'est pas traduite ; pour utiliser une traduction Home Assistant, indiquez un objet avec translationKey et, éventuellement, args.
	secondary_action.tap_action	OBLIGATOIRE	Configuration d'action Home Assistant.

Exemple de notification avec une action dont le libellé est traduit :

type: tile
entity: light.bed_light
tap_action:
  action: fire-dom-event
  uix:
    action: toast
    data:
      message: "Bed Light"
      duration: 10000
      dismissable: true
      bottomOffset: 550
      action:
        primary: true
        text:
          translationKey: ui.dialogs.more_info_control.light.toggle
        tap_action:
          action: perform-action
          perform_action: light.toggle
          target:
            entity_id: light.bed_light
      secondary_action:
        text: Custom
        tap_action:
          action: perform-action
          perform_action: light.toggle
          target:
            entity_id: light.ceiling_lights

popover — afficher un popover Home Assistant ancré

Affiche un popover adaptatif Home Assistant à côté de l'élément qui a déclenché l'action ll-custom. Il inclut le bouton de fermeture accessible standard de Home Assistant et se supprime après sa fermeture.

Configuration	Paramètre	Valeur par défaut	Description
action: popover	—	—	Affiche un popover adaptatif avec les options de data:.
data:	—	—	Options du popover.
	target	Source de l'action	Element DOM auquel ancrer le popover. none affiche un dialogue adaptatif centré sous le shadow root de Home Assistant.
	title	—	Définit headerTitle.
	subtitle	—	Définit headerSubtitle.
	subtitle_position	below	Définit header-subtitle-position : above ou below.
	width	small	Largeur : small, large ou full.
	without_header	false	Masque l'en-tête et son bouton de fermeture. Échap ferme toujours le popover sauf si dismissible vaut false.
	dismissible	true	Autorise le bouton de fermeture, Échap et le clic à l'extérieur. Avec false, un bouton de pied de page est obligatoire. dismissable est accepté comme alias.
	content	—	Contenu HTML ; incompatible avec card.
	card	—	Configuration d'une carte Home Assistant ; incompatible avec content.
	style	—	Objet plat associant des propriétés CSS à des chaînes ou nombres, appliqué directement à ha-adaptive-popover.
	uix	—	Configuration de style UIX appliquée comme dialog avec la classe type-uix-popover.
	icons	—	Liste de boutons à icône dans l'en-tête. Chaque entrée nécessite icon.
	buttons	—	Boutons de pied de page facultatifs. Au moins un est obligatoire avec dismissible: false.
	buttons.primary	—	Bouton à l'extrémité principale du pied de page ; valeurs par défaut : variant: brand, appearance: accent.
	buttons.secondary	—	Bouton avant le bouton principal ; valeurs par défaut : variant: neutral, appearance: filled.

buttons.primary et buttons.secondary utilisent les paramètres du spark Bouton de Forge, sauf les paramètres de placement. Ils acceptent label, icon, start_icon, end_icon, entity, size, variant, appearance, tap_action, hold_action et double_tap_action. Les positions suivent le sens d'écriture : le bouton principal est à droite de gauche à droite, et à gauche de droite à gauche. Un bouton avec une action ferme le popover après l'exécution de l'action ; un bouton sans action le ferme au clic.

Si la carte contient un spark Formulaire de Forge, ses valeurs actuelles sont ajoutées aux données des actions des deux boutons de pied de page. Le formulaire peut alors omettre ses propres boutons d'envoi et d'effacement.

Avec target: none, le même contenu apparaît dans un dialogue adaptatif centré. Une intégration ou un appelant personnalisé peut fournir un véritable élément DOM comme target pour choisir une autre ancre.

Chaque entrée icons utilise le bouton rond natif de Home Assistant et doit définir icon. label fournit son nom accessible. Elle accepte entity, color, tap_action, hold_action et double_tap_action. Les icônes d'en-tête ne ferment pas le popover ; elles conviennent aux paramètres ou à l'aide.

Utilisez style pour les propriétés directes du popover et uix pour styliser l'en-tête, le pied de page et les éléments internes avec la navigation DOM habituelle. Les données d'action sont accessibles aux modèles via config. Une carte créée avec card reçoit la classe uix-popover-card. .uix-popover-card permet de définir les propriétés CSS personnalisées sur l'hôte de la carte ; ".uix-popover-card $" cible l'intérieur de son shadow root.

Cet exemple original affiche du contenu HTML lorsque le bouton est activé :

type: button
show_icon: false
name: Popover
tap_action:
  action: fire-dom-event
  uix:
    action: popover
    data:
      title: Bed light
      subtitle: Quick controls
      subtitle_position: above
      width: small
      content: |
        <p>You can toggle the light using the primary action.</p>
        <p>You can navigate to config/dashboard with the cog icon.</p>
      style:
        "--ha-dialog-border-radius": 12px
      uix:
        style:
          "$": |
            .content-wrapper {
              --dialog-content-padding: 0 var(--ha-space-6) var(--ha-space-6);
            }
      icons:
        - icon: mdi:cog
          label: Settings
          tap_action:
            action: navigate
            navigation_path: /config/dashboard
      buttons:
        secondary:
          label: Cancel
        primary:
          label: Toggle
          entity: light.bed_light
          tap_action:
            action: toggle

Remplacez content par card pour afficher une carte. Cet exemple original retire aussi la bordure et l'arrière-plan de la carte :

type: button
show_icon: false
name: Popover
tap_action:
  action: fire-dom-event
  uix:
    action: popover
    data:
      title: Bed light
      subtitle: Quick controls
      subtitle_position: above
      width: small
      card:
        type: entities
        entities:
          - light.bed_light
      uix:
        style: |
          .uix-popover-card {
            --ha-card-border-width: 0px;
            --ha-card-background: none;
          }

javascript — exécuter du JavaScript dans la session du navigateur

Exécute du code JavaScript dans la session du navigateur. L'objet hass est disponible, ainsi qu'un objet facultatif variables.

WARNING

Cette action exécute du JavaScript arbitraire dans la session frontend Home Assistant actuelle. N'utilisez que du code et une configuration de confiance ; ce code peut accéder aux données disponibles dans la session du navigateur.

Configuration	Paramètre	Valeur par défaut	Description
action: javascript	—	—	Exécute du JavaScript avec les options définies dans data:.
data:	—	—	Options JavaScript.
	code	OBLIGATOIRE	Code JavaScript à exécuter.
	variables	{}	Objet de variables facultatif. Chaque variable nommée est accessible en JavaScript avec variables.<name>. Les valeurs peuvent être de n'importe quel type.

Exemple d'action JavaScript utilisant une variable et l'objet hass pour éteindre une lumière :

type: tile
entity: light.bed_light
tap_action:
  action: fire-dom-event
  uix:
    action: javascript
    data:
      variables:
        entity_id: light.bed_light
      code: |
        console.log("UIX: Custom javascript action executed!");
        hass.callService("light", "turn_off", {}, { entity_id: variables.entity_id });

Lorsqu'un spark Formulaire de Forge déclenche l'action javascript, ses valeurs actuelles sont ajoutées à data.variables. Le code y accède avec variables.<nom_du_champ>.

locked_action — demander un code ou une confirmation avant l'action

INFO

Disponible à partir de la version 8.3.0-beta.2.

Exécute une action Home Assistant classique uniquement après validation du verrou configuré pour l'utilisateur actuel. Cette action convient notamment au redémarrage, à l'ouverture d'un portail ou à la modification d'un réglage important, sans devoir envelopper toute la carte dans un verrou Forge.

type: button
name: Restart Home Assistant
tap_action:
  action: fire-dom-event
  uix:
    action: locked_action
    data:
      locks:
        - code: 1234
          admins: true
      locked_action:
        action: perform-action
        perform_action: homeassistant.restart

WARNING

locked_action protège une interaction dans le frontend ; il ne constitue pas une limite d'autorisation. Toute personne capable de modifier le tableau de bord ou d'inspecter sa configuration chargée peut voir le code et l'action protégée. Pour contrôler les accès, utilisez les permissions Home Assistant et des contrôles côté serveur.

Référence de configuration

Clé	Type	Valeur par défaut	Description
locked_action	object	—	Obligatoire. Action Home Assistant à exécuter après validation du verrou.
locks	list	[]	Liste ordonnée de règles de verrouillage. Consultez Correspondance des verrous et Clés d'une règle.
permissive	boolean	false	Si la valeur est true, les utilisateurs ne correspondant à aucune règle peuvent exécuter l'action.
entity	string	—	Identifiant d'entité transmis à l'action imbriquée, pour les types d'action qui utilisent l'entité de la carte.
code_dialog	object	—	Libellés de la demande de code ou de phrase secrète. Consultez Boîte de dialogue du code.
id	string ou number	—	Identifiant stable utilisé pour suivre les nouvelles tentatives et les blocages. Fortement recommandé avec retry_delay ou max_retries ; utilisez un identifiant différent pour chaque action protégée.

locked_action accepte tout objet d'action Home Assistant classique, notamment perform-action, toggle, more-info, navigate et fire-dom-event.

Correspondance des verrous

locks est une liste ordonnée. La première règle active correspondante détermine le contrôle demandé. Si aucune règle active ne correspond, la première règle correspondante avec active: false autorise l'action sans contrôle.

Configuration	Utilisateurs concernés
La liste users est présente	Utilisateurs dont le nom figure dans la liste. Avec admins: true, tous les administrateurs correspondent aussi.
Aucune liste users	Tous les utilisateurs non administrateurs, sauf ceux de except.
Aucune liste users avec admins: true	Tous les utilisateurs, sauf ceux de except.

admins ajoute les administrateurs à la règle : sans cette option, ils en sont exclus sauf s'ils figurent dans users. Si aucune règle ne correspond, permissive: true autorise l'action. Avec la valeur par défaut permissive: false, les administrateurs contournent le verrou d'interaction et les autres utilisateurs ne peuvent pas exécuter l'action.

Clés d'une règle de verrouillage

Clé	Type	Valeur par défaut	Description
active	boolean	true	Définissez false pour autoriser explicitement les utilisateurs correspondants sans contrôle.
code	string ou number	—	Code à saisir. Un code uniquement numérique affiche le pavé numérique Home Assistant ; les autres valeurs utilisent un champ de mot de passe.
pin	string ou number	—	Alias de code.
confirmation	string, boolean ou object	—	Confirmation demandée après le code. true utilise le texte par défaut de Home Assistant ; une chaîne définit un texte personnalisé ; un objet peut contenir title et text.
users	liste de chaînes	—	Noms des utilisateurs concernés par cette règle.
admins	boolean	false	Étend la règle aux administrateurs. Sans liste users, elle s'applique alors à tous les utilisateurs.
except	liste de chaînes	—	Noms des utilisateurs exemptés d'une règle sans users.
retry_delay	number ou string	—	Délai après un code erroné avant une nouvelle tentative. Les nombres sont en millisecondes ; les chaînes acceptent des unités comme "10s".
max_retries	number	—	Nombre de codes erronés autorisés avant le blocage prolongé.
max_retries_delay	number ou string	30000	Durée du blocage après max_retries. Les nombres sont en millisecondes ; les chaînes acceptent des unités comme "30s" ou "5m".

Boîte de dialogue du code

Utilisez code_dialog pour personnaliser la demande de code ou de phrase secrète.

Clé	Type	Valeur par défaut	Description
title	string	Valeur par défaut Home Assistant	Titre de la boîte de dialogue.
submit_text	string	Valeur par défaut Home Assistant	Libellé du bouton de confirmation.
cancel_text	string	Valeur par défaut Home Assistant	Libellé du bouton d'annulation.

Suivi des tentatives

L'état des tentatives est conservé dans la session de navigateur actuelle. Définissez id dès que le délai entre les tentatives ou le blocage est important, en particulier si un modèle ou une autre carte personnalisée peut recréer la configuration du tableau de bord : un identifiant explicite reste stable après la recréation du contrôle. Le même identifiant partage le compteur de tentatives ; attribuez donc un identifiant distinct à chaque action protégée.

tap_action:
  action: fire-dom-event
  uix:
    action: locked_action
    data:
      id: restart-home-assistant
      code_dialog:
        title: Enter administrator PIN
        submit_text: Restart
      locks:
        - code: 1234
          admins: true
          max_retries: 3
          max_retries_delay: 5m
      locked_action:
        action: perform-action
        perform_action: homeassistant.restart