Actions API 修訂

在 Flutter 中，Intent 是一個物件，通常會透過 Shortcuts 元件 (Widget) 綁定至某個鍵盤組合鍵。 Intent 可以綁定至 Action， 用於更新應用程式狀態或執行其他操作。 在使用此 API 的過程中，我們發現設計上有幾個缺點，因此我們對 Actions API 進行了更新，使其更易於使用與理解。

在先前的 Actions API 設計中，actions 是從 LocalKey 對應到 ActionFactory，每次呼叫 invoke 方法時都會建立一個新的 Action。 在目前的 API 中，actions 是從 Intent 的類型對應到 Action 實例（帶有 Map<Type, Action>）， 且每次呼叫時不會重新建立實例。

原本的 Actions API 設計是為了讓 actions 能從元件 (Widget) 中被呼叫，並在該元件的上下文中執行。 團隊在實際使用 actions 時，發現該設計有幾項限制需要改進：

1. 無法從元件 (Widget) 階層外部呼叫 actions。 例如：處理指令腳本、某些 undo 架構，以及部分 controller 架構。

2. 從快捷鍵到 Intent 再到 Action 的對應關係並不總是很清楚，因為資料結構是將 LogicalKeySet => Intent，再由 LocalKey => ActionFactory。新的對應方式仍然是 LogicalKeySet 對應 Intent，但接著會將 Type （Intent 類型）對應到 Action， 這樣的設計更直接且易讀，因為 intent 的類型會直接寫在對應表中。

3. 如果某個 action 的鍵盤綁定在元件階層的其他地方，Intent 不一定能取得決定 intent/action 是否啟用所需的狀態。

為了解決這些問題，我們對 API 進行了重大調整。 actions 的對應方式變得更直觀， 而啟用（enabled）介面則移至 Action 類別。 另外，Action 的 invoke 方法與建構函式中也移除了不必要的參數，並允許 actions 的 invoke 方法回傳結果。 actions 現在改為泛型（generics），可指定所處理的 Intent 類型，且不再使用 LocalKeys 來識別要執行哪個 action，而是改用 Intent 的類型。

這些主要變更大多來自 Revise Action API 及 Make Action.enabled be isEnabled(Intent intent) instead 這兩個 PR，詳細內容可參考設計文件。

以下是針對上述問題所做的調整：

1. 提供給 Actions 元件 (Widget) 的 Map<LocalKey, ActionFactory>，現在是一個 Map<Type, Action<Intent>>（其類型為要傳遞給 Action 的 Intent 類型）。
2. isEnabled 方法已從 Intent 類別移至 Action 類別。
3. Action.invoke 與 Actions.invoke 方法中的 FocusNode 參數已被移除。
4. 呼叫 action 時不再會建立新的 Action 實例。
5. Intent 建構函式中的 LocalKey 參數已被移除。
6. CallbackAction 的 LocalKey 參數已被移除。
7. Action 類別現在為泛型（Action<T extends Intent>），以提升型別安全性。
8. CallbackAction 所使用的 OnInvokeCallback 不再需要 FocusNode 參數。
9. ActionDispatcher.invokeAction 的簽章已變更，不再接受可選的 FocusNode，而是改為可選的 BuildContext。
10. Action 子類別中的 LocalKey 靜態常數（依慣例命名為 key）已被移除。
11. Action.invoke 與 ActionDispatcher.invokeAction 方法現在會以 Object 形式回傳 action 執行的結果。
12. Action 類別現在可以監聽狀態變化。
13. ActionFactory typedef 已被移除，因為已不再使用。

以下是一些可能因為 Actions API 使用過時而導致的分析器（analyzer）錯誤範例。實際錯誤內容可能有所不同，且這些變更也可能導致其他錯誤。

error: MyActionDispatcher.invokeAction' ('bool Function(Action<Intent>, Intent, {FocusNode focusNode})') isn't a valid override of 'ActionDispatcher.invokeAction' ('Object Function(Action<Intent>, Intent, [BuildContext])'). (invalid_override at [main] lib/main.dart:74)

error: MyAction.invoke' ('void Function(FocusNode, Intent)') isn't a valid override of 'Action.invoke' ('Object Function(Intent)'). (invalid_override at [main] lib/main.dart:231)

error: The method 'isEnabled' isn't defined for the type 'Intent'. (undefined_method at [main] lib/main.dart:97)

error: The argument type 'Null Function(FocusNode, Intent)' can't be assigned to the parameter type 'Object Function(Intent)'. (argument_type_not_assignable at [main] lib/main.dart:176)

error: The getter 'key' isn't defined for the type 'NextFocusAction'. (undefined_getter at [main] lib/main.dart:294)

error: The argument type 'Map<LocalKey, dynamic>' can't be assigned to the parameter type 'Map<Type, Action<Intent>>'. (argument_type_not_assignable at [main] lib/main.dart:418)

要將現有程式碼更新至新版 API，需進行重大變更。

若要在 Actions 元件 (Widget) 中，針對 Flutter 的預設動作（例如 ActivateAction 和 SelectAction）更新 action 對應，請依下列步驟操作：

• 更新 actions 參數的參數型別
• 在 Shortcuts 對應中，使用特定 Intent 類別的實例，而非 Intent(TheAction.key) 實例。

遷移前的程式碼：

class MyWidget extends StatelessWidget {
  // ...
  @override
  Widget build(BuildContext context) {
    return Shortcuts(
      shortcuts: <LogicalKeySet, Intent> {
        LogicalKeySet(LogicalKeyboardKey.enter): Intent(ActivateAction.key),
      },
      child: Actions(
        actions: <LocalKey, ActionFactory>{
          Activate.key: () => ActivateAction(),
        },
        child: Container(),
      )
    );
  }
}

遷移後的程式碼：

class MyWidget extends StatelessWidget {
  // ...
  @override
  Widget build(BuildContext context) {
    return Shortcuts(
      shortcuts: <LogicalKeySet, Intent> {
        LogicalKeySet(LogicalKeyboardKey.enter): ActivateIntent,
      },
      child: Actions(
        actions: <Type, Action<Intent>>{
          ActivateIntent: ActivateAction(),
        },
        child: Container(),
      )
    );
  }
}

若要遷移您的自訂 actions，請移除您所定義的 LocalKeys，並以 Intent 子類別取代，同時也要將 Actions 元件的 actions 參數型別進行相應更改。

遷移前的程式碼：

class MyAction extends Action {
  MyAction() : super(key);
​
  /// The [LocalKey] that uniquely identifies this action to an [Intent].
  static const LocalKey key = ValueKey<Type>(RequestFocusAction);
​
  @override
  void invoke(FocusNode node, MyIntent intent) {
    // ...
  }
}
​
class MyWidget extends StatelessWidget {
  // ...
  @override
  Widget build(BuildContext context) {
    return Shortcuts(
      shortcuts: <LogicalKeySet, Intent> {
        LogicalKeySet(LogicalKeyboardKey.enter): Intent(MyAction.key),
      },
      child: Actions(
        actions: <LocalKey, ActionFactory>{
          MyAction.key: () => MyAction(),
        },
        child: Container(),
      )
    );
  }
}

遷移後的程式碼：

// You may need to create new Intent subclasses if you used
// a bare LocalKey before.
class MyIntent extends Intent {
  const MyIntent();
}
​
class MyAction extends Action<MyIntent> {
  @override
  Object invoke(MyIntent intent) {
    // ...
  }
}
​
class MyWidget extends StatelessWidget {
  // ...
  @override
  Widget build(BuildContext context) {
    return Shortcuts(
      shortcuts: <LogicalKeySet, Intent> {
        LogicalKeySet(LogicalKeyboardKey.enter): MyIntent,
      },
      child: Actions(
        actions: <Type, Action<Intent>>{
          MyIntent: MyAction(),
        },
        child: Container(),
      )
    );
  }
}

若要更新使用 intent 參數或保存狀態的 action， 你需要修改傳遞給 invoke 方法的參數。 在下方的範例中，程式碼會將參數的值保存在 intent 中，作為 action 實例的一部分。 這是因為在舊的設計中，每次執行時都會建立新的 action 實例， 而產生的 action 可能會被 ActionDispatcher 保留，以記錄狀態。

在下方遷移後的程式碼範例中， 新的 MyAction 會在呼叫 invoke 時，將狀態作為結果回傳， 因為現在每次呼叫不會再建立新的實例。 這個狀態會回傳給 Actions.invoke 或 ActionDispatcher.invokeAction 的呼叫者， 具體取決於 action 的呼叫方式。

遷移前的程式碼：

class MyIntent extends Intent {
  const MyIntent({this.argument});
​
  final int argument;
}
​
class MyAction extends Action {
  MyAction() : super(key);
​
  /// The [LocalKey] that uniquely identifies this action to an [Intent].
  static const LocalKey key = ValueKey<Type>(RequestFocusAction);
​
  int state;
​
  @override
  void invoke(FocusNode node, MyIntent intent) {
    // ...
    state = intent.argument;
  }
}

遷移後的程式碼：

class MyIntent extends Intent {
  const MyIntent({this.argument});
​
  final int argument;
}
​
class MyAction extends Action<MyIntent> {
  @override
  int invoke(Intent intent) {
    // ...
    return intent.argument;
  }
}

合併於版本：1.18
正式版釋出：1.20

API 文件：

• Action
• ActionDispatcher
• Actions
• Intent
• Shortcuts

相關議題：

• Issue 53276

相關 PR：

• Revise Action API
• Make Action.enabled be isEnabled(Intent intent) instead