← Tous les articles

API et helpers

window.JZ : des helpers pour piloter boutons, curseurs et Output Console depuis le code

15 mai 2026 · par JustZix Team

Oubliez un instant que JustZix injecte du CSS et du JS dans chaque page. Concentrez-vous sur le fait que chaque action — bouton, curseur, select, toggle3, input, textarea — est un élément DOM vivant que vous pouvez piloter depuis d'autre code. Il vous faut deux namespaces séparés dans le MAIN world : window.JZ (helpers d'action) et window.JUSTZIX (logger). Chacun a son propre cycle de vie, son propre but, et ils ne se mélangent délibérément pas.

Pourquoi deux namespaces et pas un

Le logger (write-only, dispatch vers l'Output Console) et l'adressabilité DOM (lire/manipuler des éléments qui vivent déjà dans le DOM de la page) sont deux sémantiques différentes. Les empaqueter ensemble mélangerait les responsabilités. Un utilisateur qui lit le code voit JUSTZIX.log(...) et sait : « c'est un logger ». Il voit document.querySelector('[data-jz-action-id="x"]') et sait : « c'est une requête DOM ». De plus — l'API DOM native + les attributs data-* gagnent toujours sur un wrapper propriétaire (fonctionne avec l'inspect des DevTools, avec les bibliothèques tierces, avec le copier-coller depuis internet).

Idempotent — l'installation est verrouillée par version (_jzVersion pour JZ, flag de hook pour JUSTZIX), donc les mises à jour de l'extension n'écrasent pas les namespaces en pleine session.

Toute la surface de l'API

// ============================================================
// window.JZ — Helpers d'action
// Opère sur les éléments data-jz-action-id du DOM.
// Peut être pris par les scripts de la page → fallback : requête DOM native.
// ============================================================
JZ.action(labelOrId)     // Élément par label OU id. Insensible à la casse par label.
JZ.actionById(id)        // Élément par data-jz-action-id. Pas de fallback par label.
JZ.actions()             // Tableau de tous les éléments d'action du DOM.
JZ.labels()              // Tableau des labels (casse originale).
JZ.click(labelOrId)      // Clic programmatique. Pour <select> choisit la première option.
                          // Renvoie true/false.
JZ.value(labelOrId)      // Valeur actuelle de l'action (string ou null).
JZ.setValue(labelOrId, value)  // Setter programmatique + dispatche input + change.
JZ.bars()                // Tableau de toutes les .jz-actions-bar du DOM.
JZ.barById(id)           // Barre par data-jz-bar-id.
JZ.floatingBtn()         // L'élément du bouton flottant JustZix (quand activé).

// ============================================================
// window.JUSTZIX — Logger (depuis v2.13.73, alias principal depuis v2.13.76)
// Dispatche vers l'Output Console (kind='jz'); ne redirige PAS vers console.* natif.
// Nom de marque = risque de collision infime. Fonctionne partout.
// ============================================================
JUSTZIX.log(...args)
JUSTZIX.warn(...args)
JUSTZIX.error(...args)
JUSTZIX.info(...args)
JUSTZIX.debug(...args)

// Alias vers la même API :
window.__JUSTZIX__       // toujours défini (rétrocompatibilité avec v2.13.72-75)
window.JZ                // aussi, seulement quand non pris — un raccourci plus court

// Fallback quand window.JZ est pris par la page (p. ex. Google Ads) :
// → pas d'équivalent JUSTZIX.click(); utilisez le DOM natif.
document.querySelector('[data-jz-action-id="..."]').click();

Cas d'usage 1 — un bouton clique un autre bouton

Vous avez les actions « Login → Dashboard → Stats ». Trois boutons séparés dans une barre d'actions. Ajoutez un quatrième « 🚀 Quick » qui exécute les trois en séquence :

// Action BUTTON "Quick" — champ Code :
JZ.click('Login');
await new Promise(r => setTimeout(r, 800));
JZ.click('Dashboard');
await new Promise(r => setTimeout(r, 500));
JZ.click('Stats');
JUSTZIX.log('Flux Quick terminé — 3 clics en 1');

Bonus : ce script ne sait rien de la page, seulement de ses propres actions JustZix. Changez les sélecteurs dans « Login » / « Dashboard » — « Quick » continue de fonctionner, puisqu'il les appelle par label.

Cas d'usage 2 — un curseur pilote une variable CSS

Action SLIDER « Luminosité » (plage 50-150, défaut 100). Dans son champ Code :

// Le curseur exécute ce code à chaque changement.
// `value` est une extraVar injectée par l'extension (depuis v2.12.2).
document.documentElement.style.setProperty('--brightness', value + '%');

Maintenant dans une autre action (BUTTON « Reset ») vous pouvez définir programmatiquement la valeur du curseur :

JZ.setValue('Luminosité', 100);  // Le curseur saute à 100, variable CSS mise à jour, luminosité réinitialisée.
JUSTZIX.log('Luminosité réinitialisée à 100%');

Idem pour TOGGLE3 (interrupteurs à 3 états comme « Dev / Staging / Prod ») : JZ.setValue('Environnement', 'staging') active cet état précis et exécute son code.

Cas d'usage 3 — Output Console comme « bloc-notes »

L'Output Console (depuis v2.13.66) est un pane qui capture toute la sortie console.log de la page. Des pages comme Gmail spamment la console de centaines de lignes par seconde. Les filtres de chaîne aident, mais une meilleure astuce : n'écrivez que vos messages via JUSTZIX.log, puis passez le pane en mode [J] (Just JustZix).

// Dans une action "Vérifier le panier" : ne logger QUE vos messages, pas le bruit de la page.
const items = document.querySelectorAll('.cart-item');
JUSTZIX.log(`Le panier a ${items.length} articles`);
items.forEach((it, i) => {
  const price = parseFloat(it.querySelector('.price')?.textContent || 0);
  JUSTZIX.log(`  [${i}] ${it.dataset.sku} — $${price}`);
});
const total = [...items].reduce((s, it) => s + parseFloat(it.querySelector('.price')?.textContent || 0), 0);
JUSTZIX.log(`Total : $${total}`);

Le pane Output Console en mode [J] affiche UNIQUEMENT ces 3 lignes — totalement propre, parfait pour une barre QA ou un contexte face client.

Que se passe-t-il si la page a déjà window.JZ ?

Le logger fonctionne toujours — JUSTZIX.log() a un nom de marque (risque de collision infime) et est le principal. De plus window.__JUSTZIX__ est toujours défini comme alias de secours. Un conflit window.JZ n'affecte que les helpers d'action — et même là vous avez une issue native.

Certains sites (p. ex. Google Ads) ont leur propre window.JZ. JustZix le détecte : si window.JZ existe déjà quand le logger s'installe, l'extension n'écrase pas l'API de la page et le note dans le message d'accueil de l'Output Console. Le raccourci court JZ est alors réservé à la page — utilisez JUSTZIX pour le log et le DOM natif pour les actions :

// Logger : toujours JUSTZIX (fonctionne même quand JZ est pris par la page)
JUSTZIX.log('Panier traité');

// Clic d'action : quand window.JZ est pris → utilisez le DOM natif au lieu de JZ.click()
document.querySelector('[data-jz-action-id="actionId"]').click();
// Ou par data-jz-key (label en majuscules) :
document.querySelector('.jz-actions-bar [data-jz-key="LOGIN"]').click();

C'est un choix de conception délibéré : data-jz-action-* + querySelector est un pattern natif — il fonctionne avec l'inspect des DevTools, avec les bibliothèques tierces, avec le copier-coller depuis internet. JZ.click() est du sucre — une couche d'indirection optionnelle que vous pouvez sauter quand elle n'est pas disponible.

Pièges

• JZ.click() sur INPUT/TEXTAREA les clique seulement, ne change pas leur valeur. Pour définir du texte : JZ.setValue('Recherche', 'foo'). Les autres types (button, select, toggle3, slider) ont un comportement de clic par défaut sensé.
• JZ.value()/setValue() sont devenus les plus complets depuis v2.13.33. Les versions plus anciennes n'avaient pas la valeur du curseur dans le dataset — si vous voyez null pour un curseur, vérifiez votre version d'extension.
• Le lookup par label est insensible à la casse, mais le lookup par ID est sensible à la casse. Recommandé : restez sur les labels (les vôtres), pas les IDs (auto-générés).
• JUSTZIX.log ne redirige PAS vers la console DevTools. Intentionnel — nous voulons un canal séparé pour les scripts JustZix. Si vous voulez les DevTools — utilisez le console.log habituel.
• La JS Console ne capture que le trafic façon DevTools, pas JUSTZIX.log automatiquement. « console.log('hi') » dans la JS Console fonctionne comme toujours ; « JUSTZIX.log('hi') » dans la JS Console N'apparaîtra PAS dans l'Output Console à moins d'avoir un pane Output Console actif en mode [J] ou [C+J].
• Pas de JUSTZIX.click() ni similaire. Logger et helpers d'action sont des namespaces séparés par conception. Quand la page prend window.JZ, vous déclenchez les actions via le DOM natif (querySelector + data-jz-action-*) — c'est le pattern, pas un bug.

Et ensuite

Cela clôt la mini-série sur les fenêtres JustZix sur la page :

• CSS pane — éditeur CSS en direct dans l'onglet
• JS Console — REPL avec historique ↑↓
• JS pane — Run-on-demand
• helpers window.JZ (ce billet) — l'API programmatique

Tout ensemble, c'est une mini-IDE dans chaque onglet de navigateur, avec une mini-API pour piloter vos propres boutons. Installez JustZix et essayez vous-même — entièrement gratuit, sans compte, sans serveur.