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.