hm-ui-viewer 0.2.7

Multi-platform UI viewer with FastAPI backend. Supports HarmonyOS (hdc), Android (adb), and offline file mode.

UI Viewer

基于 FastAPI 的多平台 UI 布局查看器，支持通过浏览器可视化查看应用界面截图与控件树结构，自动生成稳定的 XPath 定位语句。

功能特性

• 🖼️ 双栏布局: 左侧显示截图（带控件边框），右侧显示可折叠的控件树
• 🔗 点击联动: 点击截图或控件树节点，双向高亮对应控件
• 🎯 XPath 生成: 自动为选中控件生成多个候选 XPath，按稳定性智能排序
• 📱 多平台支持:
  • 鸿蒙 (HarmonyOS): 通过 hdc 工具实时抓取设备界面
  • Android: 通过 adb 工具实时抓取设备界面（uiautomator dump）
  • 离线文件模式: 直接上传截图和 layout 文件查看
• 🪟 桌面窗口模式: 默认使用 pywebview 打开桌面窗口，无需浏览器
• 📐 可调布局: 截图区与控件树区、控件树与属性面板之间支持拖拽调整大小
• 🔍 控件搜索: 支持按 type、text、key 搜索控件节点
• 📋 属性查看: 选中节点后显示完整属性列表，支持一键复制 XPath

安装

环境要求

• Python 3.8+
• （可选）鸿蒙设备连接需安装 HarmonyOS DevEco Studio 并配置 hdc 命令到 PATH
• （可选）Android 设备连接需安装 Android SDK Platform-Tools 并配置 adb 命令到 PATH

安装方式

# 从源码安装
pip install -e .

# 或安装构建好的 wheel 包（在 dist 目录）
pip install dist/ui_viewer-0.1.0-py3-none-any.whl

快速开始

1. 启动服务

# 默认启动桌面窗口 (pywebview, 无需浏览器), 监听 127.0.0.1:10112
hm-ui-viewer

# 指定地址和端口
python -m ui_viewer --host 0.0.0.0 --port 10112

# 回退到旧的"打开系统浏览器"模式
python -m ui_viewer --no-window

# 完全不打开任何窗口/浏览器
python -m ui_viewer --no-window --no-browser

2. 打包为 Windows 单文件 exe

桌面窗口模式可打包为单 exe，双击直接运行，内置 WebView2 固定版本运行时，无需用户另装。

pip install -e .[build]
python build_exe.py
# 产物: dist/UIViewer.exe

打包后双击 UIViewer.exe 即弹出一个桌面窗口承载 UI，关闭窗口即退出。

3. 使用方式

方式一：连接真实设备（实时抓取）

1. 确保设备已通过 USB 连接并开启开发者模式
2. 点击顶部工具栏「连接设备 ▾」，选择设备平台（鸿蒙/Android）
3. （可选）输入设备序列号，留空使用默认设备
4. 点击「连接」后，在左侧设备列表选中设备
5. 点击「重新 Dump」按钮抓取当前界面

方式二：离线文件模式（上传文件）

1. 点击顶部工具栏「上传截图/Layout」
2. 选择对应平台，选择截图文件（jpeg/png）和 layout 文件
3. 点击「上传」即可查看

方式三：拖拽上传

1. 点击「新建 FileDevice」创建一个空的离线设备
2. 直接将截图文件拖拽到中间截图区域
3. 将 layout 文件拖拽到右侧控件树区域

4. 界面操作

• 显示控件边框: 勾选右上角「显示全部控件边框」，截图上将显示绿色虚线边框
• 选择控件: 点击截图上的控件或控件树节点，属性面板将显示该节点信息
• 展开/折叠: 使用「全部展开」「全部折叠」按钮控制控件树
• 搜索控件: 在搜索框输入关键词，实时过滤匹配的控件节点
• 复制 XPath: 点击 XPath 区域的「复制」按钮复制最优 XPath
• 调整布局: 拖拽中间垂直分割线调整左右宽度，拖拽水平分割线调整上下高度

项目结构

ui_viewer/
├── src/ui_viewer/
│   ├── static/           # 前端静态资源 (HTML/CSS/JS)
│   ├── devices/          # 设备抽象层 (FileDevice, HarmonyDevice, AndroidDevice)
│   ├── layouts/          # Layout 解析适配器
│   ├── routers/          # FastAPI 路由
│   ├── app.py            # FastAPI 应用入口
│   └── __main__.py       # 命令行入口
├── examples/             # 示例文件和脚本
├── tests/                # 测试数据
├── docs/images/          # 文档截图
└── pyproject.toml        # 包配置

技术栈

• 后端: FastAPI + Uvicorn
• 前端: 原生 JavaScript + CSS3 (无框架依赖)
• 鸿蒙设备: 通过 hdc shell uitest dumpLayout 和 hdc shell snapshot_display 抓取数据
• Android 设备: 通过 adb shell uiautomator dump 和 adb shell screencap 抓取数据
• 桌面窗口: pywebview（WebView2 后端）

License

MIT