en

UI Kit

streamvi-ui содержит React-компоненты для интерфейса плагина в стиле StreamVi. Имя текущего пакета и его импорта: @streamvi/streamvi-ui-kit. Библиотека построена на Material UI и поддерживает светлую и тёмную темы.

Установка

Установите библиотеку из GitHub в React-приложении:

npm install git+https://github.com/StreamVi/streamvi-ui.git

Совместимые версии React, MUI и Emotion указаны в peerDependencies файла package.json. Современный npm устанавливает отсутствующие peer-зависимости автоматически. Если они уже есть в приложении, проверьте совместимость перед обновлением. Сохраните package-lock.json, чтобы зафиксировать результат установки. Публикация пакета в npm для этой команды не требуется.

Первый компонент

Оберните интерфейс в SvThemeProvider. Входной файл React-приложения может выглядеть так:

import { SvButton, SvThemeProvider } from '@streamvi/streamvi-ui-kit';
import '@streamvi/streamvi-ui-kit/fonts.css';

export function App() {
  return (
    <SvThemeProvider defaultMode="light">
      <SvButton onClick={() => alert('Ready')}>Проверить кнопку</SvButton>
    </SvThemeProvider>
  );
}

Импорт fonts.css необязателен: он подключает шрифт Inter. Компоненты получают стили через MUI и Emotion; отдельный импорт style.css не используется. Фон страницы, её раскладку и глобальные стили задаёт приложение. UI Kit не подключает CssBaseline автоматически.

Компоненты

Основные компоненты перечислены ниже. Полные свойства и примеры находятся в README UI Kit.

НазначениеКомпоненты
ДействияSvButton, SvIconButton, SvMenu
Ввод текста и числаSvField, SvNumberField, SvTagInput
Выбор значенияSvCheckbox, SvRadio, SvRadioGroup, SvSelect, SvSlider, SvSwitch
Метки и подсказкиSvChip, SvTooltip

Обработчики различаются: например, у SvField значение берётся из event.target.value, а SvNumberField передаёт число или null вторым аргументом onChange. Используйте типы текущей версии вместо переноса свойств старых компонентов.

Тема плагина

Внутри провайдера useSvColorScheme() возвращает mode и setMode. Режимы: light, dark, system. На первом рендере mode может отсутствовать. defaultMode задаёт начальный вариант; сохранённый выбор пользователя может иметь приоритет.

При обмене сообщениями виджета кабинет передаёт payload.theme. После проверки отправителя применяйте её через setMode('light') или setMode('dark'). UI Kit сам не слушает сообщения кабинета. Для встроенной страницы этот протокол настроек не предусмотрен.

Форма настроек

Этот компонент получает тему и значение поля от родительского компонента. Изменение поля вызывает onTitleChange, отправка формы вызывает onSave. Пустой заголовок не отправляется.

import { useEffect } from 'react';
import {
  SvButton, SvField, SvThemeProvider, useSvColorScheme,
} from '@streamvi/streamvi-ui-kit';

type SettingsProps = {
  theme: 'light' | 'dark';
  title: string;
  onTitleChange: (title: string) => void;
  onSave: () => void;
};

export function WidgetSettings(props: SettingsProps) {
  return (
    <SvThemeProvider defaultMode={props.theme} storageManager={null}>
      <SettingsForm {...props} />
    </SvThemeProvider>
  );
}

function SettingsForm({ theme, title, onTitleChange, onSave }: SettingsProps) {
  const { setMode } = useSvColorScheme();
  useEffect(() => { setMode(theme); }, [theme, setMode]);
  const invalid = title.trim().length === 0;

  return (
    <form onSubmit={event => {
      event.preventDefault();
      if (!invalid) onSave();
    }}>
      <SvField
        label="Заголовок"
        value={title}
        onChange={event => onTitleChange(event.target.value)}
        error={invalid}
        helperText={invalid ? 'Введите заголовок' : undefined}
      />
      <SvButton type="submit" disabled={invalid}>Сохранить</SvButton>
    </form>
  );
}

Передавайте theme из проверенного сообщения кабинета, а title из текущих настроек. В родительском компоненте храните черновик: onTitleChange меняет его, onSave отправляет весь объект настроек по протоколу виджета, сохраняя остальные поля. Сообщения init и sync только обновляют состояние формы, они не должны вызывать update в ответ. UI Kit не сохраняет настройки сам.

storageManager={null} отключает сохранённый выбор темы в этом примере, чтобы тема кабинета оставалась определяющей. Изменения theme применяются через setMode; одного defaultMode для последующих переключений недостаточно.

TypeScript

Пакет использует ESM. Для приложения со сборщиком настройте moduleResolution: "bundler"; для Node.js используйте согласованные module и moduleResolution: "NodeNext".

Если сборка с exactOptionalPropertyTypes: true сообщает ошибки в объявлениях Collapse или Fade из MUI 9.5, сначала проверьте совместимость зависимостей. Это известный случай ошибок типов в зависимостях, а не обязательная настройка UI Kit. Временный вариант: skipLibCheck: true. Он отключает проверку файлов .d.ts всех библиотек, поэтому не добавляйте его без такой ошибки.

Переход со старой версии

Счётчик зрителей использует прежний пакет @streamvi/streamvi-ui, закреплённый на другой ревизии. Там другая основа компонентов, импорты и обработчики. Обновление до @streamvi/streamvi-ui-kit требует миграции, а не только замены зависимости. Для запуска примера сохраняйте его исходные версии; для нового интерфейса ориентируйтесь на текущий UI Kit.

Предыдущая
Passport
Далее
Примеры