#JS Field

#Вступ

JS Field використовується для кастомного відображення вмісту в позиції поля за допомогою JavaScript. Його зазвичай застосовують у блоках деталей, полях форм лише для читання або як «Інші кастомні елементи» в стовпцях таблиць. Він підходить для персоналізованого відображення, комбінування похідної інформації, відображення значків статусу, розширеного тексту або діаграм.

#Типи

• Лише для читання: Використовується для нередагованого відображення, зчитує ctx.value для відображення виводу.
• Редагований: Використовується для кастомних взаємодій з введенням. Він надає ctx.getValue()/ctx.setValue(v) та подію контейнера js-field:value-change для полегшення двосторонньої синхронізації зі значеннями форми.

#Сценарії використання

• Лише для читання

  • Блок деталей: Відображення вмісту лише для читання, такого як результати обчислень, значки статусу, фрагменти розширеного тексту, діаграми тощо.
  • Блок таблиці: Використовується як «Інший кастомний стовпець > JS Field» для відображення лише для читання (якщо вам потрібен стовпець, не прив'язаний до поля, будь ласка, використовуйте JS Column).

• Редагований

  • Блок форми (CreateForm/EditForm): Використовується для кастомних елементів керування введенням або складених полів введення, які перевіряються та надсилаються разом із формою.
  • Підходить для таких сценаріїв: компоненти введення із зовнішніх бібліотек, редактори розширеного тексту/коду, складні динамічні компоненти тощо.

#API контексту під час виконання

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

• 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 Field підтримує підсвічування синтаксису, підказки про помилки та вбудовані фрагменти коду (Snippets).

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

Ви також можете генерувати код за допомогою AI-співробітника:

• AI-співробітник · Nathan: 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 у кількох блоках/спливаючих вікнах.
• Очищення подій: Поле може бути перемальовано кілька разів через зміни даних або перемикання вигляду. Перед прив'язкою події її слід очистити або дедуплікувати, щоб уникнути повторного спрацьовування. Можна використовувати підхід «спочатку remove, потім add».