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

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

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

از ترکیب‌پذیر 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(
                    painter = rememberVectorPainter(AppIcons.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 مقیاس و شفافیت را اصلاح می‌کند.

نتیجه

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

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

منابع بیشتر