Yenilemek için aşağı çekin.

Yenilemek için çekme bileşeni, kullanıcıların verileri yenilemek için uygulamanın içeriğinin başında aşağı doğru çekmesine olanak tanır.

API yüzeyi

Kaydırılabilir içeriğiniz için kapsayıcı görevi gören, aşağı çekerek yenileme özelliğini uygulamak üzere PullToRefreshBox composable'ını kullanın. Yenileme davranışını ve görünümünü aşağıdaki temel parametreler kontrol eder:

  • isRefreshing: Yenileme işleminin devam edip etmediğini belirten bir boole değeri.
  • onRefresh: Kullanıcı yenileme işlemi başlattığında yürütülen bir lambda işlevi.
  • indicator: Sistem tarafından çekerek yenileme işleminde kullanılan göstergeyi özelleştirir.

Temel örnek

Bu snippet, PullToRefreshBox'nın temel kullanımını gösterir:

@Composable
fun PullToRefreshBasicSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}

Kodla ilgili önemli noktalar

  • PullToRefreshBox, bir LazyColumn öğesini sarar. Bu öğe, bir dize listesini görüntüler.
  • PullToRefreshBox için isRefreshing ve onRefresh parametreleri gerekir.
  • PullToRefreshBox bloğundaki içerik, kaydırılabilir içeriği temsil eder.

Sonuç

Bu videoda, önceki koddan alınan temel çekerek yenileme uygulaması gösterilmektedir:

Şekil 1. Öğeler listesinde temel bir yenilemek için çekme uygulaması.

Gelişmiş örnek: Gösterge rengini özelleştirme

@Composable
fun PullToRefreshCustomStyleSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    val state = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier,
        state = state,
        indicator = {
            Indicator(
                modifier = Modifier.align(Alignment.TopCenter),
                isRefreshing = isRefreshing,
                containerColor = MaterialTheme.colorScheme.primaryContainer,
                color = MaterialTheme.colorScheme.onPrimaryContainer,
                state = state
            )
        },
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}

Kodla ilgili önemli noktalar

  • Gösterge rengi, indicator parametresindeki containerColor ve color özellikleri aracılığıyla özelleştirilir.
  • rememberPullToRefreshState(), yenileme işleminin durumunu yönetir. Bu durumu indicator parametresiyle birlikte kullanırsınız.

Sonuç

Bu videoda, renkli bir göstergeyle yenilemek için çekme işleminin nasıl uygulandığı gösterilmektedir:

Şekil 2. Özel stile sahip bir yenilemek için çekme uygulaması.

Gelişmiş örnek: Tamamen özelleştirilmiş bir gösterge oluşturma

Mevcut composable'ları ve animasyonları kullanarak karmaşık özel göstergeler oluşturabilirsiniz.Bu snippet, çekerek yenileme uygulamanızda tamamen özel bir göstergenin nasıl oluşturulacağını gösterir:

@Composable
fun PullToRefreshCustomIndicatorSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    val state = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier,
        state = state,
        indicator = {
            MyCustomIndicator(
                state = state,
                isRefreshing = isRefreshing,
                modifier = Modifier.align(Alignment.TopCenter)
            )
        }
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}

// ...
@Composable
fun MyCustomIndicator(
    state: PullToRefreshState,
    isRefreshing: Boolean,
    modifier: Modifier = Modifier,
) {
    Box(
        modifier = modifier.pullToRefresh(
            state = state,
            isRefreshing = isRefreshing,
            threshold = PositionalThreshold,
            onRefresh = {

            }
        ),
        contentAlignment = Alignment.Center
    ) {
        Crossfade(
            targetState = isRefreshing,
            animationSpec = tween(durationMillis = CROSSFADE_DURATION_MILLIS),
            modifier = Modifier.align(Alignment.Center)
        ) { refreshing ->
            if (refreshing) {
                CircularProgressIndicator(Modifier.size(SPINNER_SIZE))
            } else {
                val distanceFraction = { state.distanceFraction.coerceIn(0f, 1f) }
                Icon(
                    imageVector = Icons.Filled.CloudDownload,
                    contentDescription = "Refresh",
                    modifier = Modifier
                        .size(18.dp)
                        .graphicsLayer {
                            val progress = distanceFraction()
                            this.alpha = progress
                            this.scaleX = progress
                            this.scaleY = progress
                        }
                )
            }
        }
    }
}

Kodla ilgili önemli noktalar

  • Önceki snippet, kitaplık tarafından sağlanan Indicator öğesini kullanıyordu. Bu snippet, MyCustomIndicator adlı özel bir gösterge oluşturur. Bu composable'da pullToRefreshIndicator değiştiricisi, konumlandırmayı ve yenilemeyi tetiklemeyi yönetir.
  • Önceki snippet'te olduğu gibi, örnek PullToRefreshState örneğini ayıklar. Böylece, aynı örneği hem PullToRefreshBox hem de pullToRefreshModifier'ye iletebilirsiniz.
  • Örnekte, PullToRefreshDefaults sınıfındaki kapsayıcı rengi ve konum eşiği kullanılmaktadır. Bu şekilde, yalnızca ilgilendiğiniz öğeleri özelleştirirken Material kitaplığındaki varsayılan davranışı ve stili yeniden kullanabilirsiniz.
  • MyCustomIndicator, bulut simgesi ile CircularProgressIndicator arasında geçiş yapmak için Crossfade kullanır. Kullanıcı çektiğinde bulut simgesi büyür ve yenileme işlemi başladığında CircularProgressIndicator simgesine dönüşür.
    • targetState, hangi durumun gösterileceğini (bulut simgesi veya dairesel ilerleme durumu göstergesi) belirlemek için isRefreshing özelliğini kullanır.
    • animationSpec, geçiş için tween animasyonunu CROSSFADE_DURATION_MILLIS süresiyle tanımlar.
    • state.distanceFraction, kullanıcının ne kadar aşağı çektiğini gösterir. Değer, 0f (çekilmedi) ile 1f (tamamen çekildi) arasında değişir.
    • graphicsLayer değiştiricisi, ölçeği ve şeffaflığı değiştirir.

Sonuç

Bu videoda, önceki koddaki özel gösterge gösterilmektedir:

Şekil 3. Özel göstergeli bir yenilemek için çekme uygulaması.

Ek kaynaklar