搜尋套件、儲存庫與 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 項

原始碼儲存庫

使用此套件的專案

暫無相關資料。