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

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

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

استخدِم العنصر القابل للإنشاء 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.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
                        }
                )
            }
        }
    }
}

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

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

مراجع إضافية