Actions API 重大更改
概述
#在 Flutter 中，Intent 是一个通常使用 Shortcuts widget 绑定到键盘组合键的对象。Intent 可以绑定到 Action，该 Action 可以更新应用程序状态或执行其他操作。在使用此 API 的过程中，我们发现设计存在一些弊端，因此我们更新了 Actions API，使其更易于使用和理解。
在之前的 Actions API 设计中，操作是从 LocalKey 映射到 ActionFactory，该 ActionFactory 在每次调用 invoke 方法时都会创建一个新的 Action。在当前 API 中，操作是从 Intent 的类型映射到 Action 实例（使用 Map<Type, Action>），并且不会为每次调用都重新创建。
背景
#最初的 Actions API 设计侧重于从 widget 调用操作，并让这些操作在 widget 的上下文中执行。团队一直在使用操作，并发现该设计存在一些需要解决的限制。
操作无法从 widget 树外部调用。例如，处理命令脚本、某些撤销架构和某些控制器架构。
从快捷键到
Intent再到Action的映射并不总是清晰的，因为数据结构映射为 LogicalKeySet =>Intent，然后是LocalKey=>ActionFactory。新的映射仍然是LogicalKeySet到Intent，但现在它将Type（Intent类型）映射到Action，这更直接、更易读，因为意图的类型写在映射中。如果某个操作的键绑定位于 widget 树的另一部分，则
Intent并非总是能够访问必要的状态来决定该意图/操作是否应该启用。
为了解决这些问题，我们对 API 进行了一些重大更改。操作的映射更加直观，并且 enabled 接口已移至 Action 类。从 Action 的 invoke 方法及其构造函数中移除了不必要的参数，并允许操作从其 invoke 方法返回结果。操作已改为泛型，接受它们处理的 Intent 类型，并且不再使用 LocalKeys 来标识要运行的操作，而是使用 Intent 的类型。
这些更改大部分是在 Revise Action API 和 Make Action.enabled be isEnabled(Intent intent) instead 的 PR 中完成的，并在 设计文档 中进行了详细描述。
变更说明
#以下是为解决上述问题所做的更改：
- 传递给
Actionswidget 的Map<LocalKey, ActionFactory>现在是Map<Type, Action<Intent>>（类型是传递给 Action 的 Intent 的类型）。 isEnabled方法已从Intent类移至Action类。- 已从
Action.invoke和Actions.invoke方法中移除了FocusNode参数。 - 调用操作不再创建
Action的新实例。 - 已从
Intent构造函数中移除了LocalKey参数。 - 已从
CallbackAction中移除了LocalKey参数。 Action类现在是一个泛型（Action<T extends Intent>），以提高类型安全性。CallbackAction使用的OnInvokeCallback不再接受FocusNode参数。ActionDispatcher.invokeAction的签名已更改为不接受可选的FocusNode，而是接受可选的BuildContext。- 已移除
Action子类中（按约定命名为 key）的LocalKey静态常量。 Action.invoke和ActionDispatcher.invokeAction方法现在将调用操作的结果作为Object返回。- 现在可以监听
Action类以查看状态更改。 ActionFactory类型定义已被移除，因为它不再使用。
示例分析器故障
#以下是一些可能遇到的示例分析器故障，其中过时地使用 Actions API 可能是问题的原因。错误的具体细节可能有所不同，并且可能还存在由这些更改引起的其他故障。
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）的操作映射，请执行以下操作：
- 更新
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(),
)
);
}
}自定义操作
#要迁移自定义操作，请删除已定义的 LocalKeys，并将其替换为 Intent 子类，以及更改 Actions widget 的 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(),
)
);
}
}带有参数的自定义 Actions 和 Intents
#要更新使用意图参数或持有状态的操作，您需要修改 invoke 方法的参数。在下面的示例中，代码将意图中的参数值保留为操作实例的一部分。这是因为在旧的设计中，每次执行操作时都会创建一个新实例，并且 ActionDispatcher 可以保留结果操作以记录状态。
在下面的迁移后代码示例中，新的 MyAction 将状态作为调用 invoke 的结果返回，因为每次调用都不会创建新实例。此状态将返回给调用 Actions.invoke 或 ActionDispatcher.invokeAction 的调用者，具体取决于操作的调用方式。
迁移前的代码
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 文档
相关议题
相关 PR