#JS Block

#Вступ

JS Block — це високогнучкий блок для кастомного рендерингу, що дозволяє безпосередньо писати JavaScript-скрипти для генерації інтерфейсів, прив'язування подій, виклику API даних або інтеграції сторонніх бібліотек. Він ідеально підходить для сценаріїв персоналізованої візуалізації, тимчасових експериментів та легких розширень, які важко реалізувати за допомогою вбудованих блоків.

#API середовища виконання

Контекст виконання JS Block вже містить вбудовані можливості, які можна використовувати безпосередньо:

• ctx.element: DOM-контейнер блоку (безпечно обгорнутий як ElementProxy), що підтримує innerHTML, querySelector, addEventListener тощо;
• ctx.requireAsync(url): асинхронно завантажує бібліотеку AMD/UMD за URL-адресою;
• ctx.importAsync(url): динамічно імпортує ESM-модуль за URL-адресою;
• ctx.openView: відкриває налаштований вигляд (спливаюче вікно/бічна панель/сторінка);
• ctx.useResource(...) + ctx.resource: отримує доступ до даних як до ресурсу;
• ctx.i18n.t() / ctx.t(): вбудована функція інтернаціоналізації;
• ctx.onRefReady(ctx.ref, cb): рендерить після готовності контейнера, щоб уникнути проблем із послідовністю;
• ctx.libs.React / ctx.libs.ReactDOM / ctx.libs.antd / ctx.libs.antdIcons / ctx.libs.dayjs: вбудовані загальні бібліотеки, такі як React, ReactDOM, Ant Design, іконки Ant Design та dayjs, для рендерингу JSX та обробки часу. (ctx.React / ctx.ReactDOM / ctx.antd залишаються для сумісності.)
• ctx.render(vnode): рендерить React-елемент, HTML-рядок або DOM-вузол у контейнер за замовчуванням ctx.element; багаторазові виклики повторно використовують той самий React Root і перезаписують наявний вміст контейнера.

#Додавання блоку

Ви можете додати JS Block на сторінку або у спливаюче вікно.

#Редактор та фрагменти коду

Редактор скриптів JS Block підтримує підсвічування синтаксису, підказки про помилки та вбудовані фрагменти коду (Snippets), що дозволяє швидко вставляти типові приклади, такі як рендеринг діаграм, прив'язка подій до кнопок, завантаження зовнішніх бібліотек, рендеринг компонентів React/Vue, часові шкали, інформаційні картки тощо.

• Snippets: Відкриває список вбудованих фрагментів коду. Ви можете шукати та одним кліком вставляти вибраний фрагмент у поточну позицію курсору в редакторі коду.
• Run: Безпосередньо запускає код у поточному редакторі та виводить журнали виконання на нижню панель Logs. Підтримує відображення console.log/info/warn/error, а помилки будуть підсвічені та матимуть посилання на конкретний рядок і стовпець.

Крім того, у верхньому правому куті редактора ви можете безпосередньо викликати AI-співробітника «Фронтенд-інженер · Nathan», який допоможе вам написати або змінити скрипти на основі поточного контексту. Потім ви можете одним кліком «Apply to editor» (Застосувати до редактора) і запустити код, щоб побачити результат. Детальніше дивіться:

• AI-співробітник · Nathan: Фронтенд-інженер

#Середовище виконання та безпека

• Контейнер: Система надає скрипту безпечний DOM-контейнер ctx.element (ElementProxy), який впливає лише на поточний блок і не заважає іншим областям сторінки.
• Пісочниця: Скрипт виконується в контрольованому середовищі. window/document/navigator використовують безпечні проксі-об'єкти, що дозволяє використовувати типові API, але обмежує ризиковані дії.
• Повторний рендеринг: Блок автоматично повторно рендериться, коли його приховують, а потім знову показують (щоб уникнути повторного виконання початкового скрипту монтування).

#Типові випадки використання (спрощені приклади)

#1) Рендеринг React (JSX)

const { Button } = ctx.libs.antd;
ctx.render(
  <div style={{ padding: 12 }}>
    <Button type="primary" onClick={() => ctx.message.success(ctx.t('Натиснуто!'))}>
      {ctx.t('Натиснути')}
    </Button>
  </div>
);

#2) Шаблон API-запиту

const resp = await ctx.api.request({ url: 'users:list', method: 'get', params: { pageSize: 10 } });
ctx.message.success(ctx.t('Запит завершено'));
console.log(ctx.t('Дані відповіді:'), resp?.data);

#3) Завантаження ECharts та рендеринг

const container = document.createElement('div');
container.style.height = '360px';
container.style.width = '100%';
ctx.element.replaceChildren(container);
const echarts = await ctx.requireAsync('https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js');
if (!echarts) throw new Error('ECharts not loaded');
const chart = echarts.init(container);
chart.setOption({ title: { text: ctx.t('ECharts') }, xAxis: {}, yAxis: {}, series: [{ type: 'bar', data: [5, 12, 9] }] });
chart.resize();

#4) Відкриття вигляду (бічної панелі)

const popupUid = ctx.model.uid + '-1';
await ctx.openView(popupUid, { mode: 'drawer', title: ctx.t('Приклад бічної панелі'), size: 'large' });

#5) Зчитування ресурсу та рендеринг JSON

const resource = ctx.createResource('SingleRecordResource');
resource.setDataSourceKey('main');
resource.setResourceName('users');
await resource.refresh();
ctx.render(`<pre style="padding:12px;background:#f5f5f5;border-radius:6px;">${JSON.stringify(resource.getData(), null, 2)}</pre>`);

#Важливі примітки

• Для завантаження зовнішніх бібліотек рекомендується використовувати надійні CDN.
• Рекомендації щодо використання селекторів: Віддавайте перевагу використанню селекторів за class або атрибутом [name=...]; уникайте використання фіксованих id, щоб запобігти конфліктам стилів або подій через дублювання id у кількох блоках/спливаючих вікнах.
• Очищення подій: Блок може рендеритися кілька разів, тому перед прив'язкою подій їх слід очищати або дедуплікувати, щоб уникнути повторного спрацьовування. Можна використовувати підхід «спочатку видалити, потім додати», одноразові слухачі або додавати прапорці для запобігання дублюванню.

#Пов'язані документи

• Змінні та контекст
• Правила взаємодії
• Вигляди та спливаючі вікна