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

插件详情v0.2.0

flutter_debug_overlay

用于在您的应用中实现调试叠加层的 Flutter 包,提供日志查看器、HTTP 请求检查器以及可自定义的小部件,便于调试。

AndroidiOSWebmacOSWindowsLinux
近 30 天下载
6090
喜欢数
12
Pub 分数
150

安装插件

flutter pub add flutter_debug_overlay

插件介绍

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

一个 Flutter 包,为您的应用添加可自定义的调试叠加层,支持实时监控日志、HTTP 请求和性能指标。专为开发者设计,提供直观的界面,在开发过程中可轻松检查应用行为,无需依赖外部工具。该叠加层支持多个平台,并能以最少的设置无缝集成到现有项目中。通过在应用 UI 中直接显示关键信息,提升调试效率。

适合场景

  • 实时日志检查
  • HTTP 请求监控
  • 开发过程中的性能跟踪
  • 无需外部工具的快速调试
  • 测试应用状态更改
  • UI 元素调试

主要特点

  • 可自定义的调试小部件
  • 实时日志查看器
  • HTTP 请求检查器
  • 多平台支持
  • 与现有应用的轻松集成
  • 可切换的覆盖层可见性

适合对象

  • 处于活跃调试阶段的开发者
  • 需要快速应用洞察的团队
  • 需要频繁性能检查的应用
  • 前端开发人员测试UI状态
  • 移动和Web应用开发者
  • 原型设计与迭代开发

使用建议

  • 不适用于生产环境
  • 叠加层可能影响UI布局
  • 需要手动激活
  • 可能轻微影响性能
  • 高级用户自定义选项有限
  • 仅在开发期间使用

原始 README

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

Flutter Debug Overlay

The Flutter Debug Overlay package allows you to implement an overlay in your app for easy debugging, even on devices away from any computer. It provides features like displaying logs in a sorted view, inspecting logged HTTP requests with a JSON viewer, and supporting custom widgets for global actions from anywhere in your app.

Features

  • Global overlay: The debug overlay can be used as a global overlay even above your app navigation.
  • Customizable triggers: By default, the debug overlay provides two triggers for opening the overlay:
    • Mobile/Touch: Press and hold 2 fingers on the screen.
    • Desktop/Keyboard: Press ALT+F12.
  • Custom widgets: Supports custom widgets to enable global actions from everywhere in your app.
  • Log viewer: Displays your logs in a nice and sorted view.
  • HTTP request inspector: Allows you to inspect logged HTTP requests including a JSON viewer.
    • Supports implementing custom request/response body widgets using DebugHttpHandler.
  • Provided HTTP middlewares: The debug overlay provides several middleware options for logging HTTP requests, including the DioLogInterceptor for the popular dio package, HttpClientLogAdapter when utilizing the default dart:io client, and HttpLogClient for the http package.

Usage

To use the debug overlay in your app, import the package and insert the DebugOverlay widget at any point in your widget tree, to achieve a global overlay, put it in the builder of your WidgetsApp.

The short and simple way (supports only limited features and customization):

import 'package:flutter_debug_overlay/flutter_debug_overlay.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: DebugOverlay.builder(),
      home: const MyHomePage(),
    );
  }
}

The advanced way:

import 'package:flutter_debug_overlay/flutter_debug_overlay.dart';

class MyApp extends StatelessWidget {
  static final LogBucket logBucket = LogBucket();
  static final HttpBucket httpBucket = HttpBucket();

  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, child) {
        return DebugOverlay(
          hiddenFields: const [HttpHeaders.authorizationHeader, "Token"],
          logBucket: logBucket,
          httpBucket: httpBucket,
          debugEntries: [ExampleDebug()],
          child: child ?? const SizedBox.shrink(),
        );
      },
      home: const MyHomePage(),
    );
  }
}
Open the Overlay

By default, the debug overlay can be triggered either by pressing and holding two fingers on the screen or by pressing ALT+F12 on a keyboard.

You can also use the visible property of the DebugOverlay widget to control it programmatically.

Add log entries

To access your logs in the log view:

  1. Create an instance of LogBucket.
  2. Provide the instance to the DebugOverlay widget.
  3. Add your logs to the bucket via add.

With this, all log events from your app will be displayed in the debug overlay.

Example Log Sources
  • Logger

     import 'package:logger/logger.dart' hide LogEvent;
     
     // Connects logger to the overlay.
     Logger.addOutputListener((event) {
       LogLevel? level = LogLevel.values
           .firstWhereOrNull((element) => element.name == event.origin.level.name);
       if (level == null) return;
       MyApp.logBucket.add(LogEvent(
         level: level,
         message: event.origin.message,
         error: event.origin.error,
         stackTrace: event.origin.stackTrace,
         time: event.origin.time,
       ));
     });
    
  • Flutter Errors (e.g. Rendering Exceptions)

    FlutterError.onError = (details) {
      FlutterError.presentError(details);
      MyApp.logBucket.add(LogEvent(
        level: LogLevel.fatal,
        message: details.exceptionAsString(),
        error: (kDebugMode
            ? details.toDiagnosticsNode().toStringDeep()
            : details.exception.toString()),
        stackTrace: details.stack,
      ));
    };
    
  • Uncaught Exceptions

    PlatformDispatcher.instance.onError = (exception, stackTrace) {
      MyApp.logBucket.add(LogEvent(
        level: LogLevel.fatal,
        message: "Unhandled Exception",
        error: exception,
        stackTrace: stackTrace,
      ));
      return false; // "false" still dumps it to the console.
    };
    

More information: https://docs.flutter.dev/testing/errors#handling-all-types-of-errors

Add HTTP requests

To inspect HTTP requests:

  1. Create an instance of HttpBucket.
  2. Provide the instance to the DebugOverlay widget.
  3. Add your requests to the bucket:
  • By using one of the provided middlewares
    • DioLogInterceptor for the dio package.
    • HttpClientLogAdapter when utilizing the default dart:io client.
    • and HttpLogClient for the http package.
  • Manually via add.

With this, all HTTP requests made within your app will be displayed and can be inspected in the debug overlay.

Example HTTP Client Integrations
  • Dio

    dio = Dio()..interceptors.add(DioLogInterceptor(MyApp.httpBucket));
    
  • HttpClient (dart:io)

    httpClient = HttpClient();
    httpClientAdapter = HttpClientLogAdapter(MyApp.httpBucket);
    
    • Log request
      httpClientAdapter.onRequest(request);
      
    • Log response
      httpClientAdapter.onResponse(request, response, responseBody);
      
    • Log error
      httpClientAdapter.onError(request, error, stackTrace);
      
  • "http"

    client = HttpLogClient(MyApp.httpBucket, http.Client());
    
Example custom body widgets
DebugOverlay.httpHandler = CustomHttpHandler();
class CustomHttpHandler extends DebugHttpHandler {
  @override
  BodyType determineBodyType(headers, body) {
    var mediaType = headers != null ? extractMediaType(headers) : null;
    if (mediaType?.type == "image") {
      return BodyType.custom;
    }
    return super.determineBodyType(headers, body);
  }

  @override
  Widget buildCustomBody(context, headers, body, hiddenKeys) {
    if (body is List<int>) {
      return Image.memory(Uint8List.fromList(body));
    }
    return Text(body.toString());
  }
}

Additional information

If you have any questions or issues with the library, please don't hesitate to open an issue on GitHub. Contributions are always welcome, so feel free to submit a pull request if you have any improvements or bug fixes to share.

Acknowledgments

Inspired by debug_overlay and cr_logger.

所属分类

依赖

依赖清单 10 项

源码仓库

使用此插件的项目

暂无相关数据。