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, компоненты.