패키지, 저장소 및 앱 카테고리 검색

패키지 상세v0.2.0

flutter_debug_overlay

앱에서 디버그 오버레이를 구현하기 위한 플러터 패키지로, 로그 뷰어, HTTP 요청 인스펙터 및 쉽게 디버깅할 수 있는 사용자 정의 위젯을 제공합니다.

AndroidiOSWebmacOSWindowsLinux
30일 다운로드
6.1천
좋아요
12
Pub 점수
150

패키지 설치

flutter pub add flutter_debug_overlay

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

Flutter 패키지로 앱에 사용자 정의 가능한 디버그 오버레이를 추가하여 로그, HTTP 요청 및 성능 메트릭을 실시간으로 모니터링할 수 있습니다. 개발자를 위한 것으로, 외부 도구에 의존하지 않고 개발 중에 앱 동작을 쉽게 검사할 수 있는 직관적인 인터페이스를 제공합니다. 여러 플랫폼을 지원하며 최소한의 설정으로 기존 프로젝트에 원활하게 통합됩니다. 앱 UI 내에서 중요한 정보를 직접 표시함으로써 디버깅 효율성을 높입니다.

사용 사례

  • 실시간 로그 검사
  • HTTP 요청 모니터링
  • 개발 중 성능 추적
  • 외부 도구 없이 빠른 디버깅
  • 앱 상태 변경 테스트
  • UI 요소 디버깅

주요 기능

  • 사용자 정의 가능한 디버그 위젯
  • 실시간 로그 뷰어
  • HTTP 요청 인스펙터
  • 다중 플랫폼 지원
  • 기존 앱과의 간편한 통합
  • 전환 가능한 오버레이 표시

적합한 대상

  • 활성 디버깅 단계에 있는 개발자
  • 빠른 앱 인사이트가 필요한 팀
  • 자주 성능 점검이 필요한 앱
  • 프론트엔드 개발자가 UI 상태 테스트
  • 모바일 및 웹 앱 개발자
  • 프로토타이핑 및 반복 개발

고려 사항

  • 생산 사용을 위한 것이 아님
  • 오버레이가 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 개

소스 저장소

이 패키지를 사용하는 프로젝트

아직 데이터가 없습니다.