459 lines
12 KiB
Markdown
459 lines
12 KiB
Markdown
# Документация Telegram Mini Apps SDK
|
||
|
||
## Оглавление
|
||
1. [Установка и инициализация](#установка-и-инициализация)
|
||
- [Установка пакета](#установка-пакета)
|
||
- [Инициализация SDK](#инициализация-sdk)
|
||
2. [Основные концепции](#основные-концепции)
|
||
- [Области (Scopes)](#области-scopes)
|
||
- [Предварительные требования](#предварительные-требования)
|
||
- [Доступность методов](#доступность-методов)
|
||
3. [Компоненты интерфейса](#компоненты-интерфейса)
|
||
- [Back Button (Кнопка "Назад")](#back-button)
|
||
- [Main Button (Основная кнопка)](#main-button)
|
||
- [Secondary Button (Вторичная кнопка)](#secondary-button)
|
||
- [Settings Button (Кнопка настроек)](#settings-button)
|
||
4. [Управление приложением](#управление-приложением)
|
||
- [Mini App](#mini-app)
|
||
- [Viewport (Область просмотра)](#viewport)
|
||
- [Theme Params (Параметры темы)](#theme-params)
|
||
- [Init Data (Данные инициализации)](#init-data)
|
||
5. [Хранение и безопасность](#хранение-и-безопасность)
|
||
- [Cloud Storage (Облачное хранилище)](#cloud-storage)
|
||
- [Privacy (Конфиденциальность)](#privacy)
|
||
6. [Взаимодействие с пользователем](#взаимодействие-с-пользователем)
|
||
- [Haptic Feedback (Тактильный отклик)](#haptic-feedback)
|
||
- [Popup (Всплывающее окно)](#popup)
|
||
- [QR Scanner (Сканер QR-кодов)](#qr-scanner)
|
||
7. [Поведение приложения](#поведение-приложения)
|
||
- [Closing Behavior (Поведение при закрытии)](#closing-behavior)
|
||
- [Swipe Behavior (Поведение при свайпе)](#swipe-behavior)
|
||
8. [Дополнительные функции](#дополнительные-функции)
|
||
- [Emoji Status](#emoji-status)
|
||
- [Links (Ссылки)](#links)
|
||
- [Invoice (Счета)](#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');
|
||
\`\`\`
|