برای بازآوری بکشید

کاربران بااستفاده از عنصر «کشیدن برای بازآوری» می‌توانند در ابتدای محتوای برنامه به‌پایین بکشند تا داده‌ها بازآوری شود.

سطح میانای برنامه‌سازی کاربردی

از عنصر PullToRefreshBox قابل ترکیب برای پیاده‌سازی کشیدن برای بازآوری استفاده کنید که به‌عنوان ظرفی برای محتوای پیمایش‌پذیر شما عمل می‌کند. پارامترهای کلیدی زیر رفتار و ظاهر بازآوری را کنترل می‌کنند:

  • 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 LazyColumn را می‌پیچد که فهرستی از رشته‌ها را نمایش می‌دهد.
  • ‫PullToRefreshBox به پارامترهای isRefreshing و onRefresh نیاز دارد.
  • محتوای درون بلوک PullToRefreshBox نشان‌دهنده محتوای پیمایش‌شدنی است.

نتیجه

این ویدیو پیاده‌سازی اولیه کشیدن برای بازآوری را از کد قبلی نشان می‌دهد:

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

مثال پیشرفته: سفارشی‌سازی رنگ نشانگر

@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) })
            }
        }
    }
}

نکات کلیدی درباره کد

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

نتیجه

این ویدیو پیاده‌سازی کشیدن برای بازآوری با نشانگر رنگی را نشان می‌دهد:

شکل ۲. پیاده‌سازی کشیدن برای بازآوری با سبک سفارشی.

مثال پیشرفته: ایجاد شاخص کاملاً سفارشی

با بهره‌گیری از عناصر ترکیبی و پویانمایی‌های موجود می‌توانید نشانگرهای سفارشی پیچیده ایجاد کنید.این گزیده نحوه ایجاد نشانگر کاملاً سفارشی در پیاده‌سازی کشیدن برای بازآوری را نشان می‌دهد:

@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
                        }
                )
            }
        }
    }
}

نکات کلیدی درباره کد

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

نتیجه

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

شکل ۳. پیاده‌سازی کشیدن برای بازآوری با نشانگر سفارشی.

منابع بیشتر