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