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

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

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

استخدِم الدالة المركّبة 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 المحتوى القابل للتمرير.

النتيجة

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

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

النتيجة

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

الشكل 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. مثال على تنفيذ ميزة "السحب لإعادة التحميل" باستخدام مؤشر مخصّص

مراجع إضافية