---
metadata:
  - name: generator
    content: Diplodoc Platform v5.70.2
  - property: og:type
    content: article
  - property: article:section
    content: Платформа плагинов
  - property: og:title
    content: React SDK
  - property: article:tag
    content: Техническая инструкция
alternate:
  - https://yandex.ru/dev/yandex-360/extensions/ru/tools/sdk-react.md
  - href: https://yandex.ru/dev/yandex-360/extensions/ru/tools/sdk-react.md
    type: text/markdown
    title: Markdown version
  - href: https://yandex.ru/dev/yandex-360/extensions/ru/llms.txt?revision=r22165285
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/yandex-360/extensions/ru/llms.txt?revision=r22165285


# React SDK

React-обертка над [Core SDK](https://yandex.ru/dev/yandex-360/extensions/ru/tools/sdk-core.md). Предоставляет компонент-провайдер, реактивные хуки для темы, языка, контекста слота и UI-операций.

[**@weavix/sdk-react** на npmjs.com](https://www.npmjs.com/package/@weavix/sdk-react)

## Установка

```bash
npm install @weavix/sdk-react
```

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

```
react >= 16.14.0
react-dom >= 16.14.0
```

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

```tsx
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), уведомляет хост о готовности и предоставляет контекст всем дочерним компонентам.

```tsx
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`.

## Хуки {#hooks}

### usePluginContext(level?)

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

```tsx
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'`):

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

### useTheme()

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

```tsx
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`.

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

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

### useUserId()

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

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

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

### useOrgId()

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

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

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

### useToaster() {#use-toaster}

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

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

```tsx
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](https://yandex.ru/dev/yandex-360/extensions/ru/tools/sdk-core.md#uiapitoasteraddoptions).

### useConfirm()

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

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

```tsx
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](https://yandex.ru/dev/yandex-360/extensions/ru/tools/sdk-core.md#uiapiconfirmshowoptions).

### useLocalizedString(fallbackLanguage?)

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

```tsx
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` не подходит по каким-либо причинам (например, нужен кастомный жизненный цикл или нетипичный рендеринг).

```tsx
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

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

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

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

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

### PluginError

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

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

<PluginProvider errorFallback={(error) => <PluginError error={error} />}>
  <App />
</PluginProvider>
```

| Prop | Тип | Описание |
|------|-----|---------|
| `error` | `Error` | Ошибка для отображения |

### ErrorBoundary

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

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

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

## Утилиты

### isInternalUrl(url)

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

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

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

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

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

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

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

```tsx
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>
  );
}
```

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

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

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

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

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

[Core SDK для Трекера](https://yandex.ru/dev/yandex-360/extensions/ru/tools/sdk-tracker-core.md) — типизированная обертка для плагинов Трекера: `trackerApi`, `hostApi`, `storageApi`, специфичные типы.

[React SDK для Трекера](https://yandex.ru/dev/yandex-360/extensions/ru/tools/sdk-tracker-react.md) — React-интеграция: `TrackerPluginProvider`, `useTrackerPluginContext` и хуки.

[@weavix/tracker-api-types](https://www.npmjs.com/package/@weavix/tracker-api-types) — типы Tracker Public API v3.
