Android UI Tree

Android UIAutomator 图层查看工具。它通过 adb 获取当前设备的 UI XML，把真实节点字段整理成终端树和可搜索、可折叠的 HTML 页面，适合 Android 页面联调、布局核对和自动化定位。

有什么用

• 查看当前页面真实存在的控件层级、resource-id、文本、描述、状态和 bounds。
• 快速确认页面当前处于哪个 Activity、包名和屏幕尺寸。
• 在 HTML 中搜索节点、展开或折叠层级、复制 id、bounds、中心点和 adb tap 命令。
• 一键「复制给 AI」：生成目标节点 + 父级路径 + 同级兄弟的精简上下文，不用再手动拼原始 dump JSON。
• 一键「复制整页精简结构」：直接把浏览器里看到的 ASCII 树复制走，不用切回终端。
• 截图反向选中：在完整截图上点一下，直接跳转并高亮对应的树节点，不用先在树里找。
• 检测重叠控件：按真实 bounds 算几何重叠，找出彼此挡住的可点击控件（常见的"点不到"bug），自动排除正常的父子嵌套结构。
• 节点详情面板可以看到「嵌套深度」「同级绘制顺序」，来自折叠后的真实树结构，不是猜的。
• 通过截图裁切预览，把 UI 树节点和设备画面进行对照。
• 页面右上角支持中 / EN 双语切换，记住上次选择。
• 默认热刷新：保持一个页面，通过按钮重新抓取最新图层，不产生一堆时间戳 HTML 文件。

工具只展示 uiautomator dump 和 adb 能确认的字段，不推测 XML 中不存在的字号、颜色、圆角或 background 属性。

环境要求

• Python 3.9+。
• Android SDK Platform-Tools，adb 已加入 PATH。
• 已连接 Android 设备或已启动模拟器，并且 adb devices 状态为 device。

检查设备：

adb devices -l

安装

不想 clone 仓库，可以直接装成命令行工具：

pipx install android-ui-tree
# 或
uvx android-ui-tree -s 66918166475552

也可以本地开发安装：

pip install -e .

快速开始

克隆仓库后直接跑脚本，不装包也可以：

cd android-ui-tree
python3 android-ui-tree.py -s 66918166475552

默认启动本地热刷新服务、打开浏览器。页面内点击「获取最新图层」即可重新 dump。设备唯一时可以省略 -s。热刷新页面固定写入：

ui-tree-html/ui-tree-live-66918166475552.html

服务占用当前终端，Ctrl-C 停止。--no-open 只启动服务，手动打开终端输出的本地 URL：

python3 android-ui-tree.py -s 66918166475552 --no-open

端口默认自动选择，也可指定：

python3 android-ui-tree.py -s 66918166475552 --port 8765

--hot / --serve 仍可用，与默认行为相同。

一次性静态 HTML

不启服务、只落一份带时间戳的静态页：

python3 android-ui-tree.py -s 66918166475552 --once

常用参数

参数	作用
-s SERIAL	指定 adb 设备序列号
--html	生成 HTML；当前默认行为也会生成
--html-only	只生成 HTML，不打印终端树
--once	一次性 dump，生成静态 HTML，不启动热刷新
--hot / --serve	兼容旧参数；默认已是热刷新
--port PORT	热刷新服务端口，0 表示自动选择
--all	保留匿名布局容器，不折叠
--no-screenshot	不嵌入截图预览
--out PATH	指定 HTML 输出路径
--no-open	不自动打开浏览器
--max-depth N	限制终端树输出深度
--no-bounds	终端树不显示 bounds
--raw	将原始 XML 输出到 stderr
--no-html	只打印终端树，不生成 HTML

直接读取已有 XML

如果已经通过其他方式拿到了 XML，可以从标准输入读取：

adb exec-out cat /data/local/tmp/window_dump.xml \
  | python3 android-ui-tree.py --stdin --once

常见问题

读不到 UI XML

先确认设备在线：

adb devices -l

再手动验证：

adb -s SERIAL shell uiautomator dump /data/local/tmp/window_dump.xml
adb -s SERIAL exec-out cat /data/local/tmp/window_dump.xml | head -c 200

工具使用 /data/local/tmp/window_dump.xml，因为部分设备对 /sdcard/window_dump.xml 会报告成功但实际不生成文件。

有多台设备

必须使用 -s 指定目标设备：

python3 android-ui-tree.py -s SERIAL

HTML 中没有字号、颜色或圆角

这是 uiautomator dump 的数据边界。需要这些 paint 属性时，应查看工程 XML、Layout Inspector 或截图，而不是从 UI XML 猜测。