StickerAI-Front/документация sdk telegram.md

Документация Telegram Mini Apps SDK

Оглавление

1. Установка и инициализация
   • Установка пакета
   • Инициализация SDK
2. Основные концепции
   • Области (Scopes)
   • Предварительные требования
   • Доступность методов
3. Компоненты интерфейса
   • Back Button (Кнопка "Назад")
   • Main Button (Основная кнопка)
   • Secondary Button (Вторичная кнопка)
   • Settings Button (Кнопка настроек)
4. Управление приложением
   • Mini App
   • Viewport (Область просмотра)
   • Theme Params (Параметры темы)
   • Init Data (Данные инициализации)
5. Хранение и безопасность
   • Cloud Storage (Облачное хранилище)
   • Privacy (Конфиденциальность)
6. Взаимодействие с пользователем
   • Haptic Feedback (Тактильный отклик)
   • Popup (Всплывающее окно)
   • QR Scanner (Сканер QR-кодов)
7. Поведение приложения
   • Closing Behavior (Поведение при закрытии)
   • Swipe Behavior (Поведение при свайпе)
8. Дополнительные функции
   • Emoji Status
   • Links (Ссылки)
   • Invoice (Счета)

Установка и инициализация

Установка пакета

Перед установкой важно определить, какой пакет вам нужен. Это зависит от используемой библиотеки:

• React: `@telegram-apps/sdk-react`
• Vue: `@telegram-apps/sdk-vue`
• Svelte: `@telegram-apps/sdk-svelte`
• Для других случаев: `@telegram-apps/sdk`

Установка через npm: ```bash npm install @telegram-apps/sdk-react # для React

или

npm install @telegram-apps/sdk # для других случаев ```

Важно: Не устанавливайте оба пакета одновременно, это может привести к ошибкам.

Инициализация SDK

SDK требует ручной инициализации:

```typescript import { init } from '@telegram-apps/sdk';

init({ acceptCustomStyles?: boolean, // принимать ли стили от Telegram version?: Version, // максимальная поддерживаемая версия postEvent?: PostEventFn | 'strict' | 'non-strict' // функция отправки событий }); ```

Основные концепции

Области (Scopes)

SDK использует концепцию областей (scopes) для группировки функциональности:

1. 💠Компоненты - экспортируются как переменная и набор функций: ```typescript import { backButton, showBackButton } from '@telegram-apps/sdk';

backButton.show(); // через переменную showBackButton(); // через функцию ```

2. ⚙️Утилиты - экспортируются как набор функций: ```typescript import { openLink, shareURL } from '@telegram-apps/sdk'; ```

Предварительные требования

Для использования методов SDK необходимо:

1. SDK должен быть инициализирован
2. Код должен выполняться внутри Telegram Mini Apps
3. Для компонентов: родительский компонент должен быть смонтирован

Доступность методов

Проверка доступности метода:

```typescript if (backButton.show.isAvailable()) { backButton.show(); }

// Или с автоматической проверкой backButton.show.ifAvailable(); ```

Компоненты интерфейса

Back Button

Кнопка "Назад" в Telegram Mini Apps.

Монтирование: ```typescript if (backButton.mount.isAvailable()) { backButton.mount(); } ```

Управление видимостью: ```typescript backButton.show(); backButton.hide(); backButton.isVisible(); // проверка видимости ```

Обработка кликов: ```typescript function listener() { console.log('Clicked!'); }

const offClick = backButton.onClick(listener); // или backButton.onClick(listener); backButton.offClick(listener); ```

Main Button

Основная кнопка в нижней части экрана.

Монтирование: ```typescript if (mainButton.mount.isAvailable()) { mainButton.mount(); } ```

Настройка параметров: ```typescript mainButton.setParams({ backgroundColor: '#000000', hasShineEffect: true, isEnabled: true, isLoaderVisible: true, isVisible: true, text: 'Нажми меня', textColor: '#ffffff' }); ```

Secondary Button

Вторичная кнопка для дополнительных действий.

Монтирование: ```typescript if (secondaryButton.mount.isAvailable()) { secondaryButton.mount(); } ```

Настройка параметров: ```typescript secondaryButton.setParams({ backgroundColor: '#000000', hasShineEffect: true, isEnabled: true, isLoaderVisible: true, isVisible: true, position: 'top', text: 'Дополнительное действие', textColor: '#ffffff' }); ```

Settings Button

Кнопка настроек в интерфейсе приложения.

Монтирование: ```typescript if (settingsButton.mount.isAvailable()) { settingsButton.mount(); } ```

Управление видимостью: ```typescript settingsButton.show(); settingsButton.hide(); ```

Управление приложением

Mini App

Управление функциональностью Telegram Mini Apps.

Монтирование: ```typescript if (miniApp.mount.isAvailable()) { miniApp.mount(); } ```

CSS переменные: ```typescript miniApp.bindCssVars(); // создает --tg-bg-color, --tg-header-color // или miniApp.bindCssVars(key => `--my-prefix-${key}`); ```

Управление цветами: ```typescript miniApp.setHeaderColor('bg_color'); miniApp.setBackgroundColor('#ffffff'); ```

Viewport

Управление областью просмотра.

Монтирование: ```typescript if (viewport.mount.isAvailable()) { viewport.mount(); } ```

CSS переменные: ```typescript viewport.bindCssVars(); // создает --tg-viewport-height, --tg-viewport-width ```

Полноэкранный режим: ```typescript await viewport.requestFullscreen(); await viewport.exitFullscreen(); ```

Theme Params

Параметры темы приложения.

Монтирование: ```typescript if (themeParams.mount.isAvailable()) { themeParams.mount(); } ```

CSS переменные: ```typescript themeParams.bindCssVars(); // создает --tg-theme-button-color и др. ```

Доступные параметры: ```typescript themeParams.backgroundColor(); themeParams.textColor(); themeParams.buttonColor(); // и другие... ```

Init Data

Данные инициализации приложения.

Восстановление состояния: ```typescript initData.restore(); ```

Парсинг данных: ```typescript const data = parseInitData('auth_date=123&query_id=anQQ231vs&...'); ```

Доступные данные: ```typescript initData.user(); // информация о пользователе initData.authDate(); // дата авторизации initData.startParam(); // стартовый параметр // и другие... ```

Хранение и безопасность

Cloud Storage

Облачное хранилище для данных.

Операции с данными: ```typescript // Сохранение await cloudStorage.setItem('key', 'value');

// Получение const value = await cloudStorage.getItem('key'); const keys = await cloudStorage.getKeys();

// Удаление await cloudStorage.deleteItem('key'); ```

Privacy

Функции для работы с конфиденциальными данными.

Запрос доступа: ```typescript // Доступ к телефону const phoneStatus = await requestPhoneAccess();

// Доступ к отправке сообщений const writeStatus = await requestWriteAccess();

// Получение контакта const contact = await requestContact(); ```

Взаимодействие с пользователем

Haptic Feedback

Тактильный отклик.

Типы обратной связи: ```typescript // Импульс hapticFeedback.impactOccurred('medium');

// Уведомление hapticFeedback.notificationOccurred('success');

// Изменение выбора hapticFeedback.selectionChanged(); ```

Popup

Всплывающие окна.

Открытие окна: ```typescript const result = await popup.open({ title: 'Заголовок', message: 'Сообщение', buttons: [ { id: 'ok', type: 'default', text: 'OK' } ] }); ```

QR Scanner

Сканер QR-кодов.

Использование: ```typescript // С callback const result = await qrScanner.open({ text: 'Отсканируйте QR-код', onCaptured(qr) { console.log('Отсканировано:', qr); } });

// С promise const qr = await qrScanner.open({ text: 'Отсканируйте QR-код', capture: (qr) => qr === 'ожидаемый-код' }); ```

Поведение приложения

Closing Behavior

Управление поведением при закрытии.

Подтверждение закрытия: ```typescript closingBehavior.enableConfirmation(); closingBehavior.disableConfirmation(); ```

Swipe Behavior

Управление свайпами.

Вертикальные свайпы: ```typescript swipeBehavior.enableVertical(); swipeBehavior.disableVertical(); ```

Дополнительные функции

Emoji Status

Управление статусом эмодзи.

Установка статуса: ```typescript // Запрос доступа const status = await requestEmojiStatusAccess();

// Установка статуса await setEmojiStatus('5361800828313167608', 86400); // на 24 часа ```

Links

Работа со ссылками.

Открытие ссылок: ```typescript // Внешняя ссылка openLink('https://telegram.org', { tryBrowser: 'chrome', tryInstantView: true });

// Telegram ссылка openTelegramLink('https://t.me/username');

// Поделиться shareURL('https://t.me/channel', 'Описание'); ```

Invoice

Работа со счетами.

Открытие счета: ```typescript // По slug await invoice.open('invoice-slug');

// По URL await invoice.open('https://t.me/invoice/slug', 'url'); ```