Preparing search index...

    Миграция с устаревшего SDK

    Доступ к SDK через NPM-пакеты пространства @universe-platform признан устаревшим. Вместо этих пакетов следует использовать:

    • глобальную переменную window.Universe, или
    • пакет @universe-dg/sdk.

    Ниже приведены пояснения по миграции с устаревших пакетов и пошаговая инструкция по миграции.

    Пакет использовался как основная точка входа в SDK. Вместо него следует использовать Universe.Platform.

    import {Model} from '@universe-platform/sdk';

    class CustomModel extends Model.AbstractModel {}
    • Через window.Universe:
      class CustomModel extends window.Universe.Platform.Model.AbstractModel {}
      
    • Через пакет @universe-dg/sdk:
      import {Universe} from '@universe-dg/sdk';

      class CustomModel extends Universe.Platform.Model.AbstractModel {}

    Основная часть элементов @universe-platform/sdk перенесена в Universe.Platform и Universe.Vendor. Отдельные элементы не планируются к миграции и будут удалены. Ниже приведена полная таблица соответствия элементов пакета для миграции на новое API:

    Было Стало
    AbstractAttribute Universe.Platform.Meta.AbstractAttribute
    AbstractAttributesStore Будет удалено
    AbstractRecord Будет удалено
    AbstractSearchColumnsStore Universe.Platform.Search.AbstractSearchColumnsStore
    AbstractSearchPanelStore Universe.Platform.Search.AbstractSearchPanelStore
    AbstractSearchResultStore Universe.Platform.Search.AbstractSearchResultStore
    AbstractSearchStore Universe.Platform.Search.AbstractSearchStore
    Attribute Будет удалено
    backendPropertyManager Universe.Platform.Security.backendPropertyManager
    BulkOperationDescriptor Universe.Platform.BulkOperation.BulkOperationDescriptor
    BulkOperationParameterDescriptor Universe.Platform.BulkOperation.BulkOperationParameterDescriptor
    BulkOperationState Universe.Platform.BulkOperation.BulkOperationState
    BulkOperationStore Universe.Platform.BulkOperation.BulkOperationStore
    BulkOperationValuedParameter Universe.Platform.BulkOperation.BulkOperationValuedParameter
    CardStore Universe.Platform.Record.AbstractCardStore
    DataCard Будет удалено
    Dialog Universe.Platform.Toast.Dialog
    ICardErrorsData Universe.Platform.Record.ICardErrorsData
    i18n Universe.Platform.Locale.i18n
    IMetaAbstractAttribute Universe.Platform.Meta.IMetaAbstractAttribute
    IMetaComplexAttribute Universe.Platform.Meta.IMetaComplexAttribute
    IMetaModel Universe.Platform.Meta.IMetaModel
    Locales Universe.Platform.Locale.Locales
    MetaTypeGuards Universe.Platform.Meta.MetaTypeGuards
    Model Universe.Platform.Model
    NamespaceManager Universe.Platform.Namespace.NamespaceManager
    Network Universe.Platform.Network
    ResourceManager Universe.Platform.Security.ResourceManager
    RouterStore Universe.Platform.Router.routerStore
    SDK.Mobx Universe.Vendor.Mobx
    SDK.MobxReact Universe.Vendor.MobxReact
    SDK.React Universe.Vendor.React
    SDK['unidata/uikit'] Universe.Platform.Uikit
    SearchColumn Universe.Platform.Search.SearchColumn
    SearchHit Universe.Platform.Search.SearchHit
    SearchHitUtil Universe.Platform.Search.SearchHitUtil
    UdException Universe.Platform.Exception.UdException
    UdLogger Universe.Platform.Logger.UdLogger
    UniverseConfig Universe.Platform.Config.universeConfig
    UserLocale Universe.Platform.Locale.userLocale
    UserManager Universe.Platform.Security.UserManager
    ueModuleManager Universe.Platform.UserExit.userExitManager
    Utils Будет удалено
    UPathMetaStore Universe.Platform.Meta.UPathMetaStore
    UPathMetaUtil Universe.Platform.Meta.UPathMetaUtil
    UPathRecordUtil Universe.Platform.Record.UPathRecordUtil

    Пакет предоставлял компоненты UI kit. Вместо него следует использовать Universe.Platform.Uikit.

    import React from 'react';
    import {Button} from '@universe-platform/uikit';

    class CustomButton extends React.Component {
    override render() {
    return <Button>Click me</Button>;
    }
    }
    • Через window.Universe:
      class CustomButton extends window.Universe.Vendor.React.Component {
      override render() {
      return <window.Universe.Platform.Uikit.Button>Click me</window.Universe.Platform.Uikit.Button>;
      }
      }
    • Через пакет @universe-dg/sdk:
      import {Universe} from '@universe-dg/sdk';

      class CustomButton extends Universe.Vendor.React.Component {
      override render() {
      return <Universe.Platform.Uikit.Button>Click me</Universe.Platform.Uikit.Button>;
      }
      }

    Основная часть элементов из @universe-platform/uikit полностью соответствуют элементам в Universe.Platform.Uikit. Отдельные элементы не планируются к миграции и будут удалены. В таблице ниже приведены только те элементы, которые не совпадают напрямую (удалены или переименованы) и требуют особого внимания при миграции:

    Было Стало
    Alert Будет удалено
    Badge Будет удалено
    BaseIcon Будет удалено
    Bootstrap Будет удалено
    CardPanelGrid Universe.Platform.Uikit.CardPanel
    Col Будет удалено
    COLOR Будет удалено
    DateRangeTemplate Universe.Platform.Uikit.DateRangePickerDateRangeTemplate
    FIELD_MODE Будет удалено
    Form Будет удалено
    Grid Будет удалено
    Hierarchy Будет удалено
    HotKeyCallbackMap Будет удалено
    IColumn Universe.Platform.Uikit.TableColumn
    IDateTemplate Universe.Platform.Uikit.DatePickerDateTemplate
    IDropConfig Universe.Platform.Uikit.TreeNodeDropConfig
    IEditableListItem Будет удалено
    IEditableListItemComponentProps Будет удалено
    IFilterData Universe.Platform.Uikit.TableFilterData
    IFlatListItem Universe.Platform.Uikit.TreeFlatListItem
    IFieldCheckboxProps Universe.Platform.Uikit.FieldCheckboxProps
    IFieldInputProps Universe.Platform.Uikit.FieldInputProps
    IFieldNumberProps Universe.Platform.Uikit.FieldNumberProps
    IFieldProps Universe.Platform.Uikit.FieldProps
    IFieldSelectProps Universe.Platform.Uikit.FieldSelectProps
    IFieldTextAreaProps Universe.Platform.Uikit.FieldTextAreaProps
    IGroupOption Будет удалено
    IHeaderProps Будет удалено
    IListItem Будет удалено
    IMenuSiderProps Universe.Platform.Uikit.MenuSiderProps
    INodeProps Universe.Platform.Uikit.TreeNodeProps
    IOption Universe.Platform.Uikit.SelectOption
    IPropsBaseIcon Universe.Platform.Uikit.BaseIconProps
    IPropsIcon Universe.Platform.Uikit.IconProps
    ISelectPaginatedProps Universe.Platform.Uikit.SelectPaginatedProps
    ISelectProps Universe.Platform.Uikit.SelectProps
    ISortDireciton Universe.Platform.Uikit.TableSortDirection
    ISwitcherProps Universe.Platform.Uikit.SwitcherProps
    ITableProps Universe.Platform.Uikit.TableProps
    ITreeColumn Universe.Platform.Uikit.TreeColumn
    ITreeNode Universe.Platform.Uikit.TreeNodeType
    ITreeTableProps Universe.Platform.Uikit.TreeProps
    IValueListElement Universe.Platform.Uikit.EditableValuesListElement
    IModalProps Universe.Platform.Uikit.ModalProps
    InputType Будет удалено
    IStringKeyMap Universe.Platform.Uikit.StringKeyMap
    ITextAreaProps Universe.Platform.Uikit.TextAreaProps
    IWizardFooterProps Universe.Platform.Uikit.WizardFooterProps
    IWizardProps Universe.Platform.Uikit.WizardProps
    joinClassNames Будет удалено
    Layout Будет удалено
    LayoutManager Будет удалено
    LinksList Будет удалено
    MenuColor Будет удалено
    MenuItem Будет удалено
    MenuItemPin Будет удалено
    MenuItemPinProps Будет удалено
    message Будет удалено
    Mode Universe.Platform.Uikit.SelectMode
    Node Universe.Platform.Uikit.TreeNode
    Overlay Будет удалено
    Overlays Будет удалено
    palette Будет удалено
    PALETTE_COLOR Будет удалено
    PALETTE_COLOR_TONES_NUMBER Будет удалено
    PaginatedOptionsList Будет удалено
    PanelGridLayout Universe.Platform.Uikit.CardPanelGridLayout
    RadioChangeEvent Будет удалено
    renderIcon Будет удалено
    ROW_HEIGHT Будет удалено
    Row Будет удалено
    RowActionsProps Universe.Platform.Uikit.TableRowActionsProps
    SafeInvoke Будет удалено
    safeInvoke Будет удалено
    ScrollEvent Event
    SelectLookup Будет удалено
    SelectTree Будет удалено
    Size Будет удалено
    SizedButtonGroup Будет удалено
    StepSchema Universe.Platform.Uikit.WizardStepSchema
    StringUtil Будет удалено
    themeSchema Будет удалено
    TimePicker Universe.Platform.Uikit.Input
    ToastPortal Будет удалено
    truncateText Будет удалено
    Value Universe.Platform.Uikit.SelectValue

    Пакет предоставлял конфигурацию для сборки внешних модулей с подменой путей для имитации подключения зависимостей (@universe-platform/sdk, @universe-platform/uikit, react, mobx). Этот подход устарел, и пакет @universe-platform/ui-cli больше не требуется. Теперь потребитель должен самостоятельно настраивать инструменты сборки, если в этом есть необходимость.

    Описание файла Было Стало
    Конфигурация Vite необходимая для сборки внешнего модуля @universe-platform/ui-cli/vite/vite.external.config.ts Не поставляется. Потребитель может самостоятельно выбирать инструменты сборки
    Конфигурация Typescript для поддержки типизации в SDK @universe-platform/ui-cli/vite/tsconfig.json @universe-dg/sdk/tsconfig.recommended.json

    Пакет @universe-platform/sdk зависел от множества внутренних пакетов @universe-platform/*. Хотя они не входили в публичное API, потребители могли использовать их типы напрямую. Если вы использовали такие типы, их следует заменить на аналоги из Universe.Platform. Обычно они находятся в неймспейсе с тем же названием, что и пакет. Например, тип IRecordEntity из @universe-platform/record теперь доступен как Universe.Platform.Record.IRecordEntity. В будущем доступ ко всем пакетам @universe-platform/* будет закрыт.

    Ранее пакеты react, mobx и mobx-react подключались обычными импортами, но при сборке заменялись на глобальные переменные (window.Universe.SDK.*). Теперь такой механизм не применяется — все вендоры доступны напрямую в пространстве Universe.Vendor.

    import React from 'react';
    import {observable} from 'mobx';
    import {observer} from 'mobx-react';

    @observer
    class CustomComponent extends React.Component {
    @observable text: string;

    override render() {
    return <div>{this.text}</div>;
    }
    }
    • Через window.Universe:
      @window.Universe.Vendor.MobxReact.observer
      class CustomComponent extends window.Universe.Vendor.React.Component {
      @window.Universe.Vendor.Mobx.observable text: string;

      override render() {
      return <div>{this.text}</div>;
      }
      }
    • Через пакет @universe-dg/sdk:
      import {Universe} from '@universe-dg/sdk';

      @Universe.Vendor.MobxReact.observer
      class CustomComponent extends Universe.Vendor.React.Component {
      @Universe.Vendor.Mobx.observable text: string;

      override render() {
      return <div>{this.text}</div>;
      }
      }

    Если во внешнем модуле используются библиотеки, требующие вендоров в качестве зависимостей, то потребитель может самостоятельно настроить подмену импортов в своём сборщике, для корректной работы подключаемых библиотек.

    Ниже приведён пример настройки подмены путей в Vite:

    import {defineConfig} from 'vite';
    import {viteExternalsPlugin} from 'vite-plugin-externals';

    export default defineConfig(() => ({

    // ...

    plugins: [

    //...

    viteExternalsPlugin({
    react: ['Universe', 'Vendor', 'React'],
    mobx: ['Universe', 'Vendor', 'Mobx'],
    'mobx-react': ['Universe', 'Vendor', 'MobxReact'],
    moment: ['Universe', 'Vendor', 'Moment']
    })
    ],
    }));

    В качестве примера для миграции возьмем простой проект реализующий точку расширения Universe.App.UERightHeaderItem, использующий устаревшее SDK.

    Структура проекта:

    <project-root>
    ├─ src
    │ ├─ CustomComponent.tsx
    │ └─ index.ts
    ├─ tsconfig.json
    └─ package.json
    • <project-root>/src/CustomComponent.tsx:
      import * as React from 'react';
      import {Button, INTENT} from '@universe-platform/uikit';
      import {i18n, Locales} from '@universe-platform/sdk';

      i18n.addResourceBundle(Locales.Ru, {HeaderButton: {text: 'Нажми меня!'}});
      i18n.addResourceBundle(Locales.En, {HeaderButton: {text: 'Click me!'}});

      export class CustomComponent extends React.Component {
      override render () {
      return (
      <Button intent={INTENT.DANGER}>
      {i18n.t('HeaderButton>text')}
      </Button>
      );
      }
      }
    • <project-root>/src/index.ts:
      import {CustomComponent} from './CustomComponent';

      export default {
      userExits: [
      {
      type: 'RightHeaderItem',
      moduleId: 'uniqueId',
      active:true,
      system: false,
      resolver: () => true,
      meta: {
      order: 1,
      },
      component: CustomComponent,
      }
      ],
      }
    • <project-root>/tsconfig.json:
      {
      "extends": "@universe-platform/ui-cli/vite/tsconfig.json",
      "compilerOptions": {
      "useDefineForClassFields": false,
      "allowSyntheticDefaultImports": true
      },
      "files": ["src/index.ts"]
      }
    • <project-root>/package.json:
      {
      "scripts": {
      "build": "npx tsc && npx vite build --config node_modules/@universe-platform/ui-cli/vite/vite.external.config.ts"
      },
      "devDependencies": {
      "@universe-platform/sdk": "1.x.x",
      "@universe-platform/ui-cli": "1.x.x"
      }
      }

    Для миграции на новое SDK необходимо выполнить следующие шаги:

    1. Удалить устаревшие зависимости:
      npm uninstall @universe-platform/sdk @universe-platform/ui-cli
      
    2. Установить SDK-пакет для нового API, а также инструменты сборки:
      npm i -DE @universe-dg/sdk@undefined vite typescript
      
      Vite используется в качестве примера, как наиболее удобный сборщик, требующий минимальной конфигурации.
    3. Подключить рекомендуемую конфигурацию в <project-root>/tsconfig.json:
      {
      "extends": "@universe-dg/sdk/tsconfig.recommended.json",
      "files": ["src/index.ts"]
      }
    4. Настроить сборку внешнего модуля, создав файл <project-root>/vite.config.mjs:
      import {defineConfig} from 'vite';

      export default defineConfig({
      build: {
      lib: {
      entry: 'src/index.ts',
      formats: ['es'],
      fileName: `index.es`
      }
      }
      });
    5. Изменить команду сборки в <project-root>/package.json:
      npm pkg set scripts.build="npx tsc && npx vite build"
      
    6. Мигрировать код файла <project-root>/src/CustomComponent.tsx на новое API:
      const {React} = window.Universe.Vendor;
      const {Locale, Uikit} = window.Universe.Platform;

      Locale.i18n.addResourceBundle(Locale.Locales.Ru, {HeaderButton: {text: 'Нажми меня!'}});
      Locale.i18n.addResourceBundle(Locale.Locales.En, {HeaderButton: {text: 'Click me!'}});

      export class CustomComponent extends React.Component {
      override render() {
      return (
      <Uikit.Button intent={Uikit.INTENT.DANGER}>
      {Locale.i18n.t('HeaderButton>text')}
      </Uikit.Button>
      );
      }
      }
    7. Мигрировать код файла <project-root>/src/index.tsx на новое API:
      import {Universe} from '@universe-dg/sdk';
      import {CustomComponent} from './CustomComponent';

      export default {
      userExits: [
      {
      type: 'RightHeaderItem',
      moduleId: 'uniqueId',
      active:true,
      system: false,
      resolver: () => true,
      meta: {
      order: 1,
      },
      component: CustomComponent,
      }
      ],
      } satisfies Universe.Platform.UserExit.ExternalModuleDefault;
    8. Запустить сборку внешнего модуля:
      npm run build
      
      Внешний модуль будет собран в файл <project-root>/dist/index.es.js.