تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يتيح عنصر "السحب لإعادة التحميل" للمستخدمين السحب للأسفل في بداية محتوى التطبيق لإعادة تحميل البيانات.
مساحة واجهة برمجة التطبيقات
استخدِم العنصر القابل للإنشاء PullToRefreshBox لتنفيذ ميزة "السحب لإعادة التحميل" التي تعمل كحاوية للمحتوى القابل للتمرير. تتحكّم المَعلمات الرئيسية التالية في سلوك إعادة التحميل ومظهره:
isRefreshing: قيمة منطقية تشير إلى ما إذا كان إجراء إعادة التحميل قيد التنفيذ.
onRefresh: دالة lambda يتم تنفيذها عندما يبدأ المستخدم عملية إعادة تحميل.
indicator: تخصّص هذه السمة المؤشر الذي يرسمه النظام عند السحب لأسفل لإعادة التحميل.
مثال أساسي
يوضّح المقتطف التالي الاستخدام الأساسي لـ PullToRefreshBox:
يعرض هذا الفيديو عملية تنفيذ ميزة "السحب لإعادة التحميل" باستخدام مؤشر ملوّن:
الشكل 2. عملية تنفيذ ميزة "السحب لإعادة التحميل" بنمط مخصّص
مثال متقدّم: إنشاء مؤشر مخصّص بالكامل
يمكنك إنشاء مؤشرات مخصّصة معقّدة من خلال الاستفادة من العناصر القابلة للإنشاء والرسوم المتحركة الحالية.توضّح هذه المقتطف كيفية إنشاء مؤشر مخصّص بالكامل في عملية تنفيذ ميزة "السحب لإعادة التحميل":
استخدم المقتطف السابق Indicator الذي توفّره المكتبة. ينشئ هذا المقتطف عنصرًا قابلاً للإنشاء لمؤشر مخصّص باسم MyCustomIndicator. في هذا العنصر القابل للإنشاء، يتعامل المعدِّل pullToRefreshIndicator مع تحديد الموضع وتفعيل عملية إعادة التحميل.
كما هو الحال في المقتطف السابق، يستخرج المثال PullToRefreshState
النسخة، وبالتالي يمكنك تمرير النسخة نفسها إلى كل من PullToRefreshBox
وpullToRefreshModifier.
يستخدم المثال لون الحاوية وحد الموضع من الفئة PullToRefreshDefaults. بهذه الطريقة، يمكنك إعادة استخدام السلوك والنمط التلقائيين من مكتبة Material، مع تخصيص العناصر التي تهمّك فقط.
يستخدم MyCustomIndicatorCrossfade للانتقال بين رمز سحابة
وCircularProgressIndicator. يزداد حجم رمز السحابة الإلكترونية عندما يسحب المستخدم الشاشة، ثم يتحوّل إلى CircularProgressIndicator عند بدء إجراء إعادة التحميل.
تستخدم السمة targetState السمة isRefreshing لتحديد الحالة التي سيتم عرضها (رمز السحابة أو مؤشر التقدم الدائري).
يحدّد animationSpec حركة tween للانتقال، مع مدة محددة تبلغ CROSSFADE_DURATION_MILLIS.
يمثّل state.distanceFraction مقدار السحب الذي أجراه المستخدم،
ويتراوح بين 0f (لم يتم السحب) و1f (تم السحب بالكامل).
يعدّل المعدِّل graphicsLayer المقياس والشفافية.
النتيجة
يعرض هذا الفيديو المؤشر المخصّص من الرمز السابق:
الشكل 3. تنفيذ ميزة السحب لإعادة التحميل باستخدام مؤشر مخصّص
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-09-03 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-09-03 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["The pull to refresh component allows users to drag downwards at the beginning of\nan app's content to refresh the data.\n| **Note:** [`PullToRefreshBox()`](/reference/kotlin/androidx/compose/material3/pulltorefresh/package-summary#PullToRefreshBox(kotlin.Boolean,kotlin.Function0,androidx.compose.ui.Modifier,androidx.compose.material3.pulltorefresh.PullToRefreshState,androidx.compose.ui.Alignment,kotlin.Function1,kotlin.Function1)) is experimental.\n\nAPI surface\n\nUse the [`PullToRefreshBox`](/reference/kotlin/androidx/compose/material3/pulltorefresh/package-summary#PullToRefreshBox(kotlin.Boolean,kotlin.Function0,androidx.compose.ui.Modifier,androidx.compose.material3.pulltorefresh.PullToRefreshState,androidx.compose.ui.Alignment,kotlin.Function1,kotlin.Function1)) composable to implement pull-to-refresh, which\nacts as a container for your scrollable content. The following key parameters\ncontrol the refresh behavior and appearance:\n\n- `isRefreshing`: A boolean value indicating whether the refresh action is in progress.\n- `onRefresh`: A lambda function that executes when the user initiates a refresh.\n- `indicator`: Customizes the indicator that the system draws on pull-to-refresh.\n\nBasic example\n\nThis snippet demonstrates basic usage of `PullToRefreshBox`:\n\n\n```kotlin\n@Composable\nfun PullToRefreshBasicSample(\n items: List\u003cString\u003e,\n isRefreshing: Boolean,\n onRefresh: () -\u003e Unit,\n modifier: Modifier = Modifier\n) {\n PullToRefreshBox(\n isRefreshing = isRefreshing,\n onRefresh = onRefresh,\n modifier = modifier\n ) {\n LazyColumn(Modifier.fillMaxSize()) {\n items(items) {\n ListItem({ Text(text = it) })\n }\n }\n }\n}https://github.com/android/snippets/blob/e4396f6dd13aaa8099c4baa671cdd549a10f201c/compose/snippets/src/main/java/com/example/compose/snippets/components/PullToRefreshBox.kt#L92-L110\n```\n\n\u003cbr /\u003e\n\nKey points about the code\n\n- `PullToRefreshBox` wraps a [`LazyColumn`](/reference/kotlin/androidx/compose/foundation/lazy/package-summary#LazyColumn(androidx.compose.ui.Modifier,androidx.compose.foundation.lazy.LazyListState,androidx.compose.foundation.layout.PaddingValues,kotlin.Boolean,androidx.compose.foundation.layout.Arrangement.Vertical,androidx.compose.ui.Alignment.Horizontal,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean,androidx.compose.foundation.OverscrollEffect,kotlin.Function1)), which displays a list of strings.\n- `PullToRefreshBox` requires `isRefreshing` and `onRefresh` parameters.\n- The content within the `PullToRefreshBox` block represents the scrollable content.\n\nResult\n\nThis video demonstrates the basic pull-to-refresh implementation from\nthe preceding code:\n**Figure 1**. A basic pull-to-refresh implementation on a list of items.\n\nAdvanced example: Customize indicator color\n\n\n```kotlin\n@Composable\nfun PullToRefreshCustomStyleSample(\n items: List\u003cString\u003e,\n isRefreshing: Boolean,\n onRefresh: () -\u003e Unit,\n modifier: Modifier = Modifier\n) {\n val state = rememberPullToRefreshState()\n\n PullToRefreshBox(\n isRefreshing = isRefreshing,\n onRefresh = onRefresh,\n modifier = modifier,\n state = state,\n indicator = {\n Indicator(\n modifier = Modifier.align(Alignment.TopCenter),\n isRefreshing = isRefreshing,\n containerColor = MaterialTheme.colorScheme.primaryContainer,\n color = MaterialTheme.colorScheme.onPrimaryContainer,\n state = state\n )\n },\n ) {\n LazyColumn(Modifier.fillMaxSize()) {\n items(items) {\n ListItem({ Text(text = it) })\n }\n }\n }\n}https://github.com/android/snippets/blob/e4396f6dd13aaa8099c4baa671cdd549a10f201c/compose/snippets/src/main/java/com/example/compose/snippets/components/PullToRefreshBox.kt#L115-L145\n```\n\n\u003cbr /\u003e\n\nKey points about the code\n\n- The indicator color is customized through the `containerColor` and `color` properties in the `indicator` parameter.\n- [`rememberPullToRefreshState()`](/reference/kotlin/androidx/compose/material3/pulltorefresh/PullToRefreshState) manages the state of the refresh action. You use this state in conjunction with the `indicator` parameter.\n\n| **Note:** In the basic example, `state` was not passed to `PullToRefreshBox` because it was using the default parameter value. However, in this example, you need to define the state, and pass that state to both the box and indicator to coordinate their behavior.\n\nResult\n\nThis video shows a pull-to-refresh implementation with a colored\nindicator:\n**Figure 2**. A pull-to-refresh implementation with a custom style.\n\nAdvanced example: Create a fully customized indicator\n\nYou can create complex custom indicators by leveraging existing composables and\nanimations.This snippet demonstrates how to create a fully custom indicator in\nyour pull-to-refresh implementation:\n\n\n```kotlin\n@Composable\nfun PullToRefreshCustomIndicatorSample(\n items: List\u003cString\u003e,\n isRefreshing: Boolean,\n onRefresh: () -\u003e Unit,\n modifier: Modifier = Modifier\n) {\n val state = rememberPullToRefreshState()\n\n PullToRefreshBox(\n isRefreshing = isRefreshing,\n onRefresh = onRefresh,\n modifier = modifier,\n state = state,\n indicator = {\n MyCustomIndicator(\n state = state,\n isRefreshing = isRefreshing,\n modifier = Modifier.align(Alignment.TopCenter)\n )\n }\n ) {\n LazyColumn(Modifier.fillMaxSize()) {\n items(items) {\n ListItem({ Text(text = it) })\n }\n }\n }\n}\n\n// ...\n@Composable\nfun MyCustomIndicator(\n state: PullToRefreshState,\n isRefreshing: Boolean,\n modifier: Modifier = Modifier,\n) {\n Box(\n modifier = modifier.pullToRefreshIndicator(\n state = state,\n isRefreshing = isRefreshing,\n containerColor = PullToRefreshDefaults.containerColor,\n threshold = PositionalThreshold\n ),\n contentAlignment = Alignment.Center\n ) {\n Crossfade(\n targetState = isRefreshing,\n animationSpec = tween(durationMillis = CROSSFADE_DURATION_MILLIS),\n modifier = Modifier.align(Alignment.Center)\n ) { refreshing -\u003e\n if (refreshing) {\n CircularProgressIndicator(Modifier.size(SPINNER_SIZE))\n } else {\n val distanceFraction = { state.distanceFraction.coerceIn(0f, 1f) }\n Icon(\n imageVector = Icons.Filled.CloudDownload,\n contentDescription = \"Refresh\",\n modifier = Modifier\n .size(18.dp)\n .graphicsLayer {\n val progress = distanceFraction()\n this.alpha = progress\n this.scaleX = progress\n this.scaleY = progress\n }\n )\n }\n }\n }\n}https://github.com/android/snippets/blob/e4396f6dd13aaa8099c4baa671cdd549a10f201c/compose/snippets/src/main/java/com/example/compose/snippets/components/PullToRefreshBox.kt#L150-L222\n```\n\n\u003cbr /\u003e\n\nKey points about the code\n\n- The previous snippet used the `Indicator` provided by the library. This snippet creates a custom indicator composable called `MyCustomIndicator`. In this composable, the `pullToRefreshIndicator` modifier handles positioning and triggering a refresh.\n- As in the previous snippet, the example extracts the `PullToRefreshState` instance, so you can pass the same instance to both the `PullToRefreshBox` and the `pullToRefreshModifier`.\n- The example uses the container color and the position threshold from the `PullToRefreshDefaults` class. This way, you can reuse the default behavior and styling from the Material library, while customizing only the elements you're interested in.\n- `MyCustomIndicator` uses [`Crossfade`](/reference/kotlin/androidx/compose/animation/package-summary#Crossfade(kotlin.Any,androidx.compose.ui.Modifier,androidx.compose.animation.core.FiniteAnimationSpec,kotlin.String,kotlin.Function1)) to transition between a cloud icon and a `CircularProgressIndicator`. The cloud icon scales up as the user pulls, and transitions to a `CircularProgressIndicator` when the refresh action begins.\n - `targetState` uses `isRefreshing` to determine which state to display (the cloud icon or the circular progress indicator).\n - `animationSpec` defines a `tween` animation for the transition, with a specified duration of `CROSSFADE_DURATION_MILLIS`.\n - `state.distanceFraction` represents how far the user has pulled down, ranging from `0f` (no pull) to `1f` (fully pulled).\n - The `graphicsLayer` modifier modifies scale and transparency.\n\nResult\n\nThis video shows the custom indicator from the preceding code:\n**Figure 3**. A pull-to-refresh implementation with a custom indicator.\n\nAdditional resources\n\n- [`PullToRefreshState`](/reference/kotlin/androidx/compose/material3/pulltorefresh/PullToRefreshState)"]]