Перейти к основному содержимому

Разработка пользовательских компонентов экранных форм и JavaScript-библиотек

Вы можете расширять функциональность Атомкод самостоятельно разработанными JavaScript-библиотеками и новыми компонентами экранных форм. Код этих артефактов вы разрабатываете на JavaScript в виде ES-модулей JavaScript. Разработанные компоненты вы сможете добавлять на экранные формы только в кодовом режиме Редактора Форм.

О ES-модуле JavaScript​

ES-модуль — стандарт модулей в JavaScript, введенный спецификацией ECMAScript 2015 (ES6). ES-модули представляют способ организации и разделения кода на отдельные файлы, каждый из которых является независимым модулем.

ES-модули позволяют экспортировать определенные части своего содержимого, например, константы, переменные, функции и классы, чтобы другие ES-модули могли их импортировать и использовать. В ES-модулях существуют именованный и неименованный (экспорт по умолчанию) способы экспорта.

Именованный экспорт позволяет экспортировать несколько сущностей (функций, переменных, объектов) из ES-модуля, при этом каждая из них имеет уникальное имя. Для именованного экспорта используется ключевое слово export перед объявлением сущности. Если нужно экспортировать нескольких сущностей, оператор экспорта пишут в отдельной строке, а в фигурных скобках указывают имена экспортируемых сущностей.

Следующий блок кода демонстрирует именованный экспорт функции и константы в ES-модуле math.js.

ES-модуль math.js
export function add(a, b) {
  return a + b;
}

export const PI = 3.14159;

Для импорта сущности из другого ES-модуля используется ключевое слово import. При импорте именованных экспортов необходимо указывать имена экспортированных сущностей. Можно импортировать определенные экспортируемые сущности или целый модуль. При импорте сущностей, для которых использовался именованный экспорт, необходимы фигурные скобки.

Следующий блок кода демонстрирует импорт функции и константы из ES-модуля math.js, которые были экспортированы.

ES-модуль app.js
import { add, PI } from './math.js';
console.log(add(2, 3)); // вывод в консоль браузера числа 5
console.log(PI); // вывод в консоль браузера числа 3.14159

Экспорт по умолчанию позволяет экспортировать только одну сущность из ES-модуля. Для экспорта по умолчанию используются ключевые слова export default.

Следующий блок кода демонстрирует экспорт по умолчанию из ES-модуля main.js.

ES-модуль main.js
const greetings = 'Hello!';
export default greetings;

Имя импортированной сущности, экспортированной с помощью ключевых слов default export, может быть указано произвольно, а фигурные скобки не нужны.

Следующий блок кода демонстрирует импорт сущности, экспортируемой по умолчанию из ES-модуля main.js

ES-модуль myapp.js
import ciao from './main.js'; // имя сущности может быть выбрано произвольно
console.log(ciao); // вывод в консоль браузера строки  'Hello!'

Внедрение ES-модулей в Атомкод​

В проекте DevTools каждый ES-модуль описывается js-файлом в папке modules. Перед началом разработки кода ES-модуля необходимо создать js-файл.

При разработке кода ES-модуля можно использовать следующие инструменты:

  • js-редактор, встроенный в DevTools.

    При выборе js-файла в проекте DevTools js-редактор открывается автоматически и позволяет использовать синтаксис JavaScript и глобальный объект window браузера. В js-редакторе синтаксис JSX недоступен, однако возможно использовать React как библиотеку, что делает доступным вызовы вида React.createElement().

  • Интегрированная среда разработки, IDE (integrated development environment).

    В качестве IDE рекомендуется использовать Visual Studio Code или другую знакомую вам IDE.

    Содержимое полученного в результате сборки в IDE js-файла необходимо скопировать и вставить в предварительно созданный js-файл.

Описание разработанного ES-модуля необходимо добавить в файл Module.mdmodules в папке modulesпроекта DevTools. Файл Module.mdmodules содержит массив объектов, каждый из которых имеет следующие поля:

  • name: имя JavaScript-библиотеки или компонента экранной формы. Это имя используется для вызова в файле *.mdcontainer.
  • type: тип разработанного артефакта — значение library для описания JavaScript-библиотеки или control для описания компонента экранной формы.
  • path: путь к js-файлу ES-модуля относительно корневой папки проекта с префиксом static-content/. Если разработанный артефакт представлен несколькими ES-модулями, описывающими функциональность разработанного артефакта, в поле path указывается путь к js-файлу, содержащему экспорты этих ES-модулей.

Следующий блок кода демонстрирует пример содержимого файла Module.mdmodules. В файле перечислены два ES-модуля, один из которых описывает JavaScript-библиотеку, а другой описывает компонент экранной формы.

[
  { "name": "myLib", "type": "library", "path": "static-content/test/library.js" },
  { "name": "myContr", "type": "control", "path": "static-content/Main/myControl.js" },
]

Разработка JavaScript-библиотеки​

Вы можете разрабатывать JavaScript-библиотеку как во встроенном в DevTools js-редакторе, так и в IDE. При разработке в IDE JavaScript-библиотека должна быть собрана как ES-модуль.

Следующий блок кода демонстрирует пример ES-модуля, описывающего JavaScript-библиотеку.

class SomeLibrary{
  func1() {
    return 1
  }

  func2() {
    return 2
  }
}

export default new SomeLibrary()

Следующий блок кода демонстрирует вызов метода func1() JavaScript-библиотеки в секции Scripts файла *.mdcontainer. Строка вызова включает следующие элементы:

  • window: глобальный объект браузера;
  • myLib: имя вызываемой JavaScript-библиотеки;
  • default: способ экспорта по умолчанию;
  • func1: имя вызываемого метода.
Scripts={[
    () => {
      console.log('1', window.myLib.default.func1())
    }
  ]}

Разработка компонента экранной формы​

Вы можете разрабатывать компонент экранной формы как во встроенном в DevTools js-редакторе, так и в IDE. Однако, вне зависимости от инструмента разработки компонента экранной формы в коде ES-модуля должны присутствовать блоки следующего вида:

Блок экспорта реализации компонента и паспорта компонента
  export {
    impl as Implementation, // описывает поведение компонента экранной формы
    pass as passport // описывает паспорт компонента экранной формы согласно принятому в Атомкод стандарту
  };
Блок описания паспорта компонента
  const pass = {
    ControlType: "CustomControl",
    ControlId: "CustomControl",
    Properties: {}
  };

Более подробная информация о паспорте компонента экранной формы содержится в соответствующей статье.

Следующий блок кода демонстрирует содержимое ES-модуля, описывающего компонент экранной формы.

function Greeting(props) {
  return React.createElement(
    'div',
    { className: 'greeting' },
    React.createElement(
      'h1',
      null,
      'Привет, ',
      props.name
    ),
    React.createElement(
      'p',
      null,
      'Добро пожаловать на наш сайт!'
    )
  );
}

const passport = {
  ControlType: 'CustomControl',
  ControlId: 'Example',
  Properties: {}
}

export {passport, Greeting as Implementation}

Предположим, что блок кода, показанный выше, расположен в файле module.js. Также предположим, что файл Module.mdmodules содержит запись следующего вида:

[{"name": "Example", "type": "control", "path": "static-content/test/module.js"}]

Тогда блок кода описания экранной формы, на которой используется компонент Example, записывается следующим образом:

<Group CSS={["pt-16", "pb-16"]} Height="100%">
    <Example></Example>
</Group>

Если вы разрабатываете компонент экранной формы в IDE, используйте шаблонный код проекта на React. Шаблонный код позволяет получить JavaScript-код ES-модуля, который принят в Атомкод. В результате сборки js-файл формируется в папке dist проекта. Приложенные в этой статье файлы webpackControl.zip и viteControl.zip содержат шаблонный код проектов согласно сборщикам проектов Webpack и Vite.

Шаблонный код проекта viteControl содержит файл конфигурации сборщика Vite vite.config.ts на языке TypeScript, модифицированный с учетом применения ES-модуля в Атомкод, а также в папке src содержит следующие файлы:

  • passport.ts: пример описания паспорта компонента.
  • index.tsx: экспорт реализации компонента и его паспорта.