Skip to main content

Summary

#

SystemContextMenuController.show is deprecated. The same functionality can be achieved by passing the result of calling SystemContextMenu.getDefaultItems to SystemContextMenuController.showWithItems.

Background

#

The iOS-drawn SystemContextMenu feature was originally added without the ability to control which items are shown in the menu. The platform would decide which items to show based on the active TextInputConnection.

The problem with this approach is that an "Autofill" button is often shown, but Flutter does not have the ability to respond to this button. So in many cases, users see an "Autofill" button that does nothing when tapped, and Flutter app developers have no way to hide the button.

This problem is solved by introducing a new method, SystemContextMenuController.showWithItems, which requires a list of items to be passed.

Developers that have no preference which items are shown can call the new method SystemContextMenu.getDefaultItems to get the default items based on the given EditableTextState. For example, if the EditableTextState indicates that there is nothing selected, then the Copy button won't be included, since it requires a selection to copy.

Migration guide

#

Most users use the system context menu through the SystemContextMenu widget, and in this case there will be no change required. The SystemContextMenu widget automatically gets the default items under the hood.

No migration is needed:

dart
class _MyWidgetState extends State<MyWidget> {
  @override
  Widget build(BuildContext context) {
    TextField(
      contextMenuBuilder: (BuildContext context, EditableTextState editableTextState) {
        return SystemContextMenu.editableText(
          editableTextState: editableTextState,
        );
      }
    );
  }
}

For advanced users that directly work with SystemContextMenuController, migrate to the new method SystemContextMenuController.showWithItems. The default can be obtained from SystemContextMenu.getDefaultItems as a list of IOSSystemContextMenuItems, which can be converted to the format required by showWithItems through IOSSystemContextMenuItem.getData.

Code before migration:

dart
_controller.show(selectionRect);

Code after migration:

dart
final List<IOSSystemContextMenuItem> defaultItems =
    SystemContextMenu.getDefaultItems(editableTextState);
final WidgetsLocalizations localizations =
    WidgetsLocalizations.of(context);
final List<IOSSystemContextMenuItemData> defaultItemDatas =
    defaultItems
        .map((IOSSystemContextMenuItem item) =>
            item.getData(localizations))
        .toList();
_controller.showWithItems(selectionRect, defaultItemDatas);

Timeline

#

Landed in version: 3.29.0-0.3.pre
In stable release: not yet

References

#

API documentation:

Relevant issues:

Relevant PRs:

除非另有说明，本文档之所提及适用于 Flutter 的最新稳定版本，本页面最后更新时间: 2025-02-13。 查看文档源码 或者 为本页面内容提出建议。