با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
مولفه کشش برای تازه کردن به کاربران این امکان را می دهد که در ابتدای محتوای برنامه به سمت پایین بکشند تا داده ها را تازه کنند.
سطح API
از PullToRefreshBox composable برای اجرای pull-to-refresh استفاده کنید که به عنوان محفظه ای برای محتوای قابل پیمایش شما عمل می کند. پارامترهای کلیدی زیر رفتار و ظاهر تازه سازی را کنترل می کنند:
isRefreshing : یک مقدار بولی که نشان می دهد آیا عمل به روز رسانی در حال انجام است یا خیر.
onRefresh : یک تابع لامبدا که زمانی اجرا می شود که کاربر یک رفرش را شروع می کند.
indicator : نشانگری را که سیستم بر روی کشش برای تازه کردن می کشد سفارشی می کند.
مثال اساسی
این قطعه کاربرد اصلی PullToRefreshBox را نشان می دهد:
رنگ نشانگر از طریق ویژگی containerColor و color در پارامتر indicator سفارشی می شود.
rememberPullToRefreshState() وضعیت اکشن تازه سازی را مدیریت می کند. شما از این حالت در ارتباط با پارامتر indicator استفاده می کنید.
نتیجه
این ویدئو اجرای pull-to-refresh را با نشانگر رنگی نشان می دهد:
شکل 2 . اجرای کشش به تازه کردن با سبک سفارشی.
مثال پیشرفته: یک نشانگر کاملا سفارشی ایجاد کنید
میتوانید با استفاده از قابلیتهای ترکیبسازی و انیمیشنهای موجود، شاخصهای سفارشی پیچیده ایجاد کنید. این قطعه نشان میدهد که چگونه میتوانید یک نشانگر کاملاً سفارشی در پیادهسازی pull-to-fresh ایجاد کنید:
قطعه قبلی از 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 . اجرای کشش برای تازه کردن با یک نشانگر سفارشی.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-08-28 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","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-28 بهوقت ساعت هماهنگ جهانی."],[],[],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/7a0ebbee11495f628cf9d574f6b6069c2867232a/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/7a0ebbee11495f628cf9d574f6b6069c2867232a/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/7a0ebbee11495f628cf9d574f6b6069c2867232a/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)"]]