---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.5
  - property: og:type
    content: article
  - property: article:section
    content: Платформа плагинов
  - property: og:title
    content: API Reference - plugin-sdk-react
  - property: article:tag
    content: Техническая инструкция
alternate:
  - https://yandex.ru/support/tracker/en/plugins/tools/sdk/react.md
  - https://yandex.ru/support/tracker/ru/plugins/tools/sdk/react.md
  - href: ru/plugins/tools/sdk/react.md
    type: text/markdown
    title: Markdown version
  - href: ../../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/support/tracker/ru/llms.txt


# API Reference - @weavix/tracker-plugin-sdk-react

## Components {#components}

### TrackerPluginProvider {#tracker-plugin-provider}

Провайдер для инициализации плагина Tracker. Оборачивает приложение и управляет жизненным циклом плагина. Предоставляет тему, язык и контекст слота через контекст React.

**Props:** [`TrackerPluginProviderProps`](#trackerpluginproviderprops)

#### Features {#tracker-plugin-provider-features}

- Автоматическая инициализация плагина
- Управление состояниями загрузки и ошибок
- Предоставление контекста через React Context API
- Автоматическое уведомление Трекера о готовности плагина
- Защита от двойной инициализации в React StrictMode

#### Example (базовое использование) {#tracker-plugin-provider-example-basic}

```tsx
import { TrackerPluginProvider } from '@weavix/tracker-plugin-sdk-react';
import { createRoot } from 'react-dom/client';
import { App } from './App';

const root = createRoot(document.getElementById('root')!);

root.render(
  <TrackerPluginProvider>
    <App />
  </TrackerPluginProvider>,
);
```

#### Example (с кастомными опциями) {#tracker-plugin-provider-example-custom-options}

```tsx
import { TrackerPluginProvider } from '@weavix/tracker-plugin-sdk-react';
import { Loader } from './components/Loader';
import { ErrorScreen } from './components/ErrorScreen';

root.render(
  <TrackerPluginProvider
    autoResize={false}
    fallback={<Loader />}
    errorFallback={(error) => <ErrorScreen error={error} />}
    autoNotifyReady={false}
  >
    <App />
  </TrackerPluginProvider>,
);
```

#### Example (отключение автоматического уведомления) {#tracker-plugin-provider-example-disable-notify}

```tsx
import { TrackerPluginProvider, hostApi } from '@weavix/tracker-plugin-sdk-react';

function App() {
  useEffect(() => {
    // Выполняем дополнительную инициализацию, затем уведомляем Трекер
    initializeApp().then(() => {
      hostApi.notifyReady()
    });
  }, []);

  return <div>My Plugin</div>;
}

root.render(
  <TrackerPluginProvider autoNotifyReady={false}>
    <App />
  </TrackerPluginProvider>,
);
```

## Hooks {#hooks}

### useTrackerPluginContext {#use-tracker-plugin-context}

Хук для получения темы, языка и контекста слота из [`TrackerPluginProvider`](#trackerpluginprovider). Поддерживает несколько перегрузок в зависимости от `level` и generic-параметра `TSlot`.

#### Type Signature {#use-tracker-plugin-context-type-signature}

```typescript
// level: 'basic' — базовый контекст (только entityId и entityMeta), тип slotContext сужается по проверке slot
function useTrackerPluginContext(level: 'basic'): {
    [K in keyof SlotContextMap]: BasicTrackerPluginContextValue<K>;
}[keyof SlotContextMap];

// level: 'full' — полный контекст с живыми данными сущности
function useTrackerPluginContext(level: 'full'): {
    [K in keyof SlotContextMap]: FullTrackerPluginContextValue<K>;
}[keyof SlotContextMap];

// С generic TSlot и level: 'basic' — типизированный базовый контекст для конкретного слота
function useTrackerPluginContext<TSlot extends keyof SlotContextMap>(
    level: 'basic',
): BasicTrackerPluginContextValue<TSlot>;

// С generic TSlot и level: 'full' — типизированный полный контекст для конкретного слота
function useTrackerPluginContext<TSlot extends keyof SlotContextMap>(
    level: 'full',
): FullTrackerPluginContextValue<TSlot>;
```

#### Parameters {#use-tracker-plugin-context-parameters}

- `level` — `'basic' | 'full'` (обязательный) — уровень контекста слота. Должен совпадать со значением `contextLevel`, указанным для слота в `manifest.json`. Подробнее — в разделе [Уровни контекста слота](https://yandex.ru/support/tracker/ru/plugins/common.md#context-levels).

#### Type Parameters {#use-tracker-plugin-context-type-parameters}

- `TSlot` — тип слота (опционально). С generic — `slotContext` типизирован под этот слот. Без generic — можно сужать по `slot === 'issue.action'` и т.д.

#### Returns {#use-tracker-plugin-context-returns}

[`BasicTrackerPluginContextValue<TSlot>`](#trackerplugincontextvalue) или [`FullTrackerPluginContextValue<TSlot>`](#trackerplugincontextvalue) в зависимости от `level`, либо union по всем слотам.

#### Throws {#use-tracker-plugin-context-throws}

- `Error` - если используется вне [`TrackerPluginProvider`](#trackerpluginprovider)

#### Example (basic контекст) {#use-tracker-plugin-context-example-basic}

```tsx
import { useTrackerPluginContext } from '@weavix/tracker-plugin-sdk-react';

function MyComponent() {
  const { theme, language, slotContext } = useTrackerPluginContext('basic');
  // slotContext.entityId — идентификатор текущей сущности
  // slotContext.entityMeta — дополнительные базовые метаданные (опционально)

  return (
    <div className={theme}>
      <p>Language: {language}</p>
      <p>Entity ID: {slotContext.entityId}</p>
    </div>
  );
}
```

#### Example (basic — слот известен) {#use-tracker-plugin-context-example-basic-known-slot}

```tsx
const { slotContext } = useTrackerPluginContext<'issue.action'>('basic');
slotContext.entityId; // идентификатор тикета
slotContext.entityMeta; // дополнительные метаданные
```

#### Example (несколько слотов — сужение по slot) {#use-tracker-plugin-context-example-narrowing}

```tsx
const { slot, slotContext } = useTrackerPluginContext('basic');
if (slot === 'issue.action') {
  slotContext.entityId; // здесь slotContext типизирован под слот issue.action
}
```

#### Example (full контекст с типизацией слота) {#use-tracker-plugin-context-example-full}

```tsx
import { useTrackerPluginContext } from '@weavix/tracker-plugin-sdk-react';

function IssuePlugin() {
  // В manifest.json для слота: contextLevel: "full"
  const { theme, language, slotContext } = useTrackerPluginContext<'issue.action'>('full');
  return (
    <div>
      <h1>Issue: {slotContext.key}</h1>
      <p>Version: {slotContext.version}</p>
      <p>Theme: {theme}</p>
    </div>
  );
}
```

### useLocalizedString {#use-localized-string}

Хук для получения локализованной строки на основе текущего языка из контекста [`TrackerPluginProvider`](#trackerpluginprovider).

#### Type Signature {#use-localized-string-type-signature}

```typescript
function useLocalizedString(fallbackLanguage?: string): (value: LocalizedString) => string;
```

#### Parameters {#use-localized-string-parameters}

- `fallbackLanguage` - `string` (опционально, по умолчанию 'en') - резервный язык, если основной не найден

#### Returns {#use-localized-string-returns}

Функция для локализации строк `(value: LocalizedString) => string`.

#### Example (базовое использование) {#use-localized-string-example-basic}

```tsx
import { useLocalizedString } from '@weavix/tracker-plugin-sdk-react';

function MyComponent() {
  const localize = useLocalizedString();

  const field = {
    name: { ru: 'Имя', en: 'Name' },
    description: { ru: 'Описание', en: 'Description' },
  };

  return (
    <div>
      <h1>{localize(field.name)}</h1>
      <p>{localize(field.description)}</p>
    </div>
  );
}
```

#### Example (с резервным языком) {#use-localized-string-example-fallback}

```tsx
import { useLocalizedString } from '@weavix/tracker-plugin-sdk-react';

function MyComponent() {
  // Если перевод на текущем языке не найден, используется русский
  const localize = useLocalizedString('ru');

  const name = { en: 'Name' }; // нет русского перевода

  return <div>{localize(name)}</div>; // вернет 'Name'
}
```

#### Example (работа с полями задачи) {#use-localized-string-example-fields}

```tsx
import {
  useLocalizedString,
  useTrackerPluginContext,
} from '@weavix/tracker-plugin-sdk-react';
import { trackerApi } from '@weavix/tracker-plugin-sdk-react';

function FieldsList() {
  const localize = useLocalizedString();
  const { slotContext } = useTrackerPluginContext<'issue.action'>();
  const [fields, setFields] = useState([]);

  useEffect(() => {
    trackerApi.v3.get['/fields/...']({ ... }).then(setFields);
  }, []);

  return (
    <ul>
      {fields.map((field) => (
        <li key={field.id}>
          <strong>{localize(field.name)}</strong>
          {field.description && <p>{localize(field.description)}</p>}
        </li>
      ))}
    </ul>
  );
}
```

### useToaster {#use-toaster}

Хук для показа toast-уведомлений в интерфейсе Трекера. Возвращает объект с методом `add`.

**Permission:** в `manifest.json` нужно запросить `tracker:ui:toaster`:

```json
{
    "permissions": {
        "ui": ["toaster"]
    }
}
```
Пример:

```tsx
import { useToaster } from '@weavix/tracker-plugin-sdk-react';

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

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

  const handleDelete = async () => {
    await deleteItem(id);
    toaster.add({
      title: 'Удалено',
      theme: 'info',
      content: 'QUEUE-123',
      actions: [
        {
          label: 'Отменить',
          onClick: () => restoreItem(id),
        },
      ],
    });
  };

  return (
    <div>
      <button onClick={handleSave}>Сохранить</button>
      <button onClick={handleDelete}>Удалить</button>
    </div>
  );
}
```

Полный список параметров `add(options)` — в [core](https://yandex.ru/support/tracker/ru/plugins/tools/sdk/core.md#toasts).

### useConfirm {#use-confirm}

Плагин может показать модальный диалог подтверждения. Диалог рендерится **на стороне трекера**, а не внутри iframe, поэтому перекрывает всё приложение и фокусирует пользователя на принятии решения.

**Permission:** в `manifest.json` нужно запросить `tracker:ui:confirm`:

```json
{
    "permissions": {
        "ui": ["confirm"]
    }
}
```

Пример:

```tsx
import { useConfirm } from '@weavix/tracker-plugin-sdk-react';

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

    const handleClick = async () => {
        const { confirmed } = await confirm.show({
            title: 'Удаление',
            message: 'Уверены что хотите удалить? Действие необратимо.',
            textButtonApply: 'Удалить',
            textButtonCancel: 'Отмена',
            theme: 'danger',
        });

        if (confirmed) {
            // выполняем действие
        }
    };

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

Полный список параметров — в [core](https://yandex.ru/support/tracker/ru/plugins/tools/sdk/core.md#confirm).

## Types {#types}

### TrackerPluginProviderProps {#tracker-plugin-provider-props}

Свойства компонента [`TrackerPluginProvider`](#trackerpluginprovider).

```typescript
interface TrackerPluginProviderProps {
  /** Дочерние элементы */
  children: ReactNode;

  /**
   * Автоматически изменять размер контейнера плагина при изменении содержимого
   * @default true
   */
  autoResize?: boolean;

  /**
   * Компонент для отображения во время инициализации
   * @default <PluginLoader />
   */
  fallback?: ReactNode;

  /**
   * Компонент для отображения при ошибке инициализации
   * @default <PluginError error={error} />
   */
  errorFallback?: (error: Error) => ReactNode;

  /**
   * Автоматически уведомить Трекер о готовности плагина после инициализации
   * @default true
   */
  autoNotifyReady?: boolean;
}
```

#### Properties {#tracker-plugin-provider-props-properties}

#|
|| **Свойство** | **Тип** | **Обязательное** | **По умолчанию** | **Описание** ||
|| `children` | `ReactNode` | Да | — | Дочерние компоненты, которые будут отрендерены после успешной инициализации ||
|| `autoResize` | `boolean` | Нет | `true` | Автоматически изменять размер контейнера плагина при изменении содержимого. Включает отслеживание изменений DOM и автоматическую отправку новой высоты Трекеру ||
|| `fallback` | `ReactNode` | Нет | Встроенный компонент `<PluginLoader />` | Компонент, отображаемый во время инициализации плагина ||
|| `errorFallback`
|

```ts
(error: Error) =>
  ReactNode
```

| Нет | Встроенный компонент
```
<PluginError
error={error} />
```
| Функция, возвращающая компонент для отображения при ошибке инициализации ||
|| `autoNotifyReady` | `boolean` | Нет | `true` | Автоматически уведомлять Трекер о готовности плагина после инициализации ||
|#

Примеры использования свойств — в разделе [Components](#trackerpluginprovider) выше.

{% note info "Элементы с относительной высотой" %}

Если вы используете элементы с относительной высотой (vh, % и т.п.), то автоматическое изменение размеров (`autoResize`) может вести себя неожиданно.
Если же вы все-таки хотите использовать компоненты с относительной высотой, то выключите автоматическое изменение размеров.

{% endnote %}

### TrackerPluginContextValue {#tracker-plugin-context-value}

Значение контекста, предоставляемое [`TrackerPluginProvider`](#trackerpluginprovider). Тип `slotContext` зависит от запрошенного уровня контекста (`level`).

#### BasicTrackerPluginContextValue {#basic-tracker-plugin-context-value}

Возвращается при `level: 'basic'`. `slotContext` содержит только идентификатор сущности и базовые метаданные.

```typescript
interface BasicTrackerPluginContextValue<TSlot extends keyof SlotContextMap = keyof SlotContextMap> {
  theme: Theme;
  language: string;
  /** Имя слота, в котором открыт плагин */
  slot: TSlot;
  /** Базовый контекст слота */
  slotContext: {
    /** Идентификатор текущей сущности */
    entityId: string;
    /** Дополнительная базовая информация.
     *  Например, для комментария содержит идентификатор родительского тикета. */
    entityMeta?: Record<string, string>;
  };
}
```

#### FullTrackerPluginContextValue {#full-tracker-plugin-context-value}

Возвращается при `level: 'full'`. `slotContext` содержит полные данные сущности (формат совпадает с типами публичного API).

```typescript
interface FullTrackerPluginContextValue<TSlot extends keyof SlotContextMap = keyof SlotContextMap> {
  theme: Theme;
  language: string;
  /** Имя слота, в котором открыт плагин */
  slot: TSlot;
  /** Полный контекст слота (зависит от типа слота) */
  slotContext: SlotContextMap[TSlot];
}
```

#### Properties (общие для обоих типов) {#tracker-plugin-context-value-properties}

#|
|| Свойство      | Тип  | Описание  |
|| `theme`       |
```
Theme ('light' | 'light-hc'
  | 'dark' | 'dark-hc' | 'system')
```
| Текущая тема оформления Трекера  ||
|| `language`    | `string` | Код текущего языка Трекера (например, `'ru'`, `'en'`)  ||
|| `slot`        | `TSlot` (ключ из `SlotContextMap`) | Имя слота, в котором открыт плагин (например, `'issue.action'`, `'navigation'`) ||
|| `slotContext` |
```
{ entityId: string;
  entityMeta?: Record<string, string> }
```
при `level: 'basic'`,
`SlotContextMap[TSlot]` при `level: 'full'` |
Контекст слота, в котором запущен плагин. При `basic` — только идентификатор и метаданные сущности. При `full` — полный объект сущности (для `'issue.action'` — тип `Issue` из пакета `@weavix/tracker-api-types`, для `'navigation'` — пустой объект `{}`) ||
|#

#### Example (basic) {#tracker-plugin-context-value-example-basic}

```tsx
const { theme, language, slotContext } = useTrackerPluginContext<'issue.action'>('basic');
const isDark = theme === 'dark' || theme === 'dark-hc';
console.log(slotContext.entityId); // 'abc123'
console.log(slotContext.entityMeta); // { issueId: 'QUEUE-123' } — для комментария
```

#### Example (full) {#tracker-plugin-context-value-example-full}

```tsx
// В manifest.json для слота: contextLevel: "full"
const { slotContext } = useTrackerPluginContext<'issue.action'>('full');
console.log(slotContext.key); // 'QUEUE-123'
console.log(slotContext.version); // 42
```

## Публичное API {#public-api}

Пакет `@weavix/tracker-plugin-sdk-react` реэкспортирует **hostApi**, **trackerApi**, **storageApi** и типы из `@weavix/tracker-plugin-sdk-core`.

- **hostApi** — взаимодействие с приложением Трекера: инициализация, тема, язык, контекст слота, размер окна, `notifyReady()`. Подробнее в [API Reference core](https://yandex.ru/support/tracker/ru/plugins/tools/sdk/core.md#notifyReady).
- **trackerApi** — вызовы Tracker Public API через **типизированное API v3**: `trackerApi.v3.get`, `trackerApi.v3.post`, `trackerApi.v3.put`, `trackerApi.v3.patch`, `trackerApi.v3.delete`. Ключи — пути эндпоинтов с автоподсказкой и JSDoc из `@weavix/tracker-api-types`. Описание методов и форматов: [Common format](https://yandex.ru/support/tracker/ru/api-ref/common-format.md).
- **storageApi** — JSON-хранилище плагина уровня организации. Подробнее: [Хранилище данных](https://yandex.ru/support/tracker/ru/plugins/storage.md).

#### Пример {#public-api-example}

```ts
import { trackerApi } from '@weavix/tracker-plugin-sdk-react';

const issue = await trackerApi.v3.get['/issues/{id}']({
  pathParams: { id: 'KEY-1' },
  queryParams: { expand: ['COMMENTS'] },
});
```

Тема, язык и контекст слота доступны через `useTrackerPluginContext`. Инициализация и уведомление Трекера — через **hostApi** или внутри `TrackerPluginProvider`. Вызовы эндпоинтов Tracker — через **trackerApi.v3**.

**Полная документация по API (типы, коды ошибок, утилиты):**

[API Reference — @weavix/tracker-plugin-sdk-core](https://yandex.ru/support/tracker/ru/plugins/tools/sdk/core.md)

## Утилиты {#utils}

### getLocalizedString {#get-localized-string}

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

#### Type Signature {#get-localized-string-type-signature}

```typescript
function getLocalizedString(
  value: LocalizedString,
  language: string,
  fallbackLanguage?: string,
): string;
```

#### Parameters {#get-localized-string-parameters}

- `value` - `LocalizedString` - локализованная строка (может быть строкой или объектом с переводами)
- `language` - `string` - код языка ('ru' или 'en')
- `fallbackLanguage` - `string` (опционально, по умолчанию 'en') - резервный язык, если основной не найден

#### Returns {#get-localized-string-returns}

`string` - локализованная строка на указанном языке.

#### Example (базовое использование) {#get-localized-string-example-basic}

```tsx
import { getLocalizedString } from '@weavix/tracker-plugin-sdk-react';
import type { LocalizedString } from '@weavix/tracker-plugin-sdk-react';

function getFieldName(name: LocalizedString, language: string): string {
  return getLocalizedString(name, language);
}
// language можно получить из useTrackerPluginContext() в компоненте

const name = { ru: 'Название', en: 'Summary' };
const localizedName = getFieldName(name, 'ru');
console.log(localizedName); // 'Название'
```

#### Example (с резервным языком) {#get-localized-string-example-fallback}

```tsx
import { getLocalizedString } from '@weavix/tracker-plugin-sdk-react';

// Если перевод на русский отсутствует, используется английский
const partial = { en: 'Name' };
const name = getLocalizedString(partial, 'ru', 'en');
console.log(name); // 'Name'

// Если передана простая строка, она возвращается как есть
const simple = 'Simple string';
const result = getLocalizedString(simple, 'ru');
console.log(result); // 'Simple string'
```

#### Example (в обработчике событий) {#get-localized-string-example-handler}

```tsx
import {
  getLocalizedString,
  useTrackerPluginContext,
} from '@weavix/tracker-plugin-sdk-react';
import type { LocalizedString } from '@weavix/tracker-plugin-sdk-react';

type FieldWithName = { id: string; name: LocalizedString };

function FieldSelector({ fields }: { fields: FieldWithName[] }) {
  const { language } = useTrackerPluginContext();
  const handleFieldSelect = (field: FieldWithName) => {
    const localizedName = getLocalizedString(field.name, language);
    alert(`Выбрано поле: ${localizedName}`);
  };

  return (
    <ul>
      {fields.map((field) => (
        <li key={field.id} onClick={() => handleFieldSelect(field)}>
          {field.id}
        </li>
      ))}
    </ul>
  );
}
```

{% note info "Примечание" %}

В React-компонентах предпочтительнее использовать хук [`useLocalizedString`](#uselocalizedstring), который автоматически получает язык из контекста:

```tsx
import { useLocalizedString } from '@weavix/tracker-plugin-sdk-react';

function MyComponent() {
  const localize = useLocalizedString();

  const field = { name: { ru: 'Название', en: 'Title' } };
  return <div>{localize(field.name)}</div>;
}
```

{% endnote %}