SDK React для Трекера

React SDK для плагинов Трекера. Строит типизированную обертку над React SDK: заменяет PluginProvider на TrackerPluginProvider и добавляет useTrackerPluginContext с типами из SlotContextMap. Реэкспортирует trackerApi, hostApi, storageApi, uiApi из SDK Core для Трекера.

@weavix/tracker-plugin-sdk-react на npmjs.com

Установка

npm install @weavix/tracker-plugin-sdk-react

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

react >= 18.0.0
react-dom >= 18.0.0

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

import { createRoot } from 'react-dom/client';
import { TrackerPluginProvider, useTrackerPluginContext } from '@weavix/tracker-plugin-sdk-react';

function App() {
  const { theme, language, slot, slotContext } = useTrackerPluginContext();

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

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

TrackerPluginProvider

Корневой компонент плагина. Является типизированной оберткой над PluginProvider из React SDK: добавляет специфичный для Трекера registerHandler с типами из SlotContextMap.

Props, поведение (autoResize, autoNotifyReady, fallback, errorFallback) и паттерн ручного вызова notifyReady — идентичны базовому PluginProvider. Подробнее: React SDK → PluginProvider.

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

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

useTrackerPluginContext(level?)

Основной хук для доступа к данным хоста. Типизирован под Tracker — slotContext имеет тип SlotContextMap[TSlot] вместо обобщенного unknown. Все значения реактивны.

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

function App() {
  // basic (по умолчанию) — slotContext: { entityId, entityMeta? }
  const { theme, language, slot, slotContext } = useTrackerPluginContext();
}

Полный контекст слота

Требует contextLevel: "full" в манифесте плагина.

function IssuePlugin() {
  const { slotContext } = useTrackerPluginContext<'issue.action'>('full');
  // slotContext: Issue | undefined

  return (
    <div>
      <h1>Задача: {slotContext?.key}</h1>
      <p>Очередь: {slotContext?.queue?.key}</p>
      <p>Исполнитель: {slotContext?.assignee?.login}</p>
    </div>
  );
}

contextLevel в манифесте

Манифест useTrackerPluginContext() useTrackerPluginContext('full')
contextLevel: "basic" (по умолчанию) slotContext: BasicContext | undefined ошибка в runtime
contextLevel: "full" slotContext: BasicContext | undefined slotContext: SlotContextMap[TSlot] | undefined

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

BasicTrackerPluginContextValue<TSlot> (level: 'basic'):

Поле Тип Описание
theme Theme | undefined Текущая тема
language string | undefined Текущий язык
slot TSlot Имя текущего слота
service string Идентификатор сервиса
origin string Origin хоста
innerUrl string URL плагина
queryParams Record<string, string> Query-параметры
userId string | undefined ID пользователя
orgId string | undefined ID организации
contextLevel 'basic' Уровень контекста
slotContext BasicContext | undefined { entityId, entityMeta? }
registerHandler RegisterHandlerFunction<TSlot> Регистрация обработчика RPC от хоста

FullTrackerPluginContextValue<TSlot> (level: 'full'): то же, но slotContext: SlotContextMap[TSlot] | undefined.

registerHandler

Типизированная регистрация обработчика входящего RPC от хоста. В отличие от базового registerHandler из @weavix/sdk-react, тип результата getData выводится из GetDataResultMap[TSlot].

import { useEffect } from 'react';
import {
  useTrackerPluginContext,
  type TriggerActionData,
} from '@weavix/tracker-plugin-sdk-react';

function App() {
  const { registerHandler } = useTrackerPluginContext<'trigger.create.action'>();

  useEffect(() => {
    // Для 'getData' — тип handler зависит от слота (GetDataResultMap[TSlot])
    const getData = (): TriggerActionData => ({
      method: 'POST',
      endpoint: 'https://example.com/webhook',
      contentType: 'application/json; charset=UTF-8',
      body: '{}',
      authContext: { type: 'noauth' },
    });

    registerHandler('getData', getData);
  }, [registerHandler]);

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

Хуки

Следующие хуки реэкспортируются из @weavix/sdk-react без изменений: useTheme, useLanguage, useUserId, useOrgId, useToaster, useConfirm.

Подробнее в React SDK.

useLocalizedString(fallbackLanguage?)

Возвращает функцию-переводчик для LocalizedString — специфичного для Трекера типа string | { ru?: string; en?: string; ... }.

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

function Label({ text }: { text: LocalizedString }) {
  const t = useLocalizedString();
  return <span>{t(text)}</span>;
}

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

Получение текущей задачи (full context)

function IssueActions() {
  const { slotContext: issue } = useTrackerPluginContext<'issue.action'>('full');
  // issue: Issue | undefined

  if (!issue) return null;

  return (
    <div>
      <h2>{issue.key}: {issue.summary}</h2>
      <p>Очередь: {issue.queue?.key}</p>
      <p>Исполнитель: {issue.assignee?.login}</p>
    </div>
  );
}

Вызов Tracker API

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

function IssueList() {
  const [issues, setIssues] = useState([]);

  useEffect(() => {
    trackerApi.v3.post['/issues/_search']({
      bodyParams: {
        filter: { queue: 'MYQUEUE' },
        order: 'updatedAt',
        orderAsc: false,
      },
    }).then(({ data }) => setIssues(data));
  }, []);

  return <ul>{issues.map(i => <li key={i.id}>{i.summary}</li>)}</ul>;
}

Описание trackerApi — см. Работа с API Яндекс Трекера и Core SDK для Трекера.

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

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

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

Core SDK — базовый runtime: hostApi, uiApi, storageApi, events, ошибки.

React SDK — базовая React-обертка: хуки, PluginProvider, компоненты.