Un script de calcul (affiché sous le nom Transform dans les paramètres de la carte) est une petite fonction JavaScript qui déduit ce que dessine une carte à partir des données qu’elle a chargées. Utilisez-le lorsqu’aucune source ne fournit exactement la forme dont vous avez besoin : convertir des unités, associer deux séries en un tracé, compter des lignes, choisir le pire statut. Un script ne fait que calculer. Il ne peut ni définir un paramètre, ni exécuter une commande, ni ouvrir une page, ni accéder au réseau.
Ajouter un script
- Personnalisez le tableau de bord et ouvrez les paramètres de la carte.
- Dans l’onglet Données, ouvrez Avancé : calculer les valeurs avec un script.
- Cochez Exécuter ce script et rédigez le Script.
- Sélectionnez Exécuter maintenant pour exécuter votre brouillon sur les données actuelles de la carte. Le Résultat liste ce qui est revenu par emplacement, par exemple « series: table, 12 row(s) » et « ran in 3 ms ».
- Définissez le Délai maximal (ms) et En cas d’échec d’exécution.
- Sélectionnez Enregistrer.
Supprimer le script le supprime. Le script est copié avec la carte, voyage dans les fichiers de tableau de bord et reste sur la carte lorsque vous l’enregistrez comme widget.
Le contrat
Le script est un module ES dont l’export par défaut est une fonction synchrone :
export default function transform({ slots, params, window, now }) {
// slots: the bound data by slot key, as the source returned it (shape table | scalar | series | record)
// params: the effective board parameters of the card's page (read-only)
// window: { from, to, interval? } (ms since the epoch) when the card's data ran with a window
// now: ms since the epoch, the host's clock (a script never reads Date)
return { slots: { /* the slots you replace */ } };
}
Il renvoie { slots }. Chaque emplacement renvoyé remplace celui qui était chargé ; les emplacements que vous ne renvoyez pas restent tels qu’ils ont été chargés. Un résultat vide affiche les données telles qu’elles ont été chargées.
| Forme | Forme |
|---|---|
| Scalaire | { shape: 'scalar', value: 21.5, meta: { unit: '°C', decimals: 1 } } |
| Série | { shape: 'series', series: [{ name: 'temperature', points: [{ t: '2026-11-09T10:00:00Z', v: 21.5 }] }] } |
| Tableau | { shape: 'table', columns: [{ key: 'id' }, { key: 'value', type: 'number' }], rows: [{ id: 'p1', value: 3 }] } |
| Enregistrement | { shape: 'record', record: { level: 2.4, flow: 18 } } |
Une carte de schéma de procédé ou de modèle 3D peut également renvoyer scene : des objets, des surcharges par objet, des connexions et zones supplémentaires, la vue et les problèmes. Cela ne modifie que le dessin.
Lieu d’exécution
Le script s’exécute dans votre navigateur, dans un cadre masqué sans accès à Hermetry, au réseau ni à votre session, dans son propre worker. Il s’exécute à nouveau à chaque modification des données de la carte (y compris une mise à jour en direct) ou d’un paramètre. Une seule exécution par carte est en cours à la fois ; la dernière entrée l’emporte, à raison de 20 exécutions par seconde au maximum. Une carte qui n’est pas affichée ne s’exécute pas. Les écrans d’affichage exécutent les scripts de la même manière.
Limites
| Limite | Valeur |
|---|---|
| Longueur du script | 65 536 caractères |
| Délai maximal | De 10 à 500 ms par exécution, 50 par défaut. Au-delà, l’exécution est arrêtée. |
| Emplacements renvoyés | 16 |
| Lignes par tableau | 5,000 |
| Colonnes | 64 |
| Une valeur de texte | 10 KiB |
| Résultat complet | 2 MiB |
| Éléments dans une scène | 500 sur un schéma de procédé, 2 000 sur un modèle 3D |
En cas d’échec d’exécution
| En cas d’échec d’exécution | La carte |
|---|---|
| Conserver le résultat précédent | Conserve la dernière sortie valide et affiche un badge Transform failed |
| Afficher la carte vide | Affiche l’erreur à la place des données |
Messages : « The script ran past its time budget: … », « The script could not be loaded: … », « Transform failed: … ».
Exemples
Celsius vers Fahrenheit sur une carte indicateur (emplacement value) :
export default function transform({ slots }) {
const c = slots.value && typeof slots.value.value === 'number' ? slots.value.value : null;
if (c === null) return {};
return { slots: { value: { shape: 'scalar', value: c * 9 / 5 + 32, meta: { unit: '°F', decimals: 1 } } } };
}
Compter les alarmes ouvertes des équipements d’un paramètre (une carte indicateur dont l’emplacement value est lié à Alarms (live), un tableau) :
export default function transform({ slots }) {
const rows = slots.value && Array.isArray(slots.value.rows) ? slots.value.rows : [];
return { slots: { value: { shape: 'scalar', value: rows.length, meta: { decimals: 0 } } } };
}
Un tracé à partir de séries de latitude et de longitude (une carte de type carte dont l’emplacement routes est lié à Device readings over time avec les clés lat,lng) :
export default function transform({ slots }) {
const series = slots.routes && Array.isArray(slots.routes.series) ? slots.routes.series : [];
const named = (k) => series.find((s) => s && s.name === k) || { points: [] };
const lng = new Map(named('lng').points.map((p) => [p.t, p.v]));
const track = named('lat').points
.filter((p) => lng.has(p.t))
.map((p) => [p.v, lng.get(p.t), Date.parse(p.t)])
.sort((a, b) => a[2] - b[2]);
return { slots: { routes: { shape: 'table',
columns: [{ key: 'name' }, { key: 'positions' }],
rows: track.length >= 2 ? [{ id: 'route', name: 'Route', positions: track.slice(-256) }] : [] } } };
}
Une liste dans une cellule contient au plus 256 éléments ; limitez donc un tracé à 256 points. Voir Cartes de type carte.
Bonnes pratiques
- Ne renvoyez que les emplacements que vous modifiez.
- Prévoyez les données manquantes : un emplacement peut être vide lorsque l’équipement est silencieux.
- Gardez les scripts petits et rapides ; une longue boucle sur une année de relevés bruts atteindra le délai imparti. Privilégiez une source disposant d’un agrégat.
- Utilisez
now, jamaisDate.now(), pour tout calcul lié au temps.

