theme: cyanosis
highlight: mono-blue
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 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'(? [a-zA-Z0-9]+)' r'@' r'(? [a-zA-Z0-9]+)' r'.' r'(? [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 createState() => _ImageContextMenuState(); }
class _ImageContextMenuState extends State {
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 createState() => _ContextMenuRegionState(); }
class _ContextMenuRegionState extends State { 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, ); } } ```