easydev991/pull-to-refresh

Pull-to-Refresh в Jetpack Compose

When to Use

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

Architecture

ViewModel Layer

Обязательные компоненты:

1. Состояние обновления (_isRefreshing) - отдельное StateFlow для управления состоянием загрузки
2. Метод обновления (например, refreshProfile()) - вызывает загрузку данных с сервера
3. Логирование - запись операций обновления для отладки
4. Обработка ошибок - ошибки при обновлении не должны менять основной UI State

Важные правила:

• Используй отдельный isRefreshing StateFlow вместо основного uiState
• Обновление данных НЕ должно менять основной uiState (используй параметр updateUiState = false)
• Всегда сбрасывай _isRefreshing в finally блоке
• Логируй начало и конец операции обновления

UI Layer

Обязательные компоненты:

1. PullToRefreshBox - контейнер Material 3 для pull-to-refresh
2. rememberPullToRefreshState - состояние жеста pull-to-refresh
3. PullToRefreshDefaults.Indicator - индикатор обновления
4. Вертикальная прокрутка - контент должен поддерживать вертикальную прокрутку

Важные правила:

• Оберни весь прокручиваемый контент в PullToRefreshBox
• Используй rememberScrollState для verticalScroll
• Настрой позиционирование индикатора с отступами от безопасных зон
• Подписывайся на isRefreshing из ViewModel

Instructions

Шаг 1: Добавь состояние обновления в ViewModel

Создай отдельное StateFlow для состояния обновления:

// Состояние обновления данных (pull-to-refresh)
private val _isRefreshing = MutableStateFlow(false)
val isRefreshing: StateFlow<Boolean> = _isRefreshing.asStateFlow()

Шаг 2: Создай метод обновления данных

Добавь метод, который обновляет данные с сервера:

/**
 * Обновляет данные с сервера (для pull-to-refresh).
 */
fun refreshData() {
    val data = currentData.value ?: run {
        logger.w(TAG, "Пропускаем обновление: данные отсутствуют")
        return
    }

    viewModelScope.launch {
        try {
            _isRefreshing.update { true }
            logger.i(TAG, "Начало обновления данных: ${data.id}")

            // Загрузка данных с сервера
            loadDataFromServer(data.id, updateUiState = false)
        } catch (e: Exception) {
            val errorMessage = "Ошибка обновления данных: ${e.message}"
            logger.e(TAG, errorMessage)
        } finally {
            _isRefreshing.update { false }
        }
    }
}

Шаг 3: Обнови UI для pull-to-refresh

Используй PullToRefreshBox для обертки контента:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun MyScreen(
    modifier: Modifier = Modifier,
    viewModel: MyViewModel,
) {
    val scope = rememberCoroutineScope()

    // Получаем состояние обновления (isRefreshing)
    val isRefreshing by viewModel.isRefreshing.collectAsState()

    // Состояние для pull-to-refresh
    val pullRefreshState = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = { viewModel.refreshData() },
        state = pullRefreshState,
        modifier = modifier.fillMaxSize(),
        indicator = {
            PullToRefreshDefaults.Indicator(
                state = pullRefreshState,
                isRefreshing = isRefreshing,
                modifier = Modifier
                    .align(Alignment.TopCenter)
                    .padding(top = dimensionResource(R.dimen.spacing_regular))
            )
        }
    ) {
        Column(
            modifier = Modifier
                .fillMaxSize()
                .verticalScroll(rememberScrollState())
                .padding(dimensionResource(R.dimen.spacing_regular)),
            verticalArrangement = Arrangement.spacedBy(dimensionResource(R.dimen.spacing_small))
        ) {
            // Твой контент здесь
        }
    }
}

Required Imports

Для использования pull-to-refresh необходимы следующие импорты:

ViewModel

import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch

UI (Compose)

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.pulltorefresh.PullToRefreshBox
import androidx.compose.material3.pulltorefresh.PullToRefreshDefaults
import androidx.compose.material3.pulltorefresh.rememberPullToRefreshState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.dimensionResource

Common Mistakes

Ошибка 1: Использование основного uiState для isRefreshing

Проблема: Обновление данных меняет основной UI State, что вызывает перерисовку всего экрана.

Решение: Используй отдельное isRefreshing StateFlow для управления состоянием загрузки.

Ошибка 2: Отсутствие finally блока

Проблема: Если при обновлении происходит ошибка, состояние isRefreshing остается true навсегда.

Решение: Всегда сбрасывай _isRefreshing в finally блоке.

Ошибка 3: Отсутствие вертикальной прокрутки

Проблема: Pull-to-refresh не работает, потому что контент не поддерживает прокрутку.

Решение: Оберни контент в Column с verticalScroll(rememberScrollState()).

Ошибка 4: Неверное позиционирование индикатора

Проблема: Индикатор перекрывается TopAppBar или другими элементами.

Решение: Используй top = dimensionResource(R.dimen.spacing_regular) для отступа индикатора.

Testing

Unit-тесты ViewModel

Тестируй метод обновления данных:

@Test
fun refreshData_whenCalled_thenUpdatesIsRefreshing() = runTest {
    // Given
    mainDispatcherRule.advanceUntilIdle()

    // When
    viewModel.refreshData()
    advanceUntilIdle()

    // Then
    assertEquals(false, viewModel.isRefreshing.value)
}

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

Более подробные примеры кода см. в файле references/EXAMPLES.md.

Доступные примеры

• Полная реализация ProfileViewModel - пример с состоянием isRefreshing и методом refreshProfile()
• Полная реализация ProfileRootScreen - пример с PullToRefreshBox и индикатором обновления
• Пример для списков (LazyColumn) - адаптация pull-to-refresh для списков