Подключение внешних компонентов для использования на экранных формах

Вы можете дополнить набор компонентов экранных форм Платформы самостоятельно разработанными компонентами. Код этих компонентов вы разрабатываете на JavaScript. Разработанные компоненты вы сможете добавлять на экранные формы только в кодовом режиме Редактора Форм.

Процедура добавления компонента экранной формы заключается в создании папки src/project/controls/<имя компонента> в папке с исходным кодом FrontendProject дистрибутива Платформы и создании в этой папке следующих файлов:

• index.js: паспорт компонента описывает свойства, определяет доступные обработчики событий для подключаемого компонента.
• <имя компонента>.js: код подключаемого компонента.

Описание полей паспорта компонента

interface IExample {
  Script?: string;
  States: string;
  Value: string;
  Coordinates?: string;
}

interface PosValue {
  Value: string;
  Description: string;
}

interface IProperty {
  Contract: string;
  Description: string;
  ValueType: string;
  DevValue: any;
  DefaultValue: any;
  Type: string;
  PosValues?: PosValue[];
  Impact?: string[];
}

export interface IControl {
// метод получения дочерних компонентов
  GetChildControls?: (Control: any, Metadata: any) => any[];
  
  // Признак отрисовки актуального состояния дерева компонентов, управлящих состоянием дочерних компонентов
  ForceUpdate?: boolean;
  // уникальный идентификатор для CMS
  ControlType: string;
  // уникальный идентификатор реализации компонента
  ControlId: string;
  // описание от UI-проектировщиков или программистов о назначении компонента
  Description: string;
  // краткое описание компонента
  ShortDescription?: string;
  // путь к файлу значка компонента .../controls/static/ControlsIcons/icons
  Icons?: {
    Icon16?: string;
    Icon48?: string;
  };
  // ссылка на нарисованный интерфейс компонента (figma)
  UI: string;
  // минимально рабочий пример вызова
  Sample: string;
  // описание допустимых дочерних компонентов
  // при запрете иметь дочерние компоненты указывается пустой массив,
  // при допустимости любого компонента в качестве дочернего указываются имена компонентов или символ "*"
  ChildControls: Array<string>;
  // Признак допустимости записи компонента <Control />; используеся в DevTools
  SelfClosing: boolean;
  // Признак подстановки тега автозакрытия <Control /> по умолчанию; используеся в DevTools
  SelfClosingPrefered: boolean;
  // Признак отображения компонента в списке; используеся в DevTools
  Hidden?: boolean;
  // свойства компонента
  Properties: {
    [propName: string]: IProperty;
  };
  // пример компонента для автогенерации документации
  Examples: IExample;
  // Описание изменений компонента при переходе с версии Платформы 0.6 на текущую версию
  MigrationSteps: string;
  // Устаревшее поле
  GetPropertiesMetadata?: any;
  // Страница с описанием от технических писателей, см. пример в checkbox
  Info?: string;
  DevTools?: object;
  // Признак новизны компонента
  IsNew?: boolean;
}

export interface IRepeater extends IControl {
  // метод получения дочерних компонентов
  GetChildControls(Control: any, Metadata: any): void;
}

//3D types

export enum Viewer3dMode {
  normal = 'Normal',
  compact = 'Compact'
}

export enum CameraOrientationType {
  up = 'Up',
  down = 'Down',
  left = 'Left',
  right = 'Right',
  front = 'Front',
  rear = 'Rear',
  iso = 'ISO',
  default = ''
}

export enum CameraProjectionType {
  perspective = 'Perspective',
  orthogonal = 'Orthogonal',
  default = ''
}

export enum VisibilityObjectsType {
  HideSelected = 'HideSelected',
  ShowSelected = 'ShowSelected',
  ShowAll = 'ShowAll',
  Default = ''
}

export enum CuttingPlaneType {
  threePointSlice = 'ThreePointSlice',
  onePointPlaneXZ = 'OnePointPlaneXZ',
  onePointPlaneXY = 'OnePointPlaneXY',
  onePointPlaneYZ = 'OnePointPlaneYZ',
  default = ''
}

//3D types 

Пример паспорта компонента Button

import CONTRACTS from '../../../constants/CONTRACTS';
import commonProperties from '../../../core/Control/commonProperties';
import ValueTypes from '../../../constants/ValueTypes';
import PropertyTypes from '../../../constants/PropertyTypes';

import icons from '../../static/ControlsIcons';

const IButton = {
  ControlType: 'Button',
  ControlId: 'Button',
  ShortDescription: 'Отображает кнопку',
  Icons: {
    Icon16: icons.button16,
    Icon48: icons.button48,
  },
  Description: `

Согласно дизайн-системе Платформы и в зависимости от выполняемой функции имеет несколько режимов работы  
и вариантов стилизации. 

~~~jsx
  <Button
    Text="Primary" 
    Style="Primary" 
  />
~~~
  `,
  UI: 'https://www.figma.com/design/wMSSQurkeAlLC5ap8w92j8/Components-[Web]?node-id=2517-431502&t=OEb5H6JiPQwt1D26-0',
  Sample: `
    <Button Text="foo" OnClick={() => {}} />
  `,
  ChildControls: ['Icon', "Text", "Group"],
  SelfClosing: true,
  SelfClosingPrefered: true,
  Properties: {
    ...commonProperties,
    FullWidth: {
      Contract: CONTRACTS.Optional,
      Description: 'Признак автоматически назначаемой ширины кнопки согласно ширине родительского компонента',
      ValueType: ValueTypes.Boolean,
      DevValue: false,
      DefaultValue: false,
      Type: PropertyTypes.Value,
    },
    Text: {
      Contract: CONTRACTS.Optional,
      Description: 'Надпись на кнопке',
      ValueType: ValueTypes.String,
      DevValue: 'Button',
      DefaultValue: '',
      Type: PropertyTypes.Value,
    },
    OnClick: {
      Contract: CONTRACTS.Optional,
      Description: 'Обработчик события MouseClick',
      Type: PropertyTypes.Event,
      ValueType: ValueTypes.Undefined,
      DevValue: '() => ()',
      DefaultValue: null,
    },
    Disabled: {
      Contract: CONTRACTS.Optional,
      Description: 'Признак состояния компонента Отключен',
      ValueType: ValueTypes.Boolean,
      Type: PropertyTypes.Value,
      DevValue: false,
      DefaultValue: false,
    },
    Mode: {
      Contract: CONTRACTS.Optional,
      ValueType: ValueTypes.Enum,
      Description: 'Режим работы кнопки',
      Type: PropertyTypes.Value,
      PosValues: [
        {
          Value: 'Button',
          Description: 'По нажатию кнопки происходят только действия, описываемые в обработчике события',
        },
        {
          Value: 'Reset',
          Description:
            'По нажатию кнопки введенные на странице данные очищаются, и страница перезагружается',
        },
        {
          Value: 'Submit',
          Description: 'По нажатию кнопки данные на странице отправляются на сервер, и страница перезагружается',
        },
      ],
      DevValue: 'Button',
      DefaultValue: 'Button',
    },
    Style: {
      Contract: CONTRACTS.Optional,
      ValueType: ValueTypes.Enum,
      Description: 'Стиль кнопки согласно дизайн-системе Платформы',
      Type: PropertyTypes.Value,
      PosValues: [
        {
          Value: 'Primary',
          Description:
            'Используется для кнопки, выполняющей основное, ожидаемое, наиболее вероятное действие, например, Сохранить, Добавить, Применить. На странице или в окне приложения обычно используется единожды.',
        },
        {
          Value: 'Secondary',
          Description:
            'Используется при наличии нескольких равновероятных или равнозначных действий. На странице или в окне приложенияи может использоваться более одного раза.',
        },
        {
          Value: 'PrimaryGray',
          Description:
            'Используется для кнопки, выполняющей основное, ожидаемое, наиболее вероятное действие, например, Сохранить, Добавить, Применить. На странице или в окне приложения обычно используется единожды.',
        },
        {
          Value: 'Tertiary',
          Description:
            'Используется для кнопки, выполняющей дополнительное, менее приоритетное действие, чем действие, выполняемое по кнопке со стилем Primary, например, Отменить.',
        },
        {
          Value: 'PrimaryError',
          Description: 'Используется для кнопки, выполняющей наиболее ожидаемое, приоритетное деструктивное действие на странице или в окне приложения, например, Удалить.',
        },
        {
          Value: 'SecondaryError',
          Description:
            'Используется при наличии нескольких равновероятных или равнозначных деструктивных действий. На странице или в окне приложения может использоваться более одного раза.',
        },
        {
          Value: 'TertiaryError',
          Description:
            'Используется для кнопки, выполняющей деструктивное действие. Может использоваться вместо стиля Secondary Red.',
        },
        {
          Value: 'SecondaryGray',
          Description:
            'Используется по умолчанию при наличии нескольких действий с равным приоритетом, например, для кнопок на панели инструментов.',
        },
        {
          Value: 'TertiaryGray',
          Description:
            'Используется вместо стиля Secondary Gray, например, для кнопки рядом с кнопкой в стиле Primary — Отменить.',
        },
      ],
      DevValue: 'Primary',
      DefaultValue: 'Primary',
    },
  },
  DevTools: {
    DefaultCode: '<Button Text="Button"/>',
  },
  Examples: {
    States: '',
    Value: `<Group Mode="Column" Height="150px">
  <Group Mode="Row">
    <Group Mode="Column" Height="auto" Width="33%">
      <Text Value="Text" Mode="Medium_14" CSS={['ml-8']} />
      <Button
        CSS={['m-8']} 
        Text="Сохранить" 
        Style="Primary"
      />
    </Group>
    
</Group>
    `,
  },
  MigrationSteps: `
    Убраны Style: OutlinedPrimary, OutlinedSecondary, Plain
    Добавлены Style: Tertiary, PrimaryError, SecondaryError, TertiaryError, SecondaryGray, TertiaryGray
  `,
};

export default IButton;

Чтобы подключить разработанный компонент:

1. Откройте папку с исходным кодом FrontendProject дистрибутива Платформы.

2. Перейдите в папку src/project и создайте папку controls/<имя компонента>.

3. В папке controls/<имя компонента> создайте файлы index.js и <имя компонента>.js.

4. В файле project/controls/index.js импортируйте файлы, созданные согласно предыдущему пункту инструкции.

   Следующий пример демонстрирует подключение компонента с именем Sample:

   import SampleImpl from './Sample/Sample';
   import SamplePass from './Sample';

   В этот же файл добавьте блок кода согласно следующему шаблону:

   Controls: {
     implementations: {
       Sample: SampleImpl // из файла SampleImpl.js
     },
     passports: {
       Sample: SamplePass // из файла index.js
     }
    } 

5. В файл src/project/index.js добавьте следующую строку:

   import * as controls from './controls';

   В этом же файле найдите следующую строку:

   Controls: {},

   Замените эту строку на следующую строку:

   Controls: controls.default,

Обратитесь к DevOps-инженерам с просьбой об изменении Docker-контейнера nginxplatformdemo в экземпляре Платформы. После подтверждения об изменении Docker-контейнера вы можете добавлять разработанный компонент на экранные формы в кодовом режиме Редактора Форм.