React SDK

React-обертка над Core SDK. Предоставляет компонент-провайдер, реактивные хуки для темы, языка, контекста слота и UI-операций.

@weavix/sdk-react на npmjs.com

Установка

npm install @weavix/sdk-react

Peer-зависимости:

react >= 16.14.0
react-dom >= 16.14.0

Быстрый старт

import { createRoot } from 'react-dom/client';
import { PluginProvider, usePluginContext, useTheme } from '@weavix/sdk-react';

function App() {
  const { slot, language } = usePluginContext();
  const theme = useTheme();

  return <div data-theme={theme}>Слот: {slot}, язык: {language}</div>;
}

createRoot(document.getElementById('root')!).render(
  <PluginProvider>
    <App />
  </PluginProvider>
);

PluginProvider

Корневой компонент плагина. Инициализирует bridge, загружает начальные значения (тема, язык, контекст, userId, orgId), уведомляет хост о готовности и предоставляет контекст всем дочерним компонентам.

import { PluginProvider, PluginLoader } from '@weavix/sdk-react';

root.render(
  <PluginProvider
    autoResize={true}
    autoNotifyReady={true}
    fallback={<PluginLoader />}
    errorFallback={(error) => <div>Ошибка: {error.message}</div>}
  >
    <App />
  </PluginProvider>
);

Props

Prop Тип По умолчанию Описание
autoResize boolean true Автоматически менять высоту iframe при изменении содержимого
autoNotifyReady boolean true Отправить plugin.ready хосту после инициализации
fallback ReactNode undefined Что показывать во время инициализации
errorFallback (error: Error) => ReactNode <PluginError /> Что показывать при ошибке инициализации
children ReactNode — Содержимое плагина

Поведение:

  • автоматически перехватывает клики по внешним ссылкам (<a href>, data-href) и вызывает uiApi.navigate, предотвращая переход из iframe;
  • защищен от двойной инициализации в React StrictMode;
  • при ошибке инициализации оборачивает приложение в ErrorBoundary.

Хуки

usePluginContext(level?)

Основной хук для доступа к данным хоста. Все значения реактивны — обновляются при получении push-событий от хоста.

import { usePluginContext } from '@weavix/sdk-react';

function App() {
  // basic (по умолчанию) — slotContext содержит только { entityId }
  const { theme, language, slot, slotContext, userId, orgId } = usePluginContext();

  // full — slotContext содержит полный объект слота
  const { slotContext: fullCtx } = usePluginContext('full');
}

Требует contextLevel: "full" в манифесте плагина для уровня 'full'. При несоответствии бросает ошибку в runtime.

Возвращаемое значение PluginContextValue:

Поле Тип Описание
theme Theme | undefined Текущая тема ('light', 'dark', 'light-hc', 'dark-hc', 'system')
language string | undefined Текущий язык ('ru', 'en', ...)
slot string Имя текущего слота
service string Идентификатор сервиса
origin string Origin хоста
innerUrl string URL плагина
queryParams Record<string, string> Query-параметры плагина
userId string | undefined ID текущего пользователя
orgId string | undefined ID организации
contextLevel 'basic' | 'full' Уровень контекста из манифеста
slotContext BasicContext | unknown | undefined Контекст слота
registerHandler RegisterHandlerFunction Зарегистрировать обработчик входящего RPC от хоста

BasicContext (при contextLevel: 'basic'):

{ entityId: string; entityMeta?: Record<string, string> }

useTheme()

Реактивная текущая тема хоста. Обновляется по событию theme.changed.

import { useTheme } from '@weavix/sdk-react';

function App() {
  const theme = useTheme(); // 'light' | 'dark' | 'light-hc' | 'dark-hc' | 'system' | undefined
  return <div data-theme={theme}>...</div>;
}

useLanguage()

Реактивный текущий язык хоста. Обновляется по событию language.changed.

import { useLanguage } from '@weavix/sdk-react';

const language = useLanguage(); // 'ru' | 'en' | ... | undefined

useUserId()

Реактивный ID текущего пользователя. Обновляется по событию userId.changed.

import { useUserId } from '@weavix/sdk-react';

const userId = useUserId(); // string | undefined

useOrgId()

Реактивный ID организации. Обновляется по событию orgId.changed.

import { useOrgId } from '@weavix/sdk-react';

const orgId = useOrgId(); // string | undefined

useToaster()

Хук для показа toast-уведомлений в хост-приложении.

Permission: Требуется "toaster" в permissions.ui манифеста.

import { useToaster } from '@weavix/sdk-react';

function SaveButton() {
  const toaster = useToaster();

  const handleSave = async () => {
    await save();
    toaster.add({ title: 'Сохранено', theme: 'success' });
  };

  return <button onClick={handleSave}>Сохранить</button>;
}

Возвращает { add: (options: ToastOptions) => Promise<{ name: string }> }.

Параметры ToastOptions — смотрите uiApi.toaster.add в описании Core SDK.

useConfirm()

Хук для показа диалога подтверждения.

Permission: Требуется "confirm" в permissions.ui манифеста.

import { useConfirm } from '@weavix/sdk-react';

function DeleteButton() {
  const confirm = useConfirm();

  const handleDelete = async () => {
    const { confirmed } = await confirm.show({
      title: 'Удалить задачу?',
      message: 'Это действие нельзя отменить.',
      theme: 'danger',
    });
    if (confirmed) {
      await deleteItem();
    }
  };

  return <button onClick={handleDelete}>Удалить</button>;
}

Возвращает { show: (options: ConfirmOptions) => Promise<ConfirmResult> }.

Параметры ConfirmOptions — смотрите uiApi.confirm.show в описании Core SDK.

useLocalizedString(fallbackLanguage?)

Возвращает функцию-переводчик, которая разворачивает LocalizedString на основе текущего языка из хоста.

import { useLocalizedString } from '@weavix/sdk-react';

function Label({ text }: { text: { ru: string; en: string } }) {
  const t = useLocalizedString();
  return <span>{t(text)}</span>;
}
Параметр Тип По умолчанию Описание
fallbackLanguage string 'ru' Язык-фолбэк, если текущий язык не определен

Возвращает (value: LocalizedString) => string.

usePluginBootstrap(options?)

Низкоуровневый хук начальной загрузки. Используйте его, если PluginProvider не подходит по каким-либо причинам (например, нужен кастомный жизненный цикл или нетипичный рендеринг).

import { usePluginBootstrap } from '@weavix/sdk-react';

function Root() {
  const { loading, error, theme, language, context, host } = usePluginBootstrap({ autoResize: true });

  if (loading) return <Spinner />;
  if (error) return <div>Ошибка: {error}</div>;

  return <App theme={theme} language={language} context={context} host={host} />;
}
Параметр Тип По умолчанию Описание
autoResize boolean true Автоматически менять высоту iframe

Возвращает PluginBootstrapState<TContext>:

Поле Тип Описание
host HostApi<TContext> Экземпляр HostApi (использует собственный, не глобальный hostApi)
loading boolean true до завершения инициализации
error string | null Сообщение об ошибке или null
theme Theme | undefined Текущая тема
language string | undefined Текущий язык
context TContext | undefined Контекст слота (только при contextLevel: 'full')
userId string | undefined ID пользователя
orgId string | undefined ID организации

В отличие от PluginProvider, usePluginBootstrap создает изолированный экземпляр HostApi и не вызывает hostApi.notifyReady() автоматически — это делается внутри хука после загрузки данных.

Компоненты

PluginLoader

Встроенный индикатор загрузки для отображения во время инициализации.

import { PluginProvider, PluginLoader } from '@weavix/sdk-react';

root.render(
  <PluginProvider fallback={<PluginLoader />}>
    <App />
  </PluginProvider>
);

Не принимает пропсов.

PluginError

Встроенный компонент для отображения ошибки инициализации. Используется как errorFallback по умолчанию в PluginProvider.

import { PluginError } from '@weavix/sdk-react';

<PluginProvider errorFallback={(error) => <PluginError error={error} />}>
  <App />
</PluginProvider>
Prop Тип Описание
error Error Ошибка для отображения

ErrorBoundary

React Error Boundary, используемый внутри PluginProvider. Можно использовать самостоятельно для оборачивания отдельных частей приложения.

import { ErrorBoundary, PluginError } from '@weavix/sdk-react';

<ErrorBoundary fallback={(error) => <PluginError error={error} />}>
  <RiskyComponent />
</ErrorBoundary>

Утилиты

isInternalUrl(url)

Проверяет, является ли URL внутренним (того же origin, что и плагин). Используется PluginProvider при перехвате кликов по ссылкам.

import { isInternalUrl } from '@weavix/sdk-react';

isInternalUrl('/local/path');      // true
isInternalUrl('https://ext.com'); // false

Типичные паттерны

Отображение с учетом темы

function App() {
  const theme = useTheme();
  return (
    <div className={`app app--${theme ?? 'light'}`}>
      ...
    </div>
  );
}

Локализованные строки

const LABELS = {
  save: { ru: 'Сохранить', en: 'Save' },
  cancel: { ru: 'Отмена', en: 'Cancel' },
};

function Form() {
  const t = useLocalizedString();
  return (
    <form>
      <button type="submit">{t(LABELS.save)}</button>
      <button type="button">{t(LABELS.cancel)}</button>
    </form>
  );
}

Регистрация обработчика от хоста

function App() {
  const { registerHandler } = usePluginContext();

  useEffect(() => {
    registerHandler('getData', () => ({ version: '1.0', status: 'ready' }));
  }, [registerHandler]);

  return <div>...</div>;
}

Связанные пакеты

Core SDK для Трекера — типизированная обертка для плагинов Трекера: trackerApi, hostApi, storageApi, специфичные типы.

React SDK для Трекера — React-интеграция: TrackerPluginProvider, useTrackerPluginContext и хуки.

@weavix/tracker-api-types — типы Tracker Public API v3.

Предыдущая