在應用程式中加入滑動重新整理功能
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
試試 Compose 的方式
Jetpack Compose 是 Android 推薦的 UI 工具包。瞭解如何在 Compose 中使用下拉刷新功能。
滑動以重新整理使用者介面模式完全實作於 SwipeRefreshLayout
小工具中,可偵測垂直滑動動作、顯示獨特的進度列,並在應用程式中觸發回呼方法。如要啟用這項行為,請將小工具新增至版面配置檔案,做為 ListView
或 GridView
的父項,並實作使用者滑動時會叫用的重新整理行為。
本頁說明如何將小工具新增至現有版面配置。本節也說明如何在動作列溢位區新增重新整理動作,讓無法使用滑動手勢的使用者可以透過外部裝置觸發手動更新。
新增 SwipeRefreshLayout 依附元件
如要在應用程式中使用 SwipeRefreshLayout
,請在 build.gradle
檔案中新增下列依附元件:
Groovy
dependencies {
implementation "androidx.swiperefreshlayout:swiperefreshlayout:1.2.0-alpha01"
}
Kotlin
dependencies {
implementation("androidx.swiperefreshlayout:swiperefreshlayout:1.2.0-alpha01")
}
如要在現有應用程式中新增滑動重新整理小工具,請將 SwipeRefreshLayout
新增為單一 ListView
或 GridView
的父項。SwipeRefreshLayout
僅支援單一 ListView
或 GridView
子項。
以下範例說明如何將 SwipeRefreshLayout
小工具新增至包含 ListView
的現有版面配置檔案:
<androidx.swiperefreshlayout.widget.SwipeRefreshLayout
xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/swiperefresh"
android:layout_width="match_parent"
android:layout_height="match_parent">
<ListView
android:id="@android:id/list"
android:layout_width="match_parent"
android:layout_height="match_parent" />
</androidx.swiperefreshlayout.widget.SwipeRefreshLayout>
您也可以將 SwipeRefreshLayout
小工具與 ListFragment
搭配使用。如果版面配置包含 ID 為 "@android:id/list"
的 ListView
,系統會自動支援滑動重新整理功能。不過,以這種方式明確宣告 ListView
會取代預設的 ListFragment
檢視畫面結構。如果您想使用預設的檢視畫面結構,請覆寫 SwipeRefreshLayout
和 ListFragment
行為的部分。
在動作列中新增重新整理動作
請在應用程式的動作列中新增重新整理動作,讓無法執行滑動手勢的使用者能夠觸發手動更新。舉例來說,有無障礙需求的使用者可以使用外部裝置 (例如鍵盤和方向鍵) 觸發動作列動作。
設定屬性 android:showAsAction=never
,將重新整理動作新增為選單項目,而非按鈕。如果您以按鈕顯示動作,使用者可能會認為重新整理按鈕動作與滑動重新整理動作不同。讓重新整理動作在動作列中不那麼顯眼,可鼓勵使用者透過滑動手勢手動更新,同時保留可供方向鍵使用者查看的選項。
以下程式碼示範如何在溢位區域中新增滑動重新整理動作:
<menu xmlns:android="http://schemas.android.com/apk/res/android" >
<item
android:id="@+id/menu_refresh"
android:showAsAction="never"
android:title="@string/menu_refresh"/>
</menu>
這個頁面中的內容和程式碼範例均受《內容授權》中的授權所規範。Java 與 OpenJDK 是 Oracle 和/或其關係企業的商標或註冊商標。
上次更新時間:2025-07-26 (世界標準時間)。
[[["容易理解","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-07-26 (世界標準時間)。"],[],[],null,["# Add swipe-to-refresh to your app\n\nTry the Compose way \nJetpack Compose is the recommended UI toolkit for Android. Learn how to pull to refresh in Compose. \n[Pull to refresh in Compose →](/develop/ui/compose/components/pull-to-refresh) \n\nThe swipe-to-refresh user interface pattern is implemented entirely within the\n[SwipeRefreshLayout](/reference/androidx/swiperefreshlayout/widget/SwipeRefreshLayout)\nwidget, which detects the vertical swipe, displays a distinctive progress bar, and triggers callback\nmethods in your app. Enable this behavior by adding the widget to your layout file as the parent of\na [ListView](/reference/android/widget/ListView) or\n[GridView](/reference/android/widget/GridView) and implementing the\nrefresh behavior that is invoked when the user swipes.\n\nThis page shows how to add the widget to an existing layout. It also shows how to add a refresh\naction to the action bar overflow area so that users who can't use the swipe gesture can trigger a\nmanual update with an external device.\n\nAdd SwipeRefreshLayout dependency\n---------------------------------\n\nTo use `SwipeRefreshLayout` in your app, add the following dependency to your\n`build.gradle` file: \n\n### Groovy\n\n```groovy\ndependencies {\n implementation \"androidx.swiperefreshlayout:swiperefreshlayout:1.2.0-alpha01\"\n}\n```\n\n### Kotlin\n\n```kotlin\ndependencies {\n implementation(\"androidx.swiperefreshlayout:swiperefreshlayout:1.2.0-alpha01\")\n}\n```\n\nAdd the SwipeRefreshLayout Widget\n---------------------------------\n\nTo add the swipe-to-refresh widget to an existing app, add `SwipeRefreshLayout` as the\nparent of a single `ListView` or `GridView`.\n`SwipeRefreshLayout` only supports a single `ListView` or\n`GridView` child.\n\nThe following example demonstrates how to add the `SwipeRefreshLayout` widget to an\nexisting layout file containing a `ListView`: \n\n```xml\n\u003candroidx.swiperefreshlayout.widget.SwipeRefreshLayout\n xmlns:android=\"http://schemas.android.com/apk/res/android\"\n android:id=\"@+id/swiperefresh\"\n android:layout_width=\"match_parent\"\n android:layout_height=\"match_parent\"\u003e\n\n \u003cListView\n android:id=\"@android:id/list\"\n android:layout_width=\"match_parent\"\n android:layout_height=\"match_parent\" /\u003e\n\n\u003c/androidx.swiperefreshlayout.widget.SwipeRefreshLayout\u003e\n```\n\nYou can also use the `SwipeRefreshLayout` widget with a\n[ListFragment](/reference/androidx/fragment/app/ListFragment). If the\nlayout contains a `ListView` with the ID `\"@android:id/list\"`, the\nswipe-to-refresh functionality is automatically supported. However, explicitly declaring the\n`ListView` this way supersedes the default `ListFragment` view structure. If\nyou want to use the default view structure, override parts of the `SwipeRefreshLayout`\nand `ListFragment` behavior.\n\nAdd a refresh action to the action bar\n--------------------------------------\n\nAdd a refresh action to your app's action bar so users who can't perform swipe gestures can\ntrigger a manual update. For example, users with accessibility needs can trigger action bar actions\nusing external devices, such as keyboards and D-pads.\n\nAdd the refresh action as a menu item, rather than as a button, by setting the attribute\n`android:showAsAction=never`. If you display the action as a button, users might assume\nthe refresh button action is different from the swipe-to-refresh action. Making the refresh action\nless conspicuous in the action bar encourages users to perform manual updates with swipe gestures\nwhile maintaining the accessible option where D-pad users look for it.\n\nThe following code demonstrates how to add the swipe-to-refresh action to the overflow area: \n\n```xml\n\u003cmenu xmlns:android=\"http://schemas.android.com/apk/res/android\" \u003e\n \u003citem\n android:id=\"@+id/menu_refresh\"\n android:showAsAction=\"never\"\n android:title=\"@string/menu_refresh\"/\u003e\n\u003c/menu\u003e\n```"]]