קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
רכיב המשיכה לרענון מאפשר למשתמשים לגרור כלפי מטה בתחילת התוכן של האפליקציה כדי לרענן את הנתונים.
משטח API
אפשר להשתמש ב-PullToRefreshBox composable כדי להטמיע משיכה לרענון, שפועל כקונטיינר לתוכן שאפשר לגלול בו. הפרמטרים העיקריים הבאים קובעים את התנהגות הרענון והמראה:
isRefreshing: ערך בוליאני שמציין אם פעולת הרענון מתבצעת.
onRefresh: פונקציית lambda שמופעלת כשהמשתמש יוזם רענון.
indicator: התאמה אישית של האינדיקטור שהמערכת מציירת בפעולת משיכה לרענון.
דוגמה בסיסית
קטע הקוד הזה מדגים שימוש בסיסי ב-PullToRefreshBox:
בסרטון הזה מוצגת הטמעה של משיכה לרענון עם אינדיקטור צבעוני:
איור 2. הטמעה של משיכה לרענון עם סגנון מותאם אישית.
דוגמה מתקדמת: יצירת אינדיקטור בהתאמה אישית מלאה
אתם יכולים ליצור אינדיקטורים מורכבים בהתאמה אישית באמצעות רכיבים קיימים ושיטות אנימציה.בקטע הקוד הבא מוצג איך ליצור אינדיקטור בהתאמה אישית מלאה בהטמעה של משיכה לרענון:
בקטע הקוד הקודם השתמשנו ב-Indicator שסופק על ידי הספרייה. קטע הקוד הזה יוצר רכיב הניתן להרכבה של אינדיקטור בהתאמה אישית שנקרא MyCustomIndicator. ב-composable הזה, משנה ה-pullToRefreshIndicator מטפל במיקום ובהפעלת רענון.
כמו בקטע הקוד הקודם, בדוגמה הזו מופקת מכונת PullToRefreshState, כך שאפשר להעביר את אותה מכונה גם ל-PullToRefreshBox וגם ל-pullToRefreshModifier.
בדוגמה נעשה שימוש בצבע של הקונטיינר ובסף המיקום מהמחלקה PullToRefreshDefaults. כך תוכלו לעשות שימוש חוזר בהתנהגות ובסגנון שמוגדרים כברירת מחדל בספריית Material, ועדיין להתאים אישית רק את הרכיבים שמעניינים אתכם.
MyCustomIndicator משתמש ב-Crossfade כדי לעבור בין סמל של ענן
לבין CircularProgressIndicator. סמל הענן גדל כשהמשתמש מושך את המסך, ועובר לCircularProgressIndicator כשהפעולה של הרענון מתחילה.
targetState משתמש ב-isRefreshing כדי לקבוע איזה סטטוס להציג (סמל הענן או אינדיקטור ההתקדמות המעגלי).
animationSpec מגדיר אנימציה של tween למעבר, עם משך מוגדר של CROSSFADE_DURATION_MILLIS.
state.distanceFraction מייצג את המרחק שהמשתמש משך כלפי מטה, בטווח שבין 0f (לא משך) לבין 1f (משך עד הסוף).
המשנה graphicsLayer משנה את קנה המידה ואת השקיפות.
התוצאה
בסרטון הזה מוצג האינדיקטור המותאם אישית מהקוד שלמעלה:
איור 3. הטמעה של משיכה לרענון עם אינדיקטור בהתאמה אישית.
דוגמאות התוכן והקוד שבדף הזה כפופות לרישיונות המפורטים בקטע רישיון לתוכן. Java ו-OpenJDK הם סימנים מסחריים או סימנים מסחריים רשומים של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-08-23 (שעון UTC).
[[["התוכן קל להבנה","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-08-23 (שעון UTC)."],[],[],null,["# Pull to refresh\n\nThe 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-----------\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-------------\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/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/PullToRefreshBox.kt#L92-L110\n```\n\n\u003cbr /\u003e\n\n### Key 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\n### Result\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\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/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/PullToRefreshBox.kt#L115-L145\n```\n\n\u003cbr /\u003e\n\n### Key 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\n### Result\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-----------------------------------------------------\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/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/PullToRefreshBox.kt#L150-L222\n```\n\n\u003cbr /\u003e\n\n### Key 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\n### Result\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\n- [`PullToRefreshState`](/reference/kotlin/androidx/compose/material3/pulltorefresh/PullToRefreshState)"]]