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

Ekranı aşağı kaydırarak yenile bileşeni, kullanıcıların verileri yenilemek için uygulama içeriğinin başında ekranı aşağı kaydırmasına olanak tanır.

API yüzeyi

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

  • isRefreshing: Yenileme işleminin şu anda 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: Ekranı aşağı kaydırarak yenileme işleminde gösterilen göstergeyi özelleştirir.

Temel örnek

Bu snippet'te PullToRefreshBox işlevinin temel kullanımı gösterilmektedir:

@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) })
            }
        }
    }
}
PullToRefreshBox.kt

Kodla ilgili önemli noktalar

  • PullToRefreshBox, dizelerin listesini görüntüleyen bir LazyColumn öğesini sarar.
  • PullToRefreshBox için isRefreshing ve onRefresh parametreleri gerekir.
  • PullToRefreshBox bloğu içindeki içerik, kaydırılabilir içeriği temsil eder.

Sonuç

Bu videoda, önceki koddaki temel "sürükle ve yenile" uygulaması gösterilmektedir:

Şekil 1. Öğe listesinde temel bir "sürükleyerek yenileme" 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) })
            }
        }
    }
}
PullToRefreshBox.kt

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 birlikte sunulan "sürükleyerek yenile" özelliği gösterilmektedir:

Şekil 2. Özel bir stil içeren, kaydırarak yenileme uygulaması.

İleri seviye örnek: Tamamen özelleştirilmiş bir gösterge oluşturma

Mevcut bileşenlerden ve animasyonlardan yararlanarak karmaşık özel göstergeler oluşturabilirsiniz.Bu snippet'te, sürükleyerek yenileme uygulamanızda tamamen özel bir göstergenin nasıl oluşturulacağı gösterilmektedir:

@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.pullToRefreshIndicator(
            state = state,
            isRefreshing = isRefreshing,
            containerColor = PullToRefreshDefaults.containerColor,
            threshold = PositionalThreshold
        ),
        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
                        }
                )
            }
        }
    }
}
PullToRefreshBox.kt

Kodla ilgili önemli noktalar

  • Önceki snippet'te, kitaplık tarafından sağlanan Indicator kullanılıyordu. Bu snippet, MyCustomIndicator adlı özel bir gösterge bileşeni oluşturur. Bu bileşimde pullToRefreshIndicator değiştirici, konumlandırmayı ve yenilemeyi tetiklemeyi yönetir.
  • Önceki snippet'te olduğu gibi, PullToRefreshState örneği ayıklanmıştır. Bu nedenle, aynı örnek hem PullToRefreshBox hem de pullToRefreshModifier'ye iletilebilir.
  • Kapsayıcı rengi ve konum eşiği, PullToRefreshDefaults sınıfından alınır. Böylece, 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ı ekranı aşağı kaydırdığında bulut simgesi büyür ve yenileme işlemi başladığında CircularProgressIndicator simgesine geçer.
    • targetState, hangi durumun (bulut simgesi veya dairesel ilerleme durumu göstergesi) gösterileceğini belirlemek için isRefreshing'u kullanır.
    • animationSpec, geçiş için CROSSFADE_DURATION_MILLIS süresiyle tween animasyonu tanımlar.
    • state.distanceFraction, kullanıcının ekranı ne kadar aşağı çektiğini gösterir. Bu değer 0f (çekme yok) ile 1f (tamamen çekilmiş) 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 bir göstergeyle yenilemeyi sürükleyin uygulaması.

Ek kaynaklar