搜尋套件、儲存庫與 APP 分類

套件詳情v8.0.5

back_button_interceptor

返回按鈕中斷器。可用於在點擊 Android 回上一頁按鈕時執行某些動作,作為 WillPopScope 的替代方案。

AndroidiOSWebmacOSWindowsLinux
近 30 天下載
33.8萬
喜歡數
411
Pub 分數
150

安裝套件

flutter pub add back_button_interceptor

套件介紹

根據套件公開資料產生的選型評估,僅供參考。

back_button_interceptor 套件提供了一種攔截 Android 返回按鈕按壓的方法,並在應用程式導航回上一頁之前執行自訂邏輯。它作為 WillPopScope 的替代方案,為在 Flutter 應用程式中處理 Android、iOS、Web、macOS、Windows 和 Linux 上的導航提供了更多彈性。這在使用者按下返回按鈕時特別有用,例如顯示確認對話方塊、儲存資料或管理複雜的導航流程。

適用情境

  • 處理移動應用中的返回按鈕點擊
  • 導航前顯示確認對話方塊
  • 離開畫面之前儲存未儲存的資料
  • 管理多層導航流程
  • 防止意外導航
  • 自定義跨平台的返回按鈕行為

主要特色

  • 跨平台支援(Android、iOS、Web、macOS、Windows、Linux)
  • 用於攔截返回按鈕事件的簡單 API
  • WillPopScope 的替代方案,具有更好的控制能力
  • 支援巢狀路由攔截
  • 允許取消返回導航
  • 與 Navigator 無縫配合

適合對象

  • 需要對返回按鈕行為進行細粒度控制的開發者
  • 應用在導航前需要確認
  • 多螢幕表單或精靈
  • 跨平台 Flutter 應用程式
  • 避免 WillPopScope 限制的團隊

使用建議

  • 可能需要額外的狀態管理
  • 如果簡單導航已足夠,則不需要
  • 深度嵌套導航可能造成的複雜性
  • 需要小心處理,以避免意外阻塞導航
  • 僅限平台特定的返回按鈕事件(非所有裝置上的硬體返回按鈕)

原始 README

以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。

Pub popularity Pub Version GitHub stars Code Climate issues GitHub closed issues GitHub contributors GitHub repo size GitHub forks PRs Welcome Developed by Marcelo Glasberg Glasberg.dev on pub.dev Platforms

back_button_interceptor

In simple cases, when you need to intercept the Android back-button, you usually add WillPopScope to your widget tree. However, when developing stateful widgets that interact with the back button, it's more convenient to use the BackButtonInterceptor.

You may add interceptor functions to be called when the back button is tapped. These functions may perform some useful work, and then, if any of them return true, the default button process (usually popping a Route) will not be fired.

Android 13

To make it work on Android 13 and up, set this to false in the Android manifest:

android:enableOnBackInvokedCallback="false"

In more detail

All added functions are called, in order. If any function returns true, the combined result is true, and the default button process will NOT be fired. Only if all functions return false (or null), the combined result is false, and the default button process will be fired.

Optionally, you may provide a z-index. Functions with a valid z-index will be called before functions with a null z-index, and functions with larger z-index will be called first. When they have the same z-index, functions added last are called first.

Each function gets the boolean stopDefaultButtonEvent that indicates the current combined result from all the previous functions. So, if some function doesn't want to fire if some other previous function already fired, it can do:

if (stopDefaultButtonEvent) return false;

The same result may be obtained if the optional ifNotYetIntercepted parameter is true. Then the function will only be called if all previous functions returned false (that is, if stopDefaultButtonEvent is false).

Notes
  • After you've finished you MUST remove each function by calling the remove() method. Alternatively, you may also provide a name when adding a function, and then later remove it by calling the removeByName(name) method.

  • If any of your interceptors throw an error, the error message will be printed to the console, but the error thrown will be a general error with not much information. You can change the treatment of errors by changing the static errorProcessing field.

  • Your functions can also process information about routes by using the function's RouteInfo info parameter. To get the current route in the navigator, call info.currentRoute(context). Also, info.routeWhenAdded contains the route that was the current one when the interceptor was added through the BackButtonInterceptor.add() method.

  • You can set up some function so that it only runs when the current route is the same route of when the interceptor was created. To that end, you can use info.ifRouteChanged() method:

    bool myInterceptor(bool stopDefaultButtonEvent, RouteInfo info) {    
      if (info.ifRouteChanged(context)) return false;
      ...
    }    
    

    This means the interceptor function is temporarily disabled while, for example, a dialog is open.

  • You can set up some function so that it only runs in certain routes:

    bool myInterceptor(bool stopDefaultButtonEvent, RouteInfo info) {    
      if (["myRoute1", "myRoute2", "myRoute3"]
         .contains(info.currentRoute(context))) return false;
      ...
    }    
    
  • Both info.routeWhenAdded and info.ifRouteChanged() only work if you passed the context parameter to the BackButtonInterceptor.add() method. Otherwise, info.routeWhenAdded will be null and info.ifRouteChanged() will thrown an error.

  • The current route can also be obtained by using the static method BackButtonInterceptor.getCurrentNavigatorRouteName(context).

  • The interceptor function can return bool or Future<bool>.


Examples

Intercepting
@override
void initState() {
   super.initState();
   BackButtonInterceptor.add(myInterceptor);
}

@override
void dispose() {
   BackButtonInterceptor.remove(myInterceptor);
   super.dispose();
}

bool myInterceptor(bool stopDefaultButtonEvent, RouteInfo info) {
   print("BACK BUTTON!"); // Do some stuff.
   return true;
}
Named function and z-index
@override
void initState() {
   super.initState();
   BackButtonInterceptor.add(myInterceptor, zIndex:2, name:"SomeName");
}

@override
void dispose() {
   BackButtonInterceptor.removeByName("SomeName");
   super.dispose();
}

bool myInterceptor(bool stopDefaultButtonEvent, RouteInfo info) {
   print("BACK BUTTON!"); // Do some stuff.
   return true;
}
Runnable Examples
  1. main

    Intercepts the back-button and prints a string to the console.

  2. main

    Intercepts the back-button and prints a string to the console, by using an async interceptor function.

  3. main_complex_example

    The first screen has a button which opens a second screen. The second screen has 3 red squares. By tapping the Android back-button (or the "pop" button) each square turns blue, one by one. Only when all squares are blue, tapping the back-button once more will return to the previous screen. Also, if you click the "Open Dialog" button, the interceptors are disabled while the dialog is open.

  4. main_complex_example_test

    This package is test friendly, and this examples shows how to test the back button.

Testing

For testing purposes, the BackButtonInterceptor.popRoute() method may be called directly, to simulate pressing the back button. The list of all fired functions and their results is
recorded in the BackButtonInterceptor.results static variable.

Note: You may want to add BackButtonInterceptor.removeAll(); to your test's setUp function, so that you remove old interceptors between tests.

Debugging

In complex cases, to make it easier for you to debug your interceptors, you may print them to the console, with their names and z-indexes, by doing:

print(BackButtonInterceptor.describe());

Incompatibilities

This package is currently incompatible with deep links of the GoRouter package.

See also:

  • https://docs.flutter.io/flutter/widgets/WillPopScope-class.html
  • https://stackoverflow.com/questions/45916658/de-activate-system-back-button-in-flutter-app-toddler-navigation

By Marcelo Glasberg

glasberg.dev
github.com/marcglasberg
linkedin.com/in/marcglasberg/
twitter.com/glasbergmarcelo
stackoverflow.com/users/3411681/marcg
medium.com/@marcglasberg

My article in the official Flutter documentation:

The Flutter packages I've authored:

My Medium Articles:

所屬分類

依賴

依賴清單 1 項

原始碼儲存庫

使用此套件的專案