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