#Поле JS

#Введение

Поле JS используется для пользовательского рендеринга содержимого в позиции поля с помощью JavaScript. Оно обычно применяется в блоках деталей, для элементов форм, доступных только для чтения, или в табличных столбцах как «Другие пользовательские элементы». Идеально подходит для персонализированного отображения, комбинирования производной информации, рендеринга значков статуса, форматированного текста или диаграмм.

#Типы

• Только для чтения: Используется для нередактируемого отображения, считывает ctx.value для вывода.
• Редактируемое: Используется для пользовательских взаимодействий ввода. Оно предоставляет ctx.getValue()/ctx.setValue(v) и событие контейнера js-field:value-change для облегчения двусторонней синхронизации со значениями формы.

#Примеры использования

• Только для чтения

  • Блок деталей: Отображение содержимого только для чтения, такого как результаты вычислений, значки статуса, фрагменты форматированного текста, диаграммы и т.д.
  • Табличный блок: Используется как «Другой пользовательский столбец > Поле JS» для отображения только для чтения (если вам нужен столбец, не привязанный к полю, используйте JS Column).

• Редактируемое

  • Блок формы (CreateForm/EditForm): Используется для пользовательских элементов управления вводом или составных полей ввода, которые проверяются и отправляются вместе с формой.
  • Подходит для сценариев, таких как: компоненты ввода из внешних библиотек, редакторы форматированного текста/кода, сложные динамические компоненты и т.д.

#API контекста выполнения

Код поля JS во время выполнения может напрямую использовать следующие возможности контекста:

• ctx.element: DOM-контейнер поля (ElementProxy), поддерживающий innerHTML, querySelector, addEventListener и т.д.
• ctx.value: Текущее значение поля (только для чтения).
• ctx.record: Текущий объект записи (только для чтения).
• ctx.collection: Метаинформация о коллекции, к которой принадлежит поле (только для чтения).
• ctx.requireAsync(url): Асинхронная загрузка библиотеки AMD/UMD по URL.
• ctx.importAsync(url): Динамический импорт модуля ESM по URL.
• ctx.openView(options): Открытие настроенного представления (всплывающее окно/выдвижная панель/страница).
• 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; повторный рендеринг будет повторно использовать Root и перезаписывать существующее содержимое контейнера.

Особенности редактируемого типа (JSEditableField):

• ctx.getValue(): Получение текущего значения формы (приоритет отдается состоянию формы, затем используется резервное значение из свойств поля).
• ctx.setValue(v): Установка значения формы и свойств поля, поддерживая двустороннюю синхронизацию.
• Событие контейнера js-field:value-change: Срабатывает при изменении внешнего значения, что позволяет скрипту легко обновлять отображение ввода.

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

Редактор скриптов поля JS поддерживает подсветку синтаксиса, подсказки об ошибках и встроенные фрагменты кода (Snippets).

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

Вы также можете генерировать код с помощью AI-сотрудника:

• AI-сотрудник · Натан: Frontend-разработчик

#Примеры использования

#1) Базовый рендеринг (чтение значения поля)

ctx.render(<span className="nb-js-field">{String(ctx.value ?? '')}</span>);

#2) Использование JSX для рендеринга компонента React

const { Tag } = ctx.libs.antd;
ctx.render(
  <div style={{ padding: 4 }}>
    <Tag color={ctx.value ? 'green' : 'default'}>{String(ctx.value ?? '')}</Tag>
  </div>
);

#3) Загрузка сторонних библиотек (AMD/UMD или ESM)

// AMD/UMD
const dayjs = await ctx.requireAsync('https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js');
ctx.render(<span>{dayjs().format('YYYY-MM-DD HH:mm')}</span>);

// ESM
const { default: he } = await ctx.importAsync('https://cdn.jsdelivr.net/npm/he/+esm');
ctx.render(<span>{he.encode(String(ctx.value ?? ''))}</span>);

#4) Нажатие для открытия всплывающего окна/выдвижной панели (openView)

ctx.element.innerHTML = `<a class="open-detail">Посмотреть детали</a>`;
const a = ctx.element.querySelector('.open-detail');
const tk = ctx.collection?.getFilterByTK?.(ctx.record);
a?.addEventListener('click', async () => {
  await ctx.openView('target-view-uid', {
    navigation: false,
    mode: 'drawer',
    dataSourceKey: ctx.collection?.dataSourceKey,
    collectionName: ctx.collection?.name,
    filterByTk: tk,
  });
});

#5) Редактируемый ввод (JSEditableFieldModel)

// Рендеринг простого поля ввода с помощью JSX и синхронизация значения формы
function InputView() {
  return (
    <input
      className="nb-js-editable"
      style={{ width: '100%', padding: '4px 8px' }}
      defaultValue={String(ctx.getValue() ?? '')}
      onInput={(e) => ctx.setValue(e.currentTarget.value)}
    />
  );
}

// Синхронизация ввода при изменении внешнего значения (необязательно)
ctx.element.addEventListener('js-field:value-change', (ev) => {
  const el = ctx.element.querySelector('.nb-js-editable');
  if (el) el.value = ev.detail ?? '';
});

ctx.render(<InputView />);

#Примечания

• Рекомендуется использовать доверенные CDN для загрузки внешних библиотек и предусмотреть запасные варианты для сценариев сбоя (например, if (!lib) return;).
• Для селекторов рекомендуется отдавать предпочтение class или [name=...], избегая использования фиксированных id, чтобы предотвратить дублирование id в нескольких блоках или всплывающих окнах.
• Очистка событий: Поле может быть перерисовано несколько раз из-за изменений данных или переключения представлений. Перед привязкой события его следует очистить или дедуплицировать, чтобы избежать повторных срабатываний. Можно использовать подход «сначала удалить, затем добавить».