#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 Icons и dayjs для рендеринга JSX и работы со временем. (ctx.React / ctx.ReactDOM / ctx.antd сохранены для совместимости.);
• ctx.render(vnode): Рендерит элемент React, HTML-строку или DOM-узел в контейнер по умолчанию ctx.element; многократные вызовы будут повторно использовать один и тот же React Root и перезаписывать существующее содержимое контейнера.

#Добавление блока

Вы можете добавить JS Block на страницу или во всплывающее окно.

#Редактор и сниппеты

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

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

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

• AI-помощник · Натан: Фронтенд-инженер

#Среда выполнения и безопасность

• Контейнер: Система предоставляет безопасный 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 при использовании нескольких блоков или всплывающих окон.
• Очистка событий: Поскольку блок может перерисовываться несколько раз, прослушиватели событий следует очищать или дедуплицировать перед привязкой, чтобы избежать повторных срабатываний. Вы можете использовать подход «сначала удалить, затем добавить», одноразовый прослушиватель или флаг для предотвращения дубликатов.

#Связанные документы

• Переменные и контекст
• Правила связывания
• Представления и всплывающие окна