@pulsesync/addon-sdk

Официальный SDK для React-аддонов PulseSync WebHost.

Шаблон аддона · PulseSync

Установка

yarn add @pulsesync/addon-sdk [email protected]
yarn add --dev vite @vitejs/plugin-react typescript @types/react

Требуются Node.js 20+, React 19.2 и актуальный PulseSync WebHost API v1. До версии 1.0 API может меняться между minor-релизами.

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

import { defineAddon, IconButton, notifications, useCurrentTrack } from '@pulsesync/addon-sdk'

function PlayerButton() {
    const track = useCurrentTrack()

    return (
        <IconButton
            icon="info"
            label="Текущий трек"
            onClick={async () => {
                if (track) await notifications.info(`Сейчас играет: ${track.title ?? track.id}`)
            }}
        />
    )
}

export default defineAddon({
    id: 'player-button',
    slots: { playerBarButton: PlayerButton },
})

Сохраняйте постоянный id: к нему привязаны настройки и данные аддона. React и JSX runtime предоставляет WebHost — не подключайте react-dom и не вызывайте createRoot().

Основные возможности

| API | Назначение | | --- | --- | | usePlayer, useCurrentTrack, useQueue, usePage, useRoute | Реактивное состояние без опроса; до первого снимка возвращают null | | player, page, router | Данные, управление плеером и навигация вне React | | storage, assets, net, logger | JSON-хранилище, файлы аддона, запросы и логи | | toasts.show, notifications.info, notifications.error | Верхние тосты и нижние уведомления | | modals, openModal, AlertModal, ConfirmModal, FormModal | Нативные диалоги и формы | | Button, IconButton, Tooltip, TextInput, Switch, Select, Slider, Tabs, Spinner, Text, Caption, YandexMusicIcon | Нативные элементы интерфейса | | defineAddonSettings, SettingType | Типизированные настройки |

Сервисы импортируются из SDK и доступны в start, компонентах и обработчиках после запуска аддона. Не вызывайте их при импорте модуля. Параметр api, включая api.client и api.pulsesyncApi, также поддерживается.

Для интерфейса используйте slots (playerBarButton, entityHeaderTitleAccessory, entityHeaderMeta, entityHeaderControls) или декларативные действия trackMenuItems, albumMenuItems, playlistMenuItems, playerBarButtons, headerActions и headerItems.

Настройки

// src/settings.ts
import { defineAddonSettings, SettingType } from '@pulsesync/addon-sdk'

export const settings = defineAddonSettings({
    enabled: {
        type: SettingType.BOOLEAN,
        name: 'Включить аддон',
        default: true,
    },
})

Передайте settings в defineAddon({ id, settings, ... }) и addonPlugin({ manifest, settings }). В React читайте значения через settings.use(), в обработчиках — через settings.store.enabled. Поддерживаются boolean, number, select, text, color и file.

Сборка

Начните с готового шаблона, содержащего addon.config.mjs и конфигурацию проекта.

// vite.config.ts
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import { addonPlugin, defineAddonManifest } from '@pulsesync/addon-sdk/vite'
import addonConfig from './addon.config.mjs'
import { settings } from './src/settings'

export default defineConfig({
    plugins: [
        react(),
        addonPlugin({
            manifest: defineAddonManifest(addonConfig),
            settings,
        }),
    ],
})

yarn vite build создаёт dist/<directoryName> с metadata.json, script.js и script.css. SDK включается в bundle каждого аддона; React остаётся внешней зависимостью WebHost.

Важно

• Для внешних запросов укажите разрешённые origin/prefix в allowedUrls файла addon.config.mjs.
• Обновление SDK само по себе не добавляет новые возможности в старый мод: нужен совместимый Runtime и WebHost.
• При отключении аддона его подписки и нативные регистрации очищаются; сохранённые данные storage остаются.
• notifications.show() сохраняет прежнее поведение верхнего тоста; для нижних уведомлений используйте info() или error().

Лицензия: GPL-3.0-or-later.