← Все статьи

API и хелперы

window.JZ: хелперы для управления кнопками, слайдерами и Output Console из кода

15 мая 2026 · автор JustZix Team

На мгновение забудь, что JustZix внедряет CSS и JS на каждую страницу. Сосредоточься на том, что каждое действие — кнопка, слайдер, select, toggle3, input, textarea — это живой DOM-элемент, которым ты можешь управлять из другого кода. Нужны два отдельных пространства имён в MAIN world: window.JZ (хелперы действий) и window.JUSTZIX (логгер). У каждого свой жизненный цикл, своя цель, и они намеренно не смешиваются.

Почему два пространства имён, а не одно

Логгер (только запись, диспатч в Output Console) и адресуемость DOM (чтение/манипуляция элементами, которые уже живут в DOM страницы) — это две разные семантики. Упаковать их вместе означало бы смешать ответственности. Пользователь, читающий код, видит JUSTZIX.log(...) и знает: «это логгер». Видит document.querySelector('[data-jz-action-id="x"]') и знает: «это DOM-запрос». Кроме того — нативный DOM API + data-* атрибуты всегда выигрывают у проприетарной обёртки (работает с инспектором DevTools, со сторонними библиотеками, с «копировать-вставить» из интернета).

Идемпотентно — установка управляется по версии (_jzVersion для JZ, флаг хука для JUSTZIX), так что обновления расширения не перезаписывают пространства имён посреди сессии.

Полная поверхность API

// ============================================================
// window.JZ — Хелперы действий
// Работает с элементами data-jz-action-id в DOM.
// Может быть занят скриптами страницы → запасной вариант: нативный DOM-запрос.
// ============================================================
JZ.action(labelOrId)     // Элемент по метке ИЛИ id. Регистронезависимо для метки.
JZ.actionById(id)        // Элемент по data-jz-action-id. Нет фолбэка на метку.
JZ.actions()             // Массив всех action-элементов в DOM.
JZ.labels()              // Массив меток (оригинальный регистр).
JZ.click(labelOrId)      // Программный клик. Для <select> выбирает первую опцию.
                          // Возвращает true/false.
JZ.value(labelOrId)      // Текущее значение действия (string или null).
JZ.setValue(labelOrId, value)  // Программный сеттер + диспатч input и change.
JZ.bars()                // Массив всех .jz-actions-bar в DOM.
JZ.barById(id)           // Панель по data-jz-bar-id.
JZ.floatingBtn()         // Элемент плавающей кнопки JustZix (когда активна).

// ============================================================
// window.JUSTZIX — Логгер (с v2.13.73, основной алиас с v2.13.76)
// Диспатчит в Output Console (kind='jz'); НЕ перенаправляет в нативный console.*.
// Брендовое имя = пренебрежимо малый риск конфликта. Работает везде.
// ============================================================
JUSTZIX.log(...args)
JUSTZIX.warn(...args)
JUSTZIX.error(...args)
JUSTZIX.info(...args)
JUSTZIX.debug(...args)

// Алиасы того же API:
window.__JUSTZIX__       // всегда установлен (обратная совместимость с v2.13.72-75)
window.JZ                // тоже, только когда не занят — более короткий ярлык

// Запасной вариант, когда window.JZ занят страницей (например, Google Ads):
// → нет эквивалента JUSTZIX.click(); используй нативный DOM.
document.querySelector('[data-jz-action-id="..."]').click();

Сценарий 1 — кнопка нажимает другую кнопку

У тебя есть действия «Login → Dashboard → Статистика». Три отдельные кнопки на панели действий. Добавь четвёртую «🚀 Quick», которая выполняет все три по очереди:

// Действие BUTTON «Quick» — поле кода:
JZ.click('Login');
await new Promise(r => setTimeout(r, 800));
JZ.click('Dashboard');
await new Promise(r => setTimeout(r, 500));
JZ.click('Статистика');
JUSTZIX.log('Поток Quick завершён — 3 клика в 1');

Бонус: этот скрипт ничего не знает о странице, он знает только свои действия JustZix. Меняй селекторы внутри «Login» / «Dashboard» — «Quick» продолжает работать, потому что вызывает их по метке.

Сценарий 2 — слайдер управляет CSS-переменной

Действие SLIDER «Яркость» (диапазон 50-150, по умолчанию 100). В его поле «Code»:

// Слайдер выполняет этот код при каждом изменении.
// `value` — это extraVar, внедряемая расширением (с v2.12.2).
document.documentElement.style.setProperty('--brightness', value + '%');

Теперь в другом действии (BUTTON «Reset») можно программно установить значение слайдера:

JZ.setValue('Яркость', 100);  // Слайдер прыгает на 100, CSS-переменная обновлена, яркость восстановлена.
JUSTZIX.log('Яркость восстановлена на 100%');

То же касается TOGGLE3 (трёхпозиционные переключатели вроде «Dev / Staging / Prod»): JZ.setValue('Окружение', 'staging') активирует это конкретное состояние и выполняет его код.

Сценарий 3 — Output Console как «блокнот»

Output Console (с v2.13.66) — это pane, перехватывающий весь вывод console.log со страницы. Страницы вроде Gmail забивают консоль сотнями строк в секунду. Фильтры по строкам помогают, но есть приём лучше: пиши только свои сообщения через JUSTZIX.log, затем переведи pane в режим [J] (Just JustZix).

// В действии «Проверка корзины»: логируй только ТВОИ сообщения, без шума страницы.
const items = document.querySelectorAll('.cart-item');
JUSTZIX.log(`В корзине ${items.length} товаров`);
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}`);

Pane Output Console в режиме [J] показывает ТОЛЬКО эти 3 строки — полностью чисто, идеально для QA-тулбара или контекста, обращённого к клиенту.

А если у страницы уже есть window.JZ?

Логгер работает всегда — у JUSTZIX.log() брендовое имя (пренебрежимо малый риск конфликта), и он основной. Кроме того window.__JUSTZIX__ всегда установлен как запасной алиас. Конфликт по window.JZ касается только хелперов действий — и даже тогда у тебя есть нативный выход.

Некоторые сайты (например, Google Ads) имеют свой window.JZ. JustZix это обнаруживает: если window.JZ уже существует при установке логгера, расширение не перезаписывает API страницы и сообщает об этом в приветственном сообщении Output Console. Короткий ярлык JZ остаётся зарезервированным за страницей — используй JUSTZIX для логирования и нативный DOM для действий:

// Логгер: всегда JUSTZIX (работает даже когда JZ занят страницей)
JUSTZIX.log('Корзина обработана');

// Клик по действию: когда window.JZ занят → используй нативный DOM вместо JZ.click()
document.querySelector('[data-jz-action-id="actionId"]').click();
// Или по data-jz-key (метка в верхнем регистре):
document.querySelector('.jz-actions-bar [data-jz-key="LOGIN"]').click();

Это намеренный дизайн: data-jz-action-* + querySelector — нативный паттерн — работает с инспектором DevTools, со сторонними библиотеками, с «копировать-вставить» из интернета. JZ.click() — синтаксический сахар — необязательный уровень косвенности, который можно пропустить, когда он недоступен.

Ловушки

• JZ.click() на INPUT/TEXTAREA просто кликает их, не меняет их значение. Чтобы установить текст: JZ.setValue('Поиск', 'foo'). У других типов (button, select, toggle3, slider) есть разумный дефолт для клика.
• JZ.value()/setValue() стали полнее с v2.13.33. Более старые версии не имели значения слайдера в датасете — если видишь null для слайдера, проверь версию расширения.
• Поиск по метке регистронезависим, но поиск по ID регистрозависим. Рекомендуется: держись меток (твоих), а не ID (автогенерируемых).
• JUSTZIX.log НЕ перенаправляет в консоль DevTools. Это намеренно — мы хотим отдельный канал для скриптов JustZix. Если хочешь DevTools — используй обычный console.log.
• JS Console перехватывает только трафик в стиле DevTools, не JUSTZIX.log автоматически. «console.log('hi')» в JS Console работает как всегда; «JUSTZIX.log('hi')» в JS Console НЕ появится в Output Console, если у тебя нет активного pane Output Console в режиме [J] или [C+J].
• Нет JUSTZIX.click() или подобного. Логгер и хелперы действий — отдельные пространства имён по выбору. Когда страница занимает window.JZ, ты активируешь действия через нативный DOM (querySelector + data-jz-action-*) — это паттерн, а не баг.

Что делать дальше

Это завершает мини-серию об окнах JustZix во фронтенде:

• CSS pane — живой редактор CSS во вкладке
• JS Console — REPL с историей ↑↓
• JS pane — Run-on-demand
• window.JZ helpers (эта статья) — программный API

Всё вместе — это мини-IDE внутри каждой вкладки браузера, с мини-API для управления твоими кнопками. Установи JustZix и попробуй сам — полностью бесплатно, без аккаунта, без сервера.