easydev991/loading-overlay

Блокировка контента при загрузке (Loading Overlay)

When to Use

• Используй этот навык, когда разрабатываешь экран с загрузкой данных с сервера
• Используй этот навык, когда реализуешь операции CRUD (создание, обновление, удаление)
• Используй этот навык, когда нужно блокировать кнопки и интерактивные элементы во время обработки
• Используй этот навык, когда пользователь должен видеть прогресс выполнения операции
• Этот навык полезен для предотвращения повторных действий пользователя во время ожидания
• Этот навык обеспечивает последовательный UX при загрузке данных

Основной подход

Шаг 1: ViewModel - добавление состояния загрузки

В ViewModel добавь StateFlow<Boolean> для отслеживания состояния загрузки:

private val _isProcessing = MutableStateFlow(false)
val isProcessing: StateFlow<Boolean> = _isProcessing.asStateFlow()

В методах операций устанавливай _isProcessing.value = true в начале и _isProcessing.value = false в блоке finally.

Шаг 2: UI - передача состояния загрузки

В Composable экране собери состояние через collectAsState() и передай в безымянный компонент:

val isProcessing by viewModel.isProcessing.collectAsState()

MyFriendsScreenContent(
    // другие параметры...
    isProcessing = isProcessing
)

Шаг 3: Безымянный компонент - блокировка и индикатор

В безымянном компоненте:

1. Передай enabled = !isProcessing в компоненты с контентом
2. Используй LoadingOverlayView из дизайн-системы поверх контента при загрузке

Box(modifier = Modifier.fillMaxSize()) {
    Content(enabled = !isProcessing)

    if (isProcessing) {
        LoadingOverlayView()
    }
}

Примечание: LoadingOverlayView автоматически занимает весь размер родительского Box и блокирует все жесты. Компонент находится в com.swparks.ui.ds.

Шаг 4: Компоненты списка - параметр enabled

В компонентах списка передай enabled в интерактивные элементы:

Box(
    modifier = Modifier.clickable(enabled = enabled) { onClick() }
) {
    UserRowView(/* параметры */)
}

Типичные сценарии использования

Сценарий 1: Загрузка списка с сервера

• Пользователь открывает экран
• Показать индикатор в центре (UiState.Loading)
• После успешной загрузки показать данные (UiState.Success)

Сценарий 2: Действие пользователя над элементом списка

• Пользователь нажимает на кнопку в списке (принять, отклонить, удалить)
• Блокировать все элементы списка (enabled = false)
• Показать индикатор поверх контента (isProcessing = true)
• После успешного выполнения обновить данные и разблокировать (isProcessing = false)

Сценарий 3: Комбинирование нескольких состояний загрузки

• Начальная загрузка данных (isLoading)
• Выполнение асинхронного действия (isProcessing)
• Комбинировать оба состояния через combine или в UI (!isLoading && !isProcessing)

Когда использовать разные варианты индикатора

1. Начальная загрузка данных

Используй обычный CircularProgressIndicator или LoadingIndicator в центре экрана в блоке when для UiState.Loading.

2. Обновление данных или действия пользователя

Используй LoadingOverlayView из дизайн-системы поверх контента в Box с isProcessing. Этот компонент автоматически блокирует все жесты и занимает весь размер родительского контейнера.

3. Индикатор внутри кнопки

Для кнопок с операциями CRUD используй встроенный CircularProgressIndicator или параметр enabled.

Ссылки на примеры

Подробные примеры реализации см. в файле references/EXAMPLES.md:

• Пример 1: MyFriendsScreen - принятие/отклонение заявки в друзья (полный код ViewModel, UI, безымянный компонент, Content)
• Пример 2: MyBlacklistScreen - удаление из черного списка (комбинация нескольких состояний загрузки)
• Пример 3: Комбинирование нескольких состояний загрузки в ViewModel
• Пример 4: Индикатор загрузки внутри кнопки
• Шаблон для нового экрана: готовый шаблон для быстрого создания

Ключевые моменты реализации

1. Box с fillMaxSize для контента

Всегда используй Box с Modifier.fillMaxSize() для контента, чтобы LoadingOverlayView мог отобразиться поверх и корректно заблокировать все жесты.

2. LoadingOverlayView автоматически занимает родительский размер

LoadingOverlayView из дизайн-системы автоматически занимает размер родительского Box и блокирует все жесты. Нет необходимости использовать matchParentSize() или fillMaxSize().

3. try-finally для надежной блокировки

Всегда используй try-finally для гарантированного снятия блокировки при успешном выполнении или ошибке.

4. Передача enabled во все интерактивные элементы

Не забудь передать enabled во все кликабельные элементы: кнопки, кликабельные Box/Row/Surface.

Чек-лист реализации

• [ ] Добавил StateFlow<Boolean> для состояния загрузки в ViewModel
• [ ] Обернул асинхронные операции в try-finally для надежной блокировки
• [ ] Собрал состояние загрузки в Composable экрана через collectAsState()
• [ ] Передал enabled = !isProcessing в безымянный компонент
• [ ] Добавил LoadingOverlayView() из дизайн-системы поверх контента при загрузке
• [ ] Передал enabled в интерактивные элементы списка (кнопки, кликабельные области)
• [ ] Проверил, что оверлей отображается поверх контента при загрузке
• [ ] Проверил, что кнопки заблокированы и не нажимаются во время обработки
• [ ] Протестировал обработку ошибок (пользователь видит ошибку, оверлей скрывается)