يتيح عنصر "السحب لإعادة التحميل" للمستخدمين السحب للأسفل في بداية محتوى التطبيق لإعادة تحميل البيانات.
مساحة واجهة برمجة التطبيقات
استخدِم العنصر القابل للإنشاء 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المحتوى القابل للتمرير.
النتيجة
يوضّح هذا الفيديو عملية التنفيذ الأساسية لميزة "السحب لإعادة التحميل" من الرمز البرمجي السابق:
مثال متقدّم: تخصيص لون المؤشر
@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( 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، مع تخصيص العناصر التي تهمّك فقط. - يستخدم
MyCustomIndicatorCrossfadeللانتقال بين رمز سحابة وCircularProgressIndicator. يزداد حجم رمز السحابة الإلكترونية عندما يسحب المستخدم الشاشة، ثم يتحوّل إلىCircularProgressIndicatorعند بدء إجراء إعادة التحميل.- تستخدم السمة
targetStateالسمةisRefreshingلتحديد الحالة التي سيتم عرضها (رمز السحابة أو مؤشر التقدم الدائري). - يحدّد
animationSpecحركةtweenللانتقال، مع مدة محددة تبلغCROSSFADE_DURATION_MILLIS. - يمثّل
state.distanceFractionمقدار السحب الذي أجراه المستخدم للأسفل، ويتراوح بين0f(لم يتم السحب) و1f(تم السحب بالكامل). - يعدّل المعدِّل
graphicsLayerالمقياس والشفافية.
- تستخدم السمة
النتيجة
يعرض هذا الفيديو المؤشر المخصّص من الرمز السابق: