اسحب للأسفل لإعادة التحميل.

يتيح مكوّن السحب للأسفل لإعادة التحميل للمستخدمين السحب للأسفل في بداية محتوى التطبيق لإعادة تحميل البيانات.

مساحة عرض واجهة برمجة التطبيقات

استخدِم الدالة المركّبة PullToRefreshBox لتنفيذ ميزة "السحب للأسفل لإعادة التحميل"، والتي تعمل كحاوية للمحتوى القابل للتمرير. تتحكّم المَعلمات الرئيسية التالية في سلوك إعادة التحميل ومظهره:

  • ‫isRefreshing: قيمة منطقية تشير إلى ما إذا كان إجراء إعادة التحميل قيد التنفيذ.
  • ‫onRefresh: دالة lambda يتم تنفيذها عندما يبدأ المستخدم عملية إعادة تحميل.
  • ‫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 المحتوى القابل للتمرير.

النتيجة

يوضّح هذا الفيديو عملية تنفيذ ميزة "السحب للأسفل لإعادة التحميل" الأساسية من الرمز البرمجي السابق:

الشكل 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) })
            }
        }
    }
}

نقاط رئيسية حول الرمز

  • يتم تخصيص لون المؤشر من خلال السمتَين containerColor وcolor في المَعلمة indicator.
  • تتحكّم السمة rememberPullToRefreshState() في حالة إجراء إعادة التحميل. يمكنك استخدام هذه الحالة مع المَعلمة indicator.

النتيجة

يعرض هذا الفيديو عملية تنفيذ السحب للأسفل لإعادة التحميل باستخدام مؤشر ملوّن:

الشكل 2. تنفيذ ميزة "السحب للأسفل لإعادة التحميل" بنمط مخصّص

مثال متقدّم: إنشاء مؤشر مخصّص بالكامل

يمكنك إنشاء مؤشرات مخصّصة معقّدة من خلال الاستفادة من الدوال المركّبة والصور المتحركة الحالية.يوضّح هذا المقتطف كيفية إنشاء مؤشر مخصّص بالكامل في عملية تنفيذ ميزة "السحب للأسفل لإعادة التحميل":

@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 المقياس والشفافية.

النتيجة

يعرض هذا الفيديو المؤشر المخصّص من الرمز السابق:

الشكل 3. مثال يوضّح تنفيذ ميزة "السحب للأسفل لإعادة التحميل" باستخدام مؤشر مخصّص.

مراجع إضافية