Flutter Future Progress Dialog

Проблема

Большинству Flutter-приложений приходится выполнять задачи, занимающие несколько секунд — загрузка данных из API, отправка файла или обработка платежа. В это время пользователь видит застывший экран без каких-либо признаков того, что что-то происходит. Он нажимает кнопку повторно, вызывает дублирующие запросы или решает, что приложение зависло.

Стандартное решение — вручную управлять состоянием загрузки: переключить флаг, показать спиннер, дождаться завершения future, скрыть спиннер, а затем обработать результат или ошибку. Эта логика дублируется на десятках экранов с мелкими различиями каждый раз.

Типичные проблемы:

• Повторяющийся шаблонный код управления состоянием загрузки на каждом экране
• Повторные нажатия пользователей из-за отсутствия визуальной обратной связи
• Закрытые диалоги, которые оставляют «осиротевшие» future, продолжающие работу в фоне
• Непоследовательная обработка ошибок — одни экраны перехватывают исключения, другие падают молча

Как flutter_future_progress_dialog решает эту задачу

flutter_future_progress_dialog заменяет весь этот шаблонный код одним вызовом функции. Передайте асинхронную задачу — пакет покажет незакрываемый диалог прогресса, дождётся результата, закроет диалог и вернёт типобезопасный результат: Success со значением или Failure с ошибкой.

Обработка ошибок встроена в тип результата, поэтому вы никогда не забудете перехватить исключение.

Возможности

• Material-диалог — showProgressDialog отображает стандартный круговой индикатор прогресса в стиле Material
• Cupertino-диалог — showCupertinoProgressDialog показывает индикатор активности в стиле iOS
• Адаптивный диалог — showAdaptiveProgressDialog автоматически выбирает стиль, соответствующий текущей платформе
• Пользовательский интерфейс диалога — передайте builder, чтобы заменить стандартный индикатор любым виджетом
• Типобезопасные результаты — ProgressDialogResult<T> — sealed-класс с вариантами Success и Failure, поддерживающий pattern matching и удобные методы unwrap() и map()
• Перехват ошибок — Failure содержит объект ошибки и трассировку стека

Сценарии использования

Обработка платежей

Экран оформления заказа вызывает API платёжного шлюза. Без диалога прогресса пользователи нажимают «Оплатить» повторно, когда ничего не происходит, вызывая двойные списания. С showProgressDialog диалог остаётся на экране и блокирует взаимодействие до ответа шлюза, а затем pattern matching результата позволяет перейти на экран подтверждения или ошибки.

Загрузка файлов

Сканер документов отправляет изображения на сервер. Загрузка может занять несколько секунд на медленном соединении. Оборачивание загрузки в showAdaptiveProgressDialog даёт пользователям мгновенную визуальную обратную связь и гарантирует соответствие стилю платформы — Material на Android, Cupertino на iOS.

Отправка форм

Многошаговая форма отправляет данные на сервер на финальном этапе. Использование диалога прогресса предотвращает повторную отправку и даёт чистый результат Success/Failure для принятия решения — показать экран успеха или сообщение об ошибке.

Фоновая синхронизация данных

CRM-приложение синхронизирует локальные изменения с удалённым сервером. Пользовательский builder может показать брендированную анимацию загрузки вместо стандартного спиннера, сохраняя единый стиль приложения.

Начало работы

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

flutter pub add flutter_future_progress_dialog

Затем вызовите showProgressDialog с вашей асинхронной задачей:

final result = await showProgressDialog(
  context: context,
  future: () => fetchData(),
);

switch (result) {
  case Success(:final value):
    // Используйте значение
  case Failure(:final error):
    // Обработайте ошибку
}

Доступны три функции диалога: showProgressDialog (Material), showCupertinoProgressDialog (Cupertino) и showAdaptiveProgressDialog (автоматический выбор платформы). Все принимают необязательный параметр builder для пользовательского интерфейса.

Полный рабочий пример доступен в директории example.