Flutter 组件集录 | 3.7 新增 – ContextMenu 菜单

1. 什么是 ContextMenu 菜单

Context 菜单算是对弹出框的一个特性支持，特别对于桌面端来说，让 右键弹出东西框 的处理愈加简便。比方下方所示，是 AndroidStudio 中右键时弹出的东西：

严格来说，ContextMenu 不是一个单独的组件，而是一个弹出浮层菜单项小体系。对于移动端来说，输入框 TextFiled 组件长按文字时弹出的东西菜单也属于一种 ContextMenu ：

从本质上来说 ContextMenu 也不是什么新东西，只不过是对 Overlay 浮层的一层封装罢了。经过 ContextMenuController 控制器方便地增加和移除浮层。

这样对于任何组件，都能够方便地弹出浮层菜单进行操作：

---

2. 输入框与 ContextMenu 菜单

在 Flutter 3.7 中 TextFiled 组件增加了 contextMenuBuilder 回调构建办法。允许用户自定义 弹出的东西菜单，这样极大方便了文字挑选的可操作性。如下是官方的案例：

挑选文字中存在邮箱时，多增加一个 Send email 菜单。

能够按需构建东西菜单，让应用在操作上愈加灵敏，比方能够增加保存、共享、搜索等按钮。在桌面端中，右键能够弹出东西菜单栏：

---

从源码中能够看出 TextFiled#contextMenuBuilder 构造器是一个 EditableTextContextMenuBuilder 函数目标，回来 Widget 用于构建菜单内容。回调在有两个入参: context 和 editableTextState。

typedef EditableTextContextMenuBuilder = Widget Function(
  BuildContext context,
  EditableTextState editableTextState,
);

---

下面看一下官方输入框弹出东西栏的代码实现， 下面代码中中心在于 TextField 中增加了 contextMenuBuilder 回调用于构建菜单组件：

class EmailButtonPage extends StatelessWidget {
  EmailButtonPage({super.key});
  final TextEditingController _controller = TextEditingController(
    text: 'Select the email address and open the menu: me@example.com',
  );
  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 300.0,
      child: TextField(
        maxLines: 2,
        controller: _controller,
        contextMenuBuilder: _buildContextMenu,
      ),
    );
  }

在构建逻辑中，经过 isValidEmail 校验选中的文本是否包含邮箱，如果包含则在 buttonItems 的首位增加 Send email 的按钮：

Widget _buildContextMenu(BuildContext context,EditableTextState state){
  final TextEditingValue value = state.textEditingValue;
  final List<ContextMenuButtonItem> buttonItems = state.contextMenuButtonItems;
  String selectValue = value.selection.textInside(value.text);
  if (isValidEmail(selectValue)) {
    buttonItems.insert(0,
        ContextMenuButtonItem(
          label: 'Send email',
          onPressed: () =>onSendEmail(selectValue),
        ));
  }
  return AdaptiveTextSelectionToolbar.buttonItems(
    anchors: state.contextMenuAnchors,
    buttonItems: buttonItems,
  );
}
/// Returns true if the given String is a valid email address.
bool isValidEmail(String text) {
  return RegExp(
    r'(?<name>[a-zA-Z0-9]+)'
    r'@'
    r'(?<domain>[a-zA-Z0-9]+)'
    r'.'
    r'(?<topLevelDomain>[a-zA-Z0-9]+)',
  ).hasMatch(text);
}

---

3. 输入框默许菜单源码简看

经过调试不难发现，当有文字选中时， EditableTextState 的 contextMenuButtonItems 是四个值，此刻按钮条目分别是剪切、仿制、粘贴、全选：

也就是说，这个几个东西是 Flutter 源码中默许供给的，能够简略瞄一下其间的逻辑。如下所示，是 EditableTextState 获取 contextMenuButtonItems 的逻辑。很简略能够看出，它会依据输入框状态信息，供给不同的菜单按钮。

其间 buttonItemsForToolbarOptions 是依据 toolbarOptions 成员构建菜单的办法，不过随着 contextMenuBuilder 的支持，这个属性已经过时了，也不建议运用。所以这里的默许菜单项是由 EditableText#getEditableButtonItems 静态办法创建的：

---

创建的逻辑也很简略，依据回调是否为空，在回来的 ContextMenuButtonItem 中增加对应类型的菜单项：

---

别的，从源码中还能学到一些小东西的处理逻辑，比方怎么仿制粘贴，怎么剪切和全选内容。下面来略微瞄一眼，仿制办法经过 Clipboard.setData 静态办法，传入 ClipboardData 数据：

粘贴运用 Clipboard.getData 静态办法：

剪切和仿制类似，都是经过 Clipboard.setData 将字符数据放入剪切板。只不过需求将挑选的文字移除，运用如下的 _replaceText 办法处理：

最后，全选经过更新 textEditingValue 的 selection 装备实现，从 0 开端到字符串长度停止，表明全选。

---

4. 认识一下 AdaptiveTextSelectionToolbar 组件

严格来说 ContextMenuButtonItem 仅仅一个装备数据，并非 Widget 组件。

这里浮层菜单东西的界面是由 AdaptiveTextSelectionToolbar 组件决议的，ContextMenuButtonItem 仅仅其间的数据项。从上面能够看出，不同渠道有不同的菜单界面。比方 Android 中是横排，Windows 中是竖排：

Android 中	Windows 中

这就表明，在 AdaptiveTextSelectionToolbar 组件的 build 构建逻辑中，必然会对不同渠道进行区分对待。如下是其构建逻辑的源码，的确如此，分为四种东西栏组件，依据不同渠道进行构建。这也是渠道间组件适配的常见方法。

---

别的能够看出 getAdaptiveButtons 静态办法会将ContextMenuButtonItem 列表 buttonItems 数据，转化成 Widget 组件列表。其间，也是依据不同渠道组件，映射出不同的组件列表:

到这里能够知道 AdaptiveTextSelectionToolbar 仅仅一个简略的适配，并不能灵敏自定义菜单项的展示作用。这感觉还是有些遗憾的，虽然能用，但不是太好用。如果在需求中期望自定义菜单项，比方图标、快捷键说明、分割线、激活作用等，能够依据 AdaptiveTextSelectionToolbar 来自己写个组件来处理：

---

5. 自定义 ContextMenu 菜单: ContextMenuController

上面展示浮层菜单是 TextFiled 组件内部供给的 contextMenuBuilder 回调，那怎么让 任何组件 都支持浮层菜单呢？Flutter 中供给了 ContextMenuController 控制器来办理，下面先经过图片的浮层菜单来认识一下控制器的运用：

首要，浮层的显现/消失是手势事情触发的，对于桌面端来说 GestureDetector 的 onSecondaryTapUp 能够监听鼠标的点击事情。也就是说，在 _onSecondaryTapUp 中经过 _contextMenuController 显现浮层：

class ImageContextMenu extends StatefulWidget {
  const ImageContextMenu({Key? key}) : super(key: key);
  @override
  State<ImageContextMenu> createState() => _ImageContextMenuState();
}
class _ImageContextMenuState extends State<ImageContextMenu> {
  final ContextMenuController _contextMenuController = ContextMenuController();
  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onSecondaryTapUp: _onSecondaryTapUp,
      onTap: _onTap,
      child: Image.asset(
        'assets/images/sabar.webp',
        height: 400,
      ),
    );
  }

浮层的显现中心是 _contextMenuController.show 办法，其间需求传入 contextMenuBuilder 回调构建组件进行显现。菜单组件的构建仍然经过 AdaptiveTextSelectionToolbar 来完结，其间 anchors 作为锚点确认浮层的位置。

void _onSecondaryTapUp(TapUpDetails details) {
  _show(details.globalPosition);
}
void _show(Offset position) {
  _contextMenuController.show(
    context: context,
    contextMenuBuilder: (ctx) => _buildContent(ctx, position),
  );
}
Widget _buildContent(BuildContext context, Offset offset) {
  return AdaptiveTextSelectionToolbar.buttonItems(
    anchors: TextSelectionToolbarAnchors(
      primaryAnchor: offset,
    ),
    buttonItems: ['保存图片','共享图片','修改图片'].map((label) => ContextMenuButtonItem(
      onPressed: () {
        ContextMenuController.removeAny();
      },
      label: label,
    )).toList()
  );
}

浮层的消失经过 _contextMenuController.remove 即可：

void _onTap() {
  if (!_contextMenuController.isShown) {
    return;
  }
  _hide();
}
void _hide() {
  _contextMenuController.remove();
}

这就是一个最简略的经过 ContextMenuController 展示/躲藏浮层菜单的运用方法。对于移动端来说，能够监听长按事情来弹出菜单。菜单随手势的行为逻辑是基本上固定的，不同运用场景中仅仅菜单内容组件的差异，所以能够封装一个组件处理行为逻辑，让外界供给菜单界面的组件构建。

---

其实这和 TextFiled 的 contextMenuBuilder 是异曲同工的，官方在案例中给出了 context_menu_region 进行简略封装，来简化运用。如下所示，直接运用 ContextMenuRegion 进行处理，经过 contextMenuBuilder 回调让运用者供给组件。也能完结相同的功用：

class ImageContextMenuV2 extends StatelessWidget{
  const ImageContextMenuV2({super.key});
  @override
  Widget build(BuildContext context) {
    return ContextMenuRegion(
      contextMenuBuilder: _buildContent,
      child: Image.asset(
        'assets/images/sabar.webp',
        height: 400,
      ),
    );
  }
  Widget _buildContent(BuildContext context, Offset offset) {
    return AdaptiveTextSelectionToolbar.buttonItems(
      anchors: TextSelectionToolbarAnchors(
        primaryAnchor: offset,
      ),
      buttonItems: ['保存图片','共享图片','修改图片'].map((label) => ContextMenuButtonItem(
        onPressed: () {
          ContextMenuController.removeAny();
        },
        label: label,
      )).toList()
    );
  }
}

别的留意一点，目前 ContextMenuRegion 并非 Flutter 原生组件，是自定义封装的，代码见文尾。后面能够研究一下 AdaptiveTextSelectionToolbar 组件不同渠道的详细组件实现细节，来自定义一些款式。那本文就到这里，谢谢观看 ~

---

typedef ContextMenuBuilder = Widget Function(
    BuildContext context, Offset offset);
/// Shows and hides the context menu based on user gestures.
///
/// By default, shows the menu on right clicks and long presses.
class ContextMenuRegion extends StatefulWidget {
  /// Creates an instance of [ContextMenuRegion].
  const ContextMenuRegion({
    super.key,
    required this.child,
    required this.contextMenuBuilder,
  });
  /// Builds the context menu.
  final ContextMenuBuilder contextMenuBuilder;
  /// The child widget that will be listened to for gestures.
  final Widget child;
  @override
  State<ContextMenuRegion> createState() => _ContextMenuRegionState();
}
class _ContextMenuRegionState extends State<ContextMenuRegion> {
  Offset? _longPressOffset;
  final ContextMenuController _contextMenuController = ContextMenuController();
  static bool get _longPressEnabled {
    switch (defaultTargetPlatform) {
      case TargetPlatform.android:
      case TargetPlatform.iOS:
        return true;
      case TargetPlatform.macOS:
      case TargetPlatform.fuchsia:
      case TargetPlatform.linux:
      case TargetPlatform.windows:
        return false;
    }
  }
  void _onSecondaryTapUp(TapUpDetails details) {
    _show(details.globalPosition);
  }
  void _onTap() {
    if (!_contextMenuController.isShown) {
      return;
    }
    _hide();
  }
  void _onLongPressStart(LongPressStartDetails details) {
    _longPressOffset = details.globalPosition;
  }
  void _onLongPress() {
    assert(_longPressOffset != null);
    _show(_longPressOffset!);
    _longPressOffset = null;
  }
  void _show(Offset position) {
    _contextMenuController.show(
      context: context,
      contextMenuBuilder: (context) {
        return widget.contextMenuBuilder(context, position);
      },
    );
  }
  void _hide() {
    _contextMenuController.remove();
  }
  @override
  void dispose() {
    _hide();
    super.dispose();
  }
  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      behavior: HitTestBehavior.opaque,
      onSecondaryTapUp: _onSecondaryTapUp,
      onTap: _onTap,
      onLongPress: _longPressEnabled ? _onLongPress : null,
      onLongPressStart: _longPressEnabled ? _onLongPressStart : null,
      child: widget.child,
    );
  }
}

---