Flutter浮动层构建插件overlay_builder的使用

overlay_builder 是一个用于在 Flutter 中通过声明式编程构建浮动层（overlay）的插件。本文将详细介绍如何安装、使用以及一些常用的 API。

Getting Started

安装

使用命令行安装

运行以下命令：

flutter pub add overlay_builder

手动安装

在 pubspec.yaml 文件中添加以下依赖，并运行 flutter pub get：

dependencies:
    overlay_builder: ^1.1.0

Usage

基本用法

在你的 Dart 代码中，首先需要导入 overlay_builder 包：

import 'package:overlay_builder/overlay_builder.dart';

要使用 OverlayBuilder，你需要在 widget 树中的某个位置有一个子 widget，如下所示：

@override
Widget build(BuildContext context) {
  return const Text('Overlay Builder Demo');
}

然后，将当前的子 widget 包裹在 OverlayBuilder 中：

@override
Widget build(BuildContext context) {
  return OverlayBuilder(
    child: const Text('Overlay Builder Demo'),
    overlayChild: const Material(
      type: MaterialType.transparency,
      child: Center(child: Text('Overlay Test')),
    ),
  );
}

全屏覆盖

如果需要渲染一个覆盖整个屏幕的 overlay，可以设置 type 属性为 OverlayType.fullscreen：

@override
Widget build(BuildContext context) {
  return OverlayBuilder(
    type: OverlayType.fullscreen,
    child: const Text('Overlay Builder Demo'),
    overlayChild: const Material(
      type: MaterialType.transparency,
      child: Center(child: Text('Overlay Test')),
    ),
  );
}

显示和移除 Overlay

要显示或移除 overlay，可以使用 GlobalKey 来控制 OverlayBuilder 的状态：

final _overlay = GlobalKey<OverlayWidgetState>();

OverlayWidgetState get overlayController {
  return _overlay.currentState!;
  // 或者使用非空安全版本：return _overlay.currentState;
}

在 OverlayBuilder 中使用该 key：

@override
Widget build(BuildContext context) {
  return OverlayBuilder(
    key: _overlay,
    child: const Text('Overlay Builder Demo'),
    overlayChild: const Material(
      type: MaterialType.transparency,
      child: Center(child: Text('Overlay Test')),
    ),
  );
}

使用 key 来显示、移除或检查 overlay 是否正在显示：

void doSomething() {
  // 显示 overlay
  overlayController.show();

  // 移除 overlay
  overlayController.remove();

  // 检查 overlay 是否正在显示
  bool isShowing = overlayController.isShowing;

  // 切换 overlay 的显示状态
  overlayController.toggle();
}

APIS

OverlayBuilder

OverlayBuilder 用于根据其类型显示一个 overlay widget。

Props

OverlayAlignment

OverlayAlignment 与 OverlayBuilder 一起使用，用于在 type 为 OverlayType.positioned 时对齐 overlay widget。

Getters

OverlayType

OverlayType 用于根据其类型渲染 overlay。如果为 OverlayType.fullscreen，则渲染一个覆盖整个屏幕的 overlay widget；如果为 OverlayType.positioned，则渲染一个覆盖其子 widget 的 overlay widget。

Getters

OverlayWidgetState

OverlayWidgetState 与 GlobalKey 一起使用，用于获取当前 OverlayBuilder 的状态，以显示、移除或检查 overlay 是否正在显示。

Methods

Getters

Deprecation Notice

为了进行一些代码优化，OverlayWidget 和 OverlayFullscreen API 已被弃用。请改用 OverlayBuilder。

示例代码

以下是一个完整的示例代码，展示了如何使用 overlay_builder 插件：

import 'package:flutter/material.dart';
import 'package:overlay_builder/overlay_builder.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Overlay Builder Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key}) : super(key: key);

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final _overlayWidget = GlobalKey<OverlayWidgetState>();
  final _overlayFullscreen = GlobalKey<OverlayWidgetState>();

  OverlayWidgetState get overlayWidgetController {
    return _overlayWidget.currentState!;
  }

  OverlayWidgetState get overlayFullscreenController {
    return _overlayFullscreen.currentState!;
  }

  void onTap() {
    overlayWidgetController.toggle();
    overlayFullscreenController.toggle();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Overlay Builder Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            OverlayBuilder(
              key: _overlayWidget,
              child: const Text('Overlay Builder Demo'),
              overlayChild: const Material(
                type: MaterialType.transparency,
                child: CircularProgressIndicator(),
              ),
            ),
          ],
        ),
      ),
      floatingActionButton: OverlayBuilder(
        key: _overlayFullscreen,
        type: OverlayType.fullscreen,
        child: FloatingActionButton(
          onPressed: onTap,
          tooltip: 'Show Overlay',
          child: const Icon(Icons.zoom_out_map),
        ),
        overlayChild: const Material(
          type: MaterialType.transparency,
          child: Center(
            child: CircularProgressIndicator(
              valueColor: AlwaysStoppedAnimation(Colors.black),
            ),
          ),
        ),
      ), // 这个尾随逗号使自动格式化更好看
    );
  }
}

希望这篇文章能帮助你更好地理解和使用 overlay_builder 插件。如果你有任何问题或建议，请随时留言！