插件介绍

flutter_console 是一个功能强大的 Flutter 控制台可视化组件，它可以将控制台窗口置于页面最顶层，方便开发者在应用运行过程中进行实时调试和日志输出查看。该插件支持多种交互功能，如折叠/展开控制台、上下拖动调整位置、拉伸调整大小、清除日志、快速滚动到底部等，为开发者提供了便捷的调试工具。

在鸿蒙（HarmonyOS）系统上，flutter_console 已经过适配，可以充分利用鸿蒙系统的窗口管理和交互特性，为开发者提供一致的跨平台调试体验。

如何使用插件

包的引入

由于这是一个自定义修改版本的三方库，需要以 git 形式引入依赖。在项目的 pubspec.yaml 文件中添加以下配置：

dependencies:
  flutter_console:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_console.git

添加依赖后，执行以下命令获取包：

flutter pub get

基本使用示例

import 'package:flutter/material.dart';
import 'dart:async';
import 'package:flutter_console/flutter_console.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final navKey = GlobalKey<NavigatorState>();

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: navKey,
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Flutter Console'),
        ),
        body: Center(
          child: GestureDetector(
            onTap: showConsole,
            child: Container(
              height: 50,
              width: 100,
              color: Colors.purple,
              child: Center(
                child: Text(
                  'Show Console',
                  style: TextStyle(color: Colors.white, fontSize: 18),
                ),
              ),
            ),
          ),
        ),
      ),
    );
  }

  void showConsole() {
    // 创建日志流
    ConsoleStream logStream = ConsoleStream();

    // 显示控制台
    ConsoleOverlay().show(
      baseOverlay: navKey.currentState!.overlay!,
      contentStream: logStream,
      y: 300, // 控制台初始位置的y坐标
    );

    // 推送日志到控制台
    pushLogs(logStream);
  }

  void pushLogs(ConsoleStream stream) {
    stream.push('控制台日志：${DateTime.now().millisecondsSinceEpoch}');

    // 定时推送日志（示例）
    Future.delayed(const Duration(milliseconds: 1000), () {
      pushLogs(stream);
    });
  }
}

API 详解

ConsoleStream

ConsoleStream 是用于管理日志流的核心类，负责处理日志消息的推送、暂停、恢复和销毁。

主要方法

方法名	描述	参数	返回值
push	推送日志消息到流中	Object? message - 日志消息，可以是字符串、对象或函数	void
pause	暂停日志流	无	void
resume	恢复日志流	无	void
destroy	销毁日志流	无	void

示例

ConsoleStream stream = ConsoleStream();

// 推送字符串日志
stream.push('这是一条字符串日志');

// 推送对象日志
stream.push({'key': 'value', 'number': 123});

// 推送函数生成的日志
stream.push(() => '动态生成的日志：${DateTime.now()}');

// 暂停日志流
stream.pause();

// 恢复日志流
stream.resume();

// 销毁日志流
stream.destroy();

ConsoleOverlay

ConsoleOverlay 用于在应用的覆盖层（Overlay）中显示控制台窗口，并提供对控制台的控制功能。

主要方法

方法名	描述	参数	返回值
show	显示控制台浮动窗口	- baseOverlay：控制台所在的覆盖层 - contentStream：日志流 - y：初始位置的y坐标（默认200）	void
unfoldWidgetUpdate	更新展开状态的浮动窗口组件	无	void
foldAction	折叠控制台窗口	无	void
refresh	刷新浮动窗口内容	无	void

示例

ConsoleStream stream = ConsoleStream();
ConsoleOverlay overlay = ConsoleOverlay();

// 显示控制台
overlay.show(
  baseOverlay: navigatorKey.currentState!.overlay!,
  contentStream: stream,
  y: 200,
);

// 折叠控制台
overlay.foldAction();

// 展开控制台
overlay.unfoldWidgetUpdate();

// 刷新控制台内容
overlay.refresh();

ConsoleWidgetState

ConsoleWidgetState 是控制台窗口的状态管理类，用于控制窗口的高度等属性。

主要方法

方法名	描述	参数	返回值
updateWindowHeight	更新窗口高度	DragUpdateDetails detail - 拖动更新详情	void

控制台功能介绍

工具栏功能（从左至右）

1. 折叠按钮：将整个控制台窗口折叠为一个小窗口，点击小窗口可以恢复大窗口视图
2. 拉伸按钮：用于上下拉伸控制台窗口，调整其高度
3. 清除按钮：清除当前控制台中的所有日志内容
4. 关闭按钮：完全关闭控制台窗口
5. 至底按钮：将控制台窗口滚动到最底部，查看最新日志

交互功能

• 上下拖动：点击控制台标题栏，可上下拖动控制台窗口调整位置
• 拉伸调整大小：点击并拖动拉伸按钮，可调整控制台窗口的高度
• 折叠/展开：点击折叠按钮可将控制台折叠为小图标，点击图标可恢复完整视图
• 日志自动滚动：新日志推送时，控制台会自动滚动到底部（可手动关闭此功能）

鸿蒙系统特性与限制

支持的功能

• ✅ 控制台窗口的显示与隐藏
• ✅ 日志消息的推送与显示
• ✅ 控制台窗口的折叠与展开
• ✅ 控制台窗口的上下拖动
• ✅ 控制台窗口的高度调整
• ✅ 日志内容的清除
• ✅ 日志的自动滚动到底部

限制

• 控制台窗口仅支持垂直方向的拖动，不支持水平方向拖动
• 控制台窗口的宽度固定，不支持宽度调整
• 在某些特殊页面布局下，控制台窗口可能会被其他UI元素遮挡

最佳实践

1. 使用Navigator的Overlay：为了确保控制台在所有页面都能正常显示，建议使用Navigator的overlay作为baseOverlay参数

2. 合理管理日志流：当不再需要控制台时，记得调用ConsoleStream.destroy()方法销毁日志流，避免内存泄漏

3. 控制日志频率：在生产环境中，避免频繁推送大量日志，以免影响应用性能

4. 使用条件编译：可以考虑使用条件编译，仅在开发环境中启用控制台功能

// 示例：仅在开发环境中显示控制台
void showConsole() {
  if (kDebugMode) {
    ConsoleStream logStream = ConsoleStream();
    ConsoleOverlay().show(
      baseOverlay: navKey.currentState!.overlay!,
      contentStream: logStream,
      y: 300,
    );
  }
}

总结

flutter_console 是一个实用的 Flutter 控制台可视化组件，为开发者提供了便捷的调试工具。通过在鸿蒙系统上的适配，开发者可以在鸿蒙应用中使用相同的 API 和交互方式来调试应用，提高开发效率。

使用该插件时，需要注意以下几点：

1. 正确配置 git 依赖，确保获取到适配鸿蒙系统的版本
2. 使用 Navigator 的 overlay 作为控制台的容器，确保全局可见性
3. 合理管理日志流的生命周期，避免内存泄漏
4. 利用条件编译等方式，控制控制台功能在不同环境中的启用状态

通过 flutter_console，开发者可以在鸿蒙系统上实现高效的应用调试，提升开发体验和应用质量。