بکشید تا تازه شود

مولفه کشش برای تازه کردن به کاربران این امکان را می دهد که در ابتدای محتوای برنامه به سمت پایین بکشند تا داده ها را تازه کنند.

سطح API

از PullToRefreshBox composable برای اجرای pull-to-refresh استفاده کنید که به عنوان محفظه ای برای محتوای قابل پیمایش شما عمل می کند. پارامترهای کلیدی زیر رفتار و ظاهر تازه سازی را کنترل می کنند:

  • isRefreshing : یک مقدار بولی که نشان می دهد آیا عمل تازه سازی در حال حاضر در حال انجام است یا خیر.
  • onRefresh : یک تابع لامبدا که زمانی اجرا می شود که کاربر یک رفرش را شروع می کند.
  • indicator : نشانگر را که روی کشش برای تازه کردن کشیده می شود سفارشی می کند.

مثال اساسی

این قطعه کاربرد اصلی PullToRefreshBox را نشان می دهد: 

@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

نکات کلیدی در مورد کد

  • PullToRefreshBox یک LazyColumn می‌پیچد که لیستی از رشته‌ها را نمایش می‌دهد.
  • PullToRefreshBox به پارامترهای isRefreshing و onRefresh نیاز دارد.
  • محتوای داخل بلوک PullToRefreshBox محتوای قابل پیمایش را نشان می دهد.

نتیجه

این ویدیو اجرای اساسی کشش برای تازه کردن را از کد قبلی نشان می دهد:

شکل 1 . یک اجرای اساسی کشش برای تازه کردن در لیستی از موارد.

مثال پیشرفته: سفارشی کردن رنگ نشانگر 

@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

نکات کلیدی در مورد کد

  • رنگ نشانگر از طریق ویژگی containerColor و color در پارامتر indicator سفارشی می شود.
  • rememberPullToRefreshState() وضعیت اکشن تازه سازی را مدیریت می کند. شما از این حالت در ارتباط با پارامتر indicator استفاده می کنید.

نتیجه

این ویدئو اجرای pull-to-refresh را با نشانگر رنگی نشان می دهد:

شکل 2 . اجرای کشش به تازه کردن با سبک سفارشی.

مثال پیشرفته: یک نشانگر کاملا سفارشی ایجاد کنید

می‌توانید با استفاده از قابلیت‌های ترکیب‌سازی و انیمیشن‌های موجود، شاخص‌های سفارشی پیچیده ایجاد کنید. این قطعه نشان می‌دهد که چگونه می‌توانید یک نشانگر کاملاً سفارشی در پیاده‌سازی pull-to-fresh ایجاد کنید: 

@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

نکات کلیدی در مورد کد

  • قطعه قبلی از Indicator ارائه شده توسط کتابخانه استفاده می کرد. این قطعه یک نشانگر سفارشی به نام MyCustomIndicator ایجاد می کند. در این composable، اصلاح‌کننده pullToRefreshIndicator موقعیت‌یابی و راه‌اندازی یک تازه‌سازی را انجام می‌دهد.
  • مانند قطعه قبلی، نمونه PullToRefreshState استخراج شده است، بنابراین همان نمونه را می توان به PullToRefreshBox و pullToRefreshModifier ارسال کرد.
  • رنگ ظرف و آستانه موقعیت از کلاس PullToRefreshDefaults استفاده می شود. به این ترتیب، می‌توانید از رفتار و استایل پیش‌فرض از کتابخانه Material استفاده مجدد کنید، در حالی که فقط عناصری را که به آن‌ها علاقه دارید سفارشی کنید.
  • MyCustomIndicator از Crossfade برای انتقال بین نماد ابر و CircularProgressIndicator استفاده می کند. با کشیدن کاربر، نماد ابر بزرگ می‌شود و با شروع عملیات به‌روزرسانی، به یک CircularProgressIndicator منتقل می‌شود.
    • targetState از isRefreshing برای تعیین حالت نمایش (نماد ابر یا نشانگر پیشرفت دایره ای) استفاده می کند.
    • animationSpec یک انیمیشن tween برای انتقال با مدت زمان مشخص CROSSFADE_DURATION_MILLIS تعریف می کند.
    • state.distanceFraction نشان دهنده میزانی است که کاربر به سمت پایین کشیده شده است، از 0f (بدون کشش) تا 1f (کاملا کشیده شده).
    • اصلاح کننده graphicsLayer مقیاس و شفافیت را اصلاح می کند.

نتیجه

این ویدیو نشانگر سفارشی کد قبلی را نشان می دهد:

شکل 3 . اجرای کشش برای تازه کردن با یک نشانگر سفارشی.

منابع اضافی