يتيح مكوِّن "السحب لإعادة التحميل" للمستخدمين السحب للأسفل في بداية محتوى التطبيق لإعادة تحميل البيانات.
مساحة عرض واجهة برمجة التطبيقات
استخدِم الدالة المركّبة 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المقياس والشفافية.
- تستخدم السمة
النتيجة
يعرض هذا الفيديو المؤشر المخصّص من الرمز السابق: