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