← Todos los artículos

API y helpers

window.JZ: helpers para pilotar botones, sliders y Output Console desde el código

15 mayo 2026 · por JustZix Team

Por un momento, olvida que JustZix inyecta CSS y JS en cada página. Concéntrate en el hecho de que cada acción — botón, slider, select, toggle3, input, textarea — es un elemento DOM vivo que puedes pilotar desde otro código. Hacen falta dos namespaces separados en el MAIN world: window.JZ (helpers para las acciones) y window.JUSTZIX (logger). Cada uno tiene su ciclo de vida, su propósito, y deliberadamente no se mezclan.

Por qué dos namespaces y no uno

El logger (solo escritura, dispatch hacia la Output Console) y la direccionabilidad del DOM (leer/manipular elementos que ya viven en el DOM de la página) son dos semánticas distintas. Empaquetarlas juntas mezclaría las responsabilidades. Un usuario que lee el código ve JUSTZIX.log(...) y sabe: «eso es un logger». Ve document.querySelector('[data-jz-action-id="x"]') y sabe: «eso es una query DOM». Además — la API DOM nativa + los atributos data-* siempre ganan sobre un wrapper propietario (funciona con el inspect de las DevTools, con las librerías de terceros, con el copia-pega de internet).

Idempotente — la instalación se gestiona por versión (_jzVersion para JZ, flag de hook para JUSTZIX), así las actualizaciones de la extensión no sobrescriben los namespaces a mitad de sesión.

Superficie completa de la API

// ============================================================
// window.JZ — Helpers para las acciones
// Opera sobre elementos data-jz-action-id en el DOM.
// Puede estar ocupado por los scripts de la página → fallback: query DOM nativa.
// ============================================================
JZ.action(labelOrId)     // Elemento por label O id. Case-insensitive por label.
JZ.actionById(id)        // Elemento por data-jz-action-id. Sin fallback a label.
JZ.actions()             // Array de todos los elementos acción del DOM.
JZ.labels()              // Array de labels (mayúsculas/minúsculas originales).
JZ.click(labelOrId)      // Click programático. Para <select> elige la primera opción.
                          // Devuelve true/false.
JZ.value(labelOrId)      // Valor actual de la acción (string o null).
JZ.setValue(labelOrId, value)  // Setter programático + dispatch de input + change.
JZ.bars()                // Array de todas las .jz-actions-bar del DOM.
JZ.barById(id)           // Barra por data-jz-bar-id.
JZ.floatingBtn()         // El elemento del botón flotante de JustZix (cuando está activo).

// ============================================================
// window.JUSTZIX — Logger (desde v2.13.73, alias primario desde v2.13.76)
// Hace dispatch hacia la Output Console (kind='jz'); NO reenvía al console.* nativo.
// Nombre de marca = riesgo de colisión despreciable. Funciona en todas partes.
// ============================================================
JUSTZIX.log(...args)
JUSTZIX.warn(...args)
JUSTZIX.error(...args)
JUSTZIX.info(...args)
JUSTZIX.debug(...args)

// Alias a la misma API:
window.__JUSTZIX__       // siempre establecido (retrocompatibilidad con v2.13.72-75)
window.JZ                // también, solo cuando no está ocupado — un atajo más corto

// Fallback cuando window.JZ está ocupado por la página (p. ej. Google Ads):
// → ningún equivalente de JUSTZIX.click(); usa el DOM nativo.
document.querySelector('[data-jz-action-id="..."]').click();

Caso de uso 1 — un botón pulsa otro botón

Tienes las acciones «Login → Dashboard → Estadísticas». Tres botones separados en una barra de acciones. Añade un cuarto «🚀 Quick» que ejecuta los tres en secuencia:

// Acción BUTTON «Quick» — campo del código:
JZ.click('Login');
await new Promise(r => setTimeout(r, 800));
JZ.click('Dashboard');
await new Promise(r => setTimeout(r, 500));
JZ.click('Estadísticas');
JUSTZIX.log('Flujo Quick completado — 3 clics en 1');

Bonus: este script no sabe nada de la página, solo conoce sus acciones JustZix. Cambia los selectores dentro de «Login» / «Dashboard» — «Quick» sigue funcionando, porque los llama por label.

Caso de uso 2 — un slider pilota una variable CSS

Acción SLIDER «Brillo» (rango 50-150, default 100). En su campo «Code»:

// El slider ejecuta este código en cada cambio.
// `value` es una extraVar inyectada por la extensión (desde v2.12.2).
document.documentElement.style.setProperty('--brightness', value + '%');

Ahora en otra acción (BUTTON «Reset») puedes establecer programáticamente el valor del slider:

JZ.setValue('Brillo', 100);  // El slider salta a 100, variable CSS actualizada, brillo restaurado.
JUSTZIX.log('Brillo restablecido al 100%');

Lo mismo vale para TOGGLE3 (interruptores de 3 estados como «Dev / Staging / Prod»): JZ.setValue('Entorno', 'staging') activa ese estado específico y ejecuta su código.

Caso de uso 3 — la Output Console como «bloc de notas»

La Output Console (desde v2.13.66) es un pane que captura toda la salida de console.log de la página. Páginas como Gmail atascan la consola con cientos de líneas por segundo. Los filtros sobre las cadenas ayudan, pero un truco mejor: escribe solo tus mensajes mediante JUSTZIX.log, luego pon el pane en modo [J] (Just JustZix).

// En una acción «Verificar carrito»: loguea solo TUS mensajes, sin ruido de la página.
const items = document.querySelectorAll('.cart-item');
JUSTZIX.log(`El carrito tiene ${items.length} artículos`);
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}`);

El pane Output Console en modo [J] muestra SOLO esas 3 líneas — completamente limpio, perfecto para una toolbar QA o un contexto de cara al cliente.

¿Y si la página ya tiene window.JZ?

El logger funciona siempre — JUSTZIX.log() tiene un nombre de marca (riesgo de colisión despreciable) y es el primario. Además window.__JUSTZIX__ siempre está establecido como alias de fallback. Un conflicto sobre window.JZ afecta solo a los helpers para las acciones — e incluso entonces tienes una salida nativa.

Algunos sitios (p. ej. Google Ads) tienen su propio window.JZ. JustZix lo detecta: si window.JZ ya existe cuando el logger se instala, la extensión no sobrescribe la API de la página y lo señala en el mensaje de bienvenida de la Output Console. El atajo corto JZ queda entonces reservado a la página — usa JUSTZIX para el logging y el DOM nativo para las acciones:

// Logger: siempre JUSTZIX (funciona incluso cuando JZ está ocupado por la página)
JUSTZIX.log('Carrito procesado');

// Click sobre una acción: cuando window.JZ está ocupado → usa el DOM nativo en lugar de JZ.click()
document.querySelector('[data-jz-action-id="actionId"]').click();
// O por data-jz-key (label en mayúsculas):
document.querySelector('.jz-actions-bar [data-jz-key="LOGIN"]').click();

Es un diseño deliberado: data-jz-action-* + querySelector es un patrón nativo — funciona con el inspect de las DevTools, con las librerías de terceros, con el copia-pega de internet. JZ.click() es azúcar sintáctico — una capa de indirección opcional que puedes saltarte cuando no está disponible.

Trampas

• JZ.click() sobre INPUT/TEXTAREA solo los pulsa, no cambia su valor. Para establecer el texto: JZ.setValue('Buscar', 'foo'). Los demás tipos (button, select, toggle3, slider) tienen un default sensato para el click.
• JZ.value()/setValue() se volvieron más completos desde v2.13.33. Las versiones más antiguas no tenían el valor del slider en el dataset — si ves null para un slider, comprueba la versión de la extensión.
• La búsqueda por label es case-insensitive, pero la de ID es case-sensitive. Recomendado: cíñete a las labels (las tuyas), no a los IDs (auto-generados).
• JUSTZIX.log NO reenvía a la consola de las DevTools. Es a propósito — queremos un canal separado para los scripts JustZix. Si quieres las DevTools — usa el normal console.log.
• La JS Console captura solo el tráfico en estilo DevTools, no JUSTZIX.log automáticamente. «console.log('hi')» en la JS Console funciona como siempre; «JUSTZIX.log('hi')» en la JS Console NO aparecerá en la Output Console a menos que tengas un pane Output Console activo en modo [J] o [C+J].
• Ningún JUSTZIX.click() o similar. Logger y helpers para las acciones son namespaces separados por decisión. Cuando la página ocupa window.JZ, activas las acciones mediante el DOM nativo (querySelector + data-jz-action-*) — es el patrón, no un bug.

Qué hacer después

Esto cierra la mini-serie sobre las ventanas de JustZix en el frontend:

• CSS pane — editor CSS en tiempo real en la pestaña
• JS Console — REPL con historial ↑↓
• JS pane — Run-on-demand
• window.JZ helpers (este artículo) — la API programática

Todo junto es un mini-IDE dentro de cada pestaña del navegador, con una mini-API para pilotar tus botones. Instala JustZix y pruébalo tú mismo — completamente gratuito, sin cuenta, sin servidor.