# Документация 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');
\`\`\`