搜索插件、代码仓与 APP 分类

flutter_portal 封面
插件详情v1.1.4

flutter_portal

进化的 Overlay/OverlayEntry - 声明式而非命令式,直观的上下文,以及简单的对齐方式

AndroidiOSWebmacOSWindowsLinux
近 30 天下载
26.2万
喜欢数
737
Pub 分数
150

安装插件

flutter pub add flutter_portal

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

Flutter Portal 是一种现代化的覆盖层解决方案,它用声明式、上下文感知的方法取代了传统的 Overlay 和 OverlayEntry。它简化了在 widget 树上定位和对齐 UI 元素的过程,无需命令式操作即可实现直观的布局。专为跨所有 Flutter 平台的无缝集成而设计,通过减少样板代码并提高可维护性来提升开发体验。适用于需要在复杂布局中进行精确、动态定位的模态框、提示工具、弹出框和浮动组件。

适合场景

  • 在特定小部件上显示工具提示
  • 创建上下文感知的弹出窗口
  • 构建自定义模态对话框
  • 在复杂布局上叠加用户界面元素
  • 管理分层的UI组件

主要特点

  • 声明式覆盖语法
  • 自动上下文感知
  • 直观的对齐控制
  • 跨平台兼容性
  • 最小化样板代码
  • 动态定位

适合对象

  • 开发丰富 UI 叠加层的开发者
  • 注重可维护代码的团队
  • 需要精确元素定位的项目
  • 具有分层组件的UI密集型应用
  • 面向多个平台的应用程序

使用建议

  • 新手可能需要一定的学习曲线
  • 仅限叠加层特定用例
  • 不适用于全屏导航
  • 过度叠加带来的性能影响
  • 依赖于正确的 widget 树结构

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

Build pub package codecov

flutter_portal: Evolved Overlay/OverlayEntry - declarative not imperative, intuitive-context, and easy-alignment

Want to show floating overlays - tooltips, contextual menus, dialogs, bubbles, etc? This library is an enhancement and replacement to Flutter's built-in Overlay/OverlayEntry.

🚀 Advantages

Why using flutter_portal instead of built-in Overlay/OverlayEntry/OverlayPortal?

  • Declarative, not imperative: Like everything else in the Flutter world, overlays (portals) are declarative now. Simply put your floating UI in the normal widget tree. Compare: The OverlayEntry is not a widget, and is manipulated imperatively using .insert() etc.
  • Alignment, done easily: Built-in support for aligning an overlay next to a UI component. Compare: A custom contextual menu from scratch in a few lines of code; while Overlay makes it nontrivial to align the tooltip/menu next to a widget.
  • Customizable alignment logic: For example, ensure the portal target never renders outside the screen (shiftToWithinBound), align it to portal instead of parent widget (alignToPortal), and you can even create your own align algorithm (extend EnhancedCompositedTransformAnchor). Compare: Overlay does not seem to have this.
  • The intuitive Context: The overlay entry is build with its intuitive parent as its context. Compare The Overlay approach uses the far-away overlay as its context. Update: OverlayPortal, which is inspired by this package, improved and did this well.

As a consequence, also have the following pros:

  • Easy restorable property: Since showing an overlay as simple as doing a setState, RestorableProperty works nicely. Compare: When using the Overlay approach, the state of our modals are not restored when our application is killed by the OS.
  • Correct Theme/provider: Since the overlay entry has the intuitive context, it has access to the same Theme and the different providers as the widget that shows the overlay. Compare: The Overlay approach will yield confusing Themes and providers. Update: OverlayPortal, which is inspired by this package, improved and did this well.
👀 Show me the code
PortalTarget(
  // 1. Declarative: Just provide `portalFollower` as a normal widget
  // 2. Intuitive BuildContext inside
  portalFollower: MyAwesomeOverlayWidget(),
  // 3. Align the "follower" relative to the "child" anywhere you like
  anchor: Aligned.center,
  child: MyChildWidget(),
)

To migrate from 0.x to 1.x, see the last section of the readme.

🪜 Examples

Check-out the examples folder for examples on how to use flutter_portal:

Partial screenshots:

Contextual menu Onboarding view
Discovery example

🧭 Usage

  1. Install it. Follow the standard procedure of installing this package. The simplest way may be flutter pub add flutter_portal.
  2. Add the Portal widget. For example, place it above MaterialApp. Only one Portal is needed per app.
  3. Use PortalTargets whenever you want to show some overlays.

📚 Tutorial: Show a contextual menu

In this example, we will see how we can use flutter_portal to show a menu after clicking on a RaisedButton.

Add the Portal widget

Before doing anything, you must insert the Portal widget in your widget tree. The follower widgets will behave as if they are inserted as children of this widget.

You can place this Portal above MaterialApp or near the root of a route:

Portal(
  child: MaterialApp(...)
)
The button

First, we need to create a StatefulWidget that renders our RaisedButton:

class MenuExample extends StatefulWidget {
  @override
  _MenuExampleState createState() => _MenuExampleState();
}

class _MenuExampleState extends State<MenuExample> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: RaisedButton(
          onPressed: () {},
          child: Text('show menu'),
        ),
      ),
    );
  }
}

image

The menu - initial iteration

Then, we need to insert our PortalTarget in the widget tree.

We want our contextual menu to render right next to our RaisedButton. As such, our PortalTarget should be the parent of RaisedButton like so:

child: PortalTarget(
  visible: // TODO
  anchor: // TODO
  portalFollower: // TODO
  child: RaisedButton(...),
),

We can pass our menu to PortalTarget:

PortalTarget(
  visible: true,
  anchor: Filled(),
  portalFollower: Material(
    elevation: 8,
    child: IntrinsicWidth(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          ListTile(title: Text('option 1')),
          ListTile(title: Text('option 2')),
        ],
      ),
    ),
  ),
  child: RaisedButton(...),
)

At this stage, you may notice two things:

  • our menu is full-screen (because anchor is Filled)
  • our menu is always visible (because visible is true)
Change alignment

Let's fix the full-screen issue first and change our code so that our menu renders on the right of our RaisedButton.

To align our menu around our button, we can change the anchor parameter:

PortalTarget(
  visible: true,
  anchor: const Aligned(
    follower: Alignment.topLeft,
    target: Alignment.topRight,
  ),
  portalFollower: Material(...),
  child: RaisedButton(...),
)

What this code means is, this will align the top-left of our menu with the top-right or the `RaisedButton`. With this, our menu is no-longer full-screen and is now located to the right of our button.
Show the menu

Finally, we can update our code such that the menu show only when clicking on the button.

To do that, we need to declare a new boolean inside our StatefulWidget, that says whether the menu is open or not:

class _MenuExampleState extends State<MenuExample> {
  bool isMenuOpen = false;
  ...
}

We then pass this isMenuOpen variable to our PortalEntry:

PortalTarget(
  visible: isMenuOpen,
  ...
)

Then, inside the onPressed callback of our RaisedButton, we can update this isMenuOpen variable:

RaisedButton(
  onPressed: () {
    setState(() {
      isMenuOpen = true;
    });
  },
  child: Text('show menu'),
),
Hide the menu

One final step is to close the menu when the user clicks randomly outside of the menu.

This can be implemented with a second PortalEntry combined with [GestureDetector] like so:

PortalTarget(
  visible: isMenuOpen,
  portalFollower: GestureDetector(
    behavior: HitTestBehavior.opaque,
    onTap: () {
      setState(() {
        isMenuOpen = false;
      });
    },
  ),
  ...
),

🎼 Concepts

There are a few concepts that are useful to fully understand when using flutter_portal. That is especially true if you want to support custom use cases, which is easily possible with the abstract API provided.

In the following, each of the abstract concepts you need to understand are explained on a high level. You will find them both in class names (e.g. the Portal widget or the PortalTarget widget as well as in parameter names).

Portal

A portal (or the portal if you only have one) is the space used for doing all of the portal work. On a low level, this means that you have one widget that allows its subtree to place targets and followers that are connected.

The portal also defines the area (rectangle bounds) that are available to any followers to be rendered onto the screen.

In detail, you might wrap your whole MaterialApp in a single Portal widget, which would mean that you can use the whole area of your app to render followers attached to targets that are children of the Portal widget.

Target

A target is any place within a portal that can be followed by a follower. This allows you to attach whatever you want to overlay to a specific place in your UI, no matter where it moves dynamically.

On a low level, this means that you wrap the part of your UI that you want to follow in a PortalTarget widget and configure it.

Example

Imagine you want to display tooltips when an avatar is hovered in your app. In that case, the avatar would be the portal target and could be used to anchor the tooltip that is overlayed.

Another example would be a dropdown menu. The widget that shows the current selection is the target and when tapping on it, the dropdown options would be overlayed through the portal as the follower.

Follower

A follower can only be used in combination with a target. You can use it for anything that you want to overlay on top of your UI, attached to a target.

Specifically, this means that you can pass one follower to every PortalTarget, which will be displayed above your UI within the portal when you specify so.

Example

If you wanted to display an autocomplete text field using flutter_portal, you would want to follow the text field to overlay your autocomplete suggestions. The widget for the autocomplete suggestions would be the portal follower in that case.

Anchor

Anchors define the layout connection between targets and followers. In general, anchors are implemented as an abstract API that provides all the information necessary to support any positioning you want. That means that anchors can be defined based on the attributes of the associated portal, target, and follower.

There are a few anchors that are implemented by default, e.g. Aligned or Filled.

⛵ Migration from 0.x

There are some breaking changes (mostly introduced by #44) from 0.x to 1.0, but it can be easily migrated. The following:

PortalEntry(
  portalAnchor: Alignment.topLeft,
  childAnchor: Alignment.topRight,
  portal: MyAwesomePortalWidget(),
  child: MyAwesomeChildWidget(),
)

Becomes:

PortalTarget(
  anchor: const Aligned(
    follower: Alignment.topLeft,
    target: Alignment.topRight,
  ),
  portalFollower: MyAwesomePortalWidget(),
  child: MyAwesomeChildWidget(),
)

If you originally use PortalEntry without portalAnchor/childAnchor (i.e. make it fullscreen), then you can write as:

PortalTarget(
  anchor: const Filled(),
  ...
)

✨ Acknowledgement

Owners

  • @rrousselGit: The former owner of this package. Create this package in December 2019, and majorly maintain until early 2022. Contributions include: Implementation of the package, including code, documentations, examples, etc. Change algorithms of rendering. Remove PortalEntry's generic. Allow delaying the disappearance of PortalEntry, useful for leave animations.
  • @fzyzcjy: The current owner of this package. See CHANGELOG.md for contributions.

Contributors

所属分类

依赖

依赖清单 2 项

源码仓库

使用此插件的项目

所在榜单