vibration.d.ts

Обзор

Файл vibration.d.ts содержит объявления типов (TypeScript declarations) для взаимодействия с API вибрации браузера и Telegram Web App API. Его основное назначение — обеспечить поддержку автодополнения, проверки типов и документации для функций, связанных с вибрацией и тактильной отдачей, а также для управления основными элементами интерфейса Telegram Web App.

Файл определяет интерфейсы для:

• стандартного Web Vibration API (вибрация устройства),

• расширенного API Telegram Web App с функциями тактильной отдачи, управления кнопками и основными методами жизненного цикла приложения.

Это помогает разработчикам безопасно использовать эти функциональные возможности в TypeScript-проектах, гарантируя корректность параметров и возвращаемых значений.

Подробное описание интерфейсов и методов

1. Web Vibration API

Интерфейс Navigator

interface Navigator {
  vibrate(pattern: number | number[]): boolean;
}

• Описание: Определяет метод vibrate для объекта navigator браузера.

• Метод:

  • vibrate(pattern: number | number[]): boolean

    • Параметры:

      • pattern — либо число (количество миллисекунд вибрации), либо массив чисел (последовательность вибраций и пауз).

    • Возвращаемое значение: boolean — true, если вибрация успешно запущена, иначе false.

• Пример использования:

  navigator.vibrate(200); // вибрирует 200 мс
  navigator.vibrate([100, 50, 100]); // вибрация 100 мс, пауза 50 мс, вибрация 100 мс
  

Интерфейс NavigatorVibration

interface NavigatorVibration {
  vibrate(pattern: number | number[]): boolean;
}

• Аналогично интерфейсу Navigator, используется для расширения объекта navigator.

Объявление переменной

declare let navigator: Navigator & NavigatorVibration;

• Объявляется глобальный объект navigator, обладающий методами обоих интерфейсов.

2. Telegram Web App API

Интерфейс TelegramWebApp

Предоставляет набор методов и свойств для работы с Telegram Web App, включая управление тактильной отдачей, кнопками и жизненным циклом.

Свойство HapticFeedback

HapticFeedback: {
  impactOccurred(style: 'light' | 'medium' | 'heavy' | 'rigid' | 'soft'): void;
  notificationOccurred(type: 'error' | 'success' | 'warning'): void;
  selectionChanged(): void;
};

• Описание: Методы для вызова тактильной отдачи (haptic feedback) на устройстве.

• Методы:

  • impactOccurred(style: 'light' | 'medium' | 'heavy' | 'rigid' | 'soft'): void

    • Вызов тактильного импульса с заданным стилем интенсивности.

  • notificationOccurred(type: 'error' | 'success' | 'warning'): void

    • Вызов тактильного уведомления по типу (ошибка, успех, предупреждение).

  • selectionChanged(): void

    • Вызов тактильного отклика при изменении выбора.

• Пример:

  Telegram.WebApp.HapticFeedback.impactOccurred('medium');
  Telegram.WebApp.HapticFeedback.notificationOccurred('success');
  

Основные методы жизненного цикла

ready(): void;
expand(): void;
close(): void;

• ready() — уведомляет о готовности WebApp к работе.

• expand() — разворачивает WebApp на полный экран.

• close() — закрывает WebApp.

Свойство MainButton

MainButton: {
  text: string;
  color: string;
  textColor: string;
  isVisible: boolean;
  isActive: boolean;
  show(): void;
  hide(): void;
  enable(): void;
  disable(): void;
  showProgress(leaveActive?: boolean): void;
  hideProgress(): void;
  setText(text: string): void;
  onClick(callback: () => void): void;
  offClick(callback: () => void): void;
};

• Описание: Управление основной кнопкой интерфейса Telegram Web App.

• Свойства:

  • text — текст кнопки.

  • color — цвет кнопки.

  • textColor — цвет текста.

  • isVisible — видимость кнопки.

  • isActive — активность кнопки.

• Методы:

  • show() / hide() — показывать/скрывать кнопку.

  • enable() / disable() — активировать/деактивировать кнопку.

  • showProgress(leaveActive?: boolean) — показать индикатор прогресса.

  • hideProgress() — скрыть индикатор прогресса.

  • setText(text: string) — задать текст кнопки.

  • onClick(callback: () => void) — подписаться на событие клика.

  • offClick(callback: () => void) — отписаться от события клика.

• Пример:

  Telegram.WebApp.MainButton.setText("Отправить");
  Telegram.WebApp.MainButton.show();
  Telegram.WebApp.MainButton.onClick(() => {
    console.log("Main button clicked");
  });
  

Свойство BackButton

BackButton: {
  isVisible: boolean;
  show(): void;
  hide(): void;
  onClick(callback: () => void): void;
  offClick(callback: () => void): void;
};

• Описание: Управление кнопкой "Назад".

• Свойства:

  • isVisible — видимость кнопки.

• Методы:

  • show() / hide() — показывать/скрывать кнопку.

  • onClick(callback: () => void) — подписаться на клик.

  • offClick(callback: () => void) — отписаться от клика.

• Пример:

  Telegram.WebApp.BackButton.show();
  Telegram.WebApp.BackButton.onClick(() => {
    Telegram.WebApp.close();
  });
  

Интерфейс Window

interface Window {
  Telegram?: {
    WebApp: TelegramWebApp;
  };
}

• Расширяет глобальный объект window, добавляя опциональное свойство Telegram.WebApp для доступа к API Telegram Web App.

Важные детали реализации и взаимодействия

• Файл не содержит реализации — только декларации типов, предоставляющие контракт для использования API.

• Обеспечивает типовую безопасность при работе с вибрацией устройства и Telegram Web App.

• Позволяет разработчикам легко интегрировать тактильную отдачу и управление UI Telegram WebApp без ошибок типов.

• Взаимодействует с глобальными объектами браузера (navigator, window) и с API Telegram, расширяя их.

• Веб-приложения, использующие этот файл, могут вызывать вибрацию устройства и управлять основными элементами Telegram Web App через типизированный интерфейс.

Взаимодействие с другими частями системы

• Используется в проектах, которые разрабатываются с поддержкой TypeScript, для веб-приложений, работающих внутри Telegram Web App.

• Позволяет интегрировать тактильные эффекты и управление интерфейсом Telegram Web App с помощью стандартных методов.

• В сочетании с остальной частью проекта, отвечающей за UI и логику, vibration.d.ts облегчает вызов системных API и API Telegram.

• Может дополняться другими декларациями типов для работы с Telegram API или Web API.

Mermaid диаграмма — Структура интерфейсов

classDiagram
    class Navigator {
        +vibrate(pattern: number | number[]): boolean
    }
    class NavigatorVibration {
        +vibrate(pattern: number | number[]): boolean
    }
    Navigator <|-- Navigator & NavigatorVibration

    class TelegramWebApp {
        +ready(): void
        +expand(): void
        +close(): void
    }

    class HapticFeedback {
        +impactOccurred(style: string): void
        +notificationOccurred(type: string): void
        +selectionChanged(): void
    }

    class MainButton {
        +text: string
        +color: string
        +textColor: string
        +isVisible: boolean
        +isActive: boolean
        +show(): void
        +hide(): void
        +enable(): void
        +disable(): void
        +showProgress(leaveActive?: boolean): void
        +hideProgress(): void
        +setText(text: string): void
        +onClick(callback: () => void): void
        +offClick(callback: () => void): void
    }

    class BackButton {
        +isVisible: boolean
        +show(): void
        +hide(): void
        +onClick(callback: () => void): void
        +offClick(callback: () => void): void
    }

    TelegramWebApp "1" *-- "1" HapticFeedback : has
    TelegramWebApp "1" *-- "1" MainButton : has
    TelegramWebApp "1" *-- "1" BackButton : has

Итог

Файл vibration.d.ts — это декларация типов для работы с вибрацией устройства и Telegram Web App API. Он предоставляет строгие интерфейсы для вызова системных функций вибрации и управления элементами UI Telegram Web App (кнопками, тактильной обратной связью, жизненным циклом). Использование этого файла в TypeScript-проектах повышает стабильность, удобство разработки и снижает риск ошибок при интеграции с этими API.