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

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

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

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

النتيجة

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

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

مراجع إضافية