Skip to content

Latest commit

 

History

History
470 lines (372 loc) · 21.3 KB

README_cn.md

File metadata and controls

470 lines (372 loc) · 21.3 KB

flutter_ume

English

Flutter 应用内调试工具平台

platforms license

pub package pub package pub package pub package pub package

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

banner

扫码或点击链接下载 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_kit_ 的 package 都是 UME 的功能插件, 用户可按需接入。

  1. 修改 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
  2. 执行 flutter pub get

  3. 引入包

    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 网络请求调试工具
  4. 修改程序入口,增加初始化方法及注册插件代码

    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());
      }
    }
  5. flutter run 运行代码 或 flutter build apk --debugflutter 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 弹出, 所以必须showDialogshowGeneralDialog 等弹窗方法,传入参数 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 信息
Widget 详情
Widget 详情
对齐标尺
对齐标尺
颜色吸管(新)
颜色吸管(新)
颜色吸管
颜色吸管
触控标记
触控标记

性能工具包

内存信息
内存信息
性能浮层
性能浮层

设备信息工具包

CPU 信息
CPU 信息
设备信息
设备信息

代码查看

代码查看
代码查看

日志展示

日志展示
日志展示

Dio 网络请求调试工具

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

为 UME 开发插件

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

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

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

    dependencies:
      flutter_ume: '>=0.3.0 <0.4.0'
  3. 创建插件配置,实现 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'); // 插件图标
    }
  4. 在工程中引入自定义插件

    1. 修改 pubspec.yaml,添加依赖

      dev_dependencies:
        custom_plugin:
          path: path/to/custom_plugin
    2. 执行 flutter pub get

    3. 引入包

      import 'package:custom_plugin/custom_plugin.dart';
  5. 在工程中注册插件

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

快速集成嵌入式插件

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

集成重点如下:

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

如何在 Release/Profile mode 下使用 UME

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

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

不建议在 Release/Profile mode 下使用,原因如下:

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

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

  1. pubspec.yaml 中,flutter_ume 及相关插件包需要在 dependencies 中引入,而不是 dev_dependencies
  2. 调用 PluginManager.instance.register()UMEWidget(child: App()) 初始化方法的代码,不得由于 debug 标记剪枝(如 kDebugMode
  3. 确保以上细节后,依次执行 flutter cleanflutter 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 ⚠️ ⚠️ ⚠️ ⚠️

⚠️ 意为未经过完整的兼容性测试,不建议使用。

特例

  • Flutter 3.7 及以上版本请使用 flutter_ume_kit_ui: ^1.1.0 及以上版本

单测覆盖率

master develop develop_nullsafety
flutter_ume Coverage Coverage Coverage
flutter_ume_kit_device Coverage Coverage Coverage
flutter_ume_kit_perf Coverage Coverage Coverage
flutter_ume_kit_show_code Coverage Coverage Coverage
flutter_ume_kit_ui Coverage Coverage Coverage
flutter_ume_kit_console Coverage Coverage Coverage
flutter_ume_kit_dio Coverage N/A Coverage

版本号规则

请参考 Semantic versions

更新日志

Changelog

开源贡献

贡献文档:Contributing

贡献者

感谢以下贡献者(排名不分先后):

ShirelyC ShirelyC
lpylpyleo lpylpyleo
Alex Li Alex Li
Swain Swain
mengdouer mengdouer
LAIIIHZ LAIIIHZ
XinLei XinLei
suli suli
wei-spring wei-spring

社区插件

第三方开源项目说明

  • 触控标记使用了 touch_indicator,颜色吸管插件使用了 cyclop
  • cyclop 进行了 fork 并修改代码以满足需要。当 PR 合入后,我们将通过 pub 的形式依赖。

开源协议

该项目遵循 MIT 协议,详情请见 LICENSE

联系开发者

可能你:

  • 发现文档错误、代码有 bug
  • 使用 UME 后应用运行产生异常
  • 发现新版本 Flutter 无法兼容
  • 有好的点子或产品建议

上述情况均可以提一个 issue

可能你:

  • 想与开发者交流
  • 想与更多 Flutter 开发者交流
  • 想与 UME 开展交流或合作

欢迎加入字节跳动 Flutter 交流群

或随时联系开发者