Skip to main content

UI Viewer

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

UI Viewer 主界面

功能特性

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

安装

环境要求

安装方式

# 从源码安装
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

Metadata

Release files for hm-ui-viewer 0.2.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for hm-ui-viewer 0.2.7
File Interpreter ABI Platform Actions
hm_ui_viewer-0.2.7-py3-none-any.whl Python 3 none any Details for hm_ui_viewer-0.2.7-py3-none-any.whl

Release files / hm_ui_viewer-0.2.7-py3-none-any.whl

Download URL hm_ui_viewer-0.2.7-py3-none-any.whl
Size 43.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d330d0e12437a9784e5f3f4a4bc5425a33195b1eec5c62c1289a27165d8427b5
BLAKE2b-256 checksum
How to use checksums
24d76751ecf24736a37581d53b9395a46a6448ec11d0c7184010e941e9494764
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.15

Security for hm-ui-viewer 0.2.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.7 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page