flutter_ume

English

Flutter 应用内调试工具平台

Since ^1.0.0, flutter_ume starts adapting to the Flutter 3. See [Quick Start] to learn more.

扫码或点击链接下载 apk，快速体验 UME。 https://github.com/bytedance/flutter_ume/releases/download/v0.2.1.0/app-debug.apk

最新版本(1.0.1)内置 13 个插件，开发者可以创建自己的插件，并集成进 UME 平台。详见本文为 UME 开发插件部分。

更多开源社区贡献的调试插件，请见社区插件部分。

flutter_ume

快速接入

所有名称前缀为 flutter_ume_kit_ 的 package 都是 UME 的功能插件， 用户可按需接入。

修改 pubspec.yaml，添加依赖

自 1.0.0 版本开始适配 Flutter 3。

dev_dependencies:
  flutter_ume: ^1.0.1
  flutter_ume_kit_ui: ^1.0.0
  flutter_ume_kit_device: ^1.0.0
  flutter_ume_kit_perf: ^1.0.0
  flutter_ume_kit_show_code: ^1.0.0
  flutter_ume_kit_console: ^1.0.0
  flutter_ume_kit_dio: ^1.0.0

↓ Null-safety 版本，适用于 Flutter 2.x

dev_dependencies:
  flutter_ume: ^0.3.0+1
  flutter_ume_kit_ui: ^0.3.0+1
  flutter_ume_kit_device: ^0.3.0
  flutter_ume_kit_perf: ^0.3.0
  flutter_ume_kit_show_code: ^0.3.0
  flutter_ume_kit_console: ^0.3.0
  flutter_ume_kit_dio: ^0.3.0

↓ 非 Null-safety 版本，适用于 Flutter 1.x

dev_dependencies:
  flutter_ume: ^0.1.1
  flutter_ume_kit_ui: ^0.1.1
  flutter_ume_kit_device: ^0.1.1
  flutter_ume_kit_perf: ^0.1.1
  flutter_ume_kit_show_code: ^0.1.1
  flutter_ume_kit_console: ^0.1.1

执行 flutter pub get

引入包

import 'package:flutter_ume/flutter_ume.dart'; // UME 框架
import 'package:flutter_ume_kit_ui/flutter_ume_kit_ui.dart'; // UI 插件包
import 'package:flutter_ume_kit_perf/flutter_ume_kit_perf.dart'; // 性能插件包
import 'package:flutter_ume_kit_show_code/flutter_ume_kit_show_code.dart'; // 代码查看插件包
import 'package:flutter_ume_kit_device/flutter_ume_kit_device.dart'; // 设备信息插件包
import 'package:flutter_ume_kit_console/flutter_ume_kit_console.dart'; // debugPrint 插件包
import 'package:flutter_ume_kit_dio/flutter_ume_kit_dio.dart'; // Dio 网络请求调试工具

修改程序入口，增加初始化方法及注册插件代码

void main() {
  if (kDebugMode) {
    PluginManager.instance                                 // 注册插件
      ..register(WidgetInfoInspector())
      ..register(WidgetDetailInspector())
      ..register(ColorSucker())
      ..register(AlignRuler())
      ..register(ColorPicker())                            // 新插件
      ..register(TouchIndicator())                         // 新插件
      ..register(Performance())
      ..register(ShowCode())
      ..register(MemoryInfoPage())
      ..register(CpuInfoPage())
      ..register(DeviceInfoPanel())
      ..register(Console())
      ..register(DioInspector(dio: dio));                  // 传入你的 Dio 实例
    // flutter_ume 0.3.0 版本之后
    runApp(UMEWidget(child: MyApp(), enable: true)); // 初始化
    // flutter_ume 0.3.0 版本之前
    runApp(injectUMEWidget(child: MyApp(), enable: true)); // 初始化
  } else {
    runApp(MyApp());
  }
}

flutter run 运行代码或 flutter build apk --debug、flutter build ios --debug 构建产物

部分功能依赖 VM Service，本地运行需要添加额外参数，以确保能够连接到 VM Service。

Flutter 2.0.x、2.2.x 等版本在真机上运行，flutter run 需要添加 --disable-dds 参数。在 Pull Request #80900 合入之后，--disable-dds 参数被更名为 --no-dds。

特别说明

自 0.1.1/0.2.1 版本起，已经不需要设置 useRootNavigator: false。 以下部分仅适用于 0.1.1/0.2.1 之前的版本。

由于 UME 在顶层管理了路由栈，showDialog 等方法默认使用 rootNavigator 弹出，所以必须在 showDialog、showGeneralDialog 等弹窗方法，传入参数 useRootNavigator: false 避免路由栈错误。

showDialog( context: context, builder: (ctx) => AlertDialog( title: const Text('Dialog'), actions: <Widget>[ TextButton( onPressed: () => Navigator.pop(context), child: const Text('OK')) ], ), useRootNavigator: false); // <===== 非常重要

功能介绍

当前开源版 UME 内置了 13 个插件

UI 工具包
Widget 信息	Widget 详情	对齐标尺
颜色吸管（新）	颜色吸管	触控标记

性能工具包
内存信息	性能浮层

设备信息工具包
CPU 信息	设备信息

代码查看
代码查看

日志展示
日志展示

Dio 网络请求调试工具
Dio 网络请求调试工具

为 UME 开发插件

UME 插件位于 ./kits 目录下，每个插件包都是一个 package 本小节示例可参考 ./custom_plugin_example

flutter create -t package custom_plugin 创建一个插件包，可以是 package，也可以是 plugin

修改插件包的 pubspec.yaml，添加依赖

dependencies:
  flutter_ume: '>=0.3.0 <0.4.0'

创建插件配置，实现 Pluggable 虚类

import 'package:flutter_ume/flutter_ume.dart';

class CustomPlugin implements Pluggable {
  CustomPlugin({Key key});

  @override
  Widget buildWidget(BuildContext context) => Container(
    color: Colors.white
    width: 100,
    height: 100,
    child: Center(
      child: Text('Custom Plugin')
    ),
  ); // 返回插件面板

  @override
  String get name => 'CustomPlugin'; // 插件名称

  @override
  String get displayName => 'CustomPlugin';

  @override
  void onTrigger() {} // 点击插件面板图标时调用

  @override
  ImageProvider<Object> get iconImageProvider => NetworkImage('url'); // 插件图标
}

在工程中引入自定义插件

修改 pubspec.yaml，添加依赖

dev_dependencies:
  custom_plugin:
    path: path/to/custom_plugin

执行 flutter pub get

引入包

import 'package:custom_plugin/custom_plugin.dart';

在工程中注册插件

if (kDebugMode) {
  PluginManager.instance
    ..register(CustomPlugin());
  runApp(
    UMEWidget(
      child: MyApp(), 
      enable: true
    )
  );
} else {
  runApp(MyApp());
}

运行代码

快速集成嵌入式插件

自 0.3.0 版本起引入了 PluggableWithNestedWidget，用以实现在 Widget tree 中插入嵌套 Widget，快速接入嵌入式插件。

可参考 ./kits/flutter_ume_kit_ui/lib/components/color_picker/color_picker.dart 与 ./kits/flutter_ume_kit_ui/lib/components/touch_indicator/touch_indicator.dart。

集成重点如下：

插件主体类实现 PluggableWithNestedWidget
实现 Widget buildNestedWidget(Widget child)，在该方法中处理嵌套结构并返回 Widget

如何在 Release/Profile mode 下使用 UME

开发者一旦在 Release/Profile mode 下使用 flutter_ume， 即认同将自行承担相关风险，

对于由此引发的事故，flutter_ume 维护方不承担 任何责任。

不建议在 Release/Profile mode 下使用，原因如下：

在该环境下 VM Service 不可用，因此部分插件功能不可用
在该环境下开发者需要自行隔离分发渠道，避免将相关调试代码提交到生产环境

为在 Release/Profile mode 下使用，正常接入流程中需要调整的细节：

pubspec.yaml 中，flutter_ume 及相关插件包需要在 dependencies 中引入，而不是 dev_dependencies
调用 PluginManager.instance.register() 及 UMEWidget(child: App()) 初始化方法的代码，不得由于 debug 标记剪枝（如 kDebugMode）
确保以上细节后，依次执行 flutter clean、flutter pub get 后再进行构建

版本说明

兼容性

UME 版本	1.12.13	1.22.3	2.0.1	2.2.3	2.5.3	2.8.0	3.0.5	3.3.1
0.1.x	✅	✅	✅	✅	⚠️	⚠️	❌	❌
0.2.x	❌	❌	✅	✅	✅	⚠️	❌	❌
0.3.x	❌	❌	✅	✅	✅	✅	❌	❌
1.0.x	❌	❌	⚠️	⚠️	⚠️	⚠️	✅	✅
1.1.x	❌	❌	⚠️	⚠️	⚠️	⚠️	✅	✅