Metadata-Version: 2.4
Name: hm-ui-viewer
Version: 0.2.7
Summary: Multi-platform UI viewer with FastAPI backend. Supports HarmonyOS (hdc), Android (adb), and offline file mode.
Author: hm-ui-viewer
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: pydantic>=2.5
Requires-Dist: pywebview>=5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: httpx>=0.26; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == "build"

# UI Viewer

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

![UI Viewer 主界面](docs/images/main_ui.png)

## 功能特性

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

## 安装

### 环境要求

- Python 3.8+
- （可选）鸿蒙设备连接需安装 [HarmonyOS DevEco Studio](https://developer.huawei.com/consumer/cn/deveco-studio/) 并配置 `hdc` 命令到 PATH
- （可选）Android 设备连接需安装 [Android SDK Platform-Tools](https://developer.android.com/studio/releases/platform-tools) 并配置 `adb` 命令到 PATH

### 安装方式

```bash
# 从源码安装
pip install -e .

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

## 快速开始

### 1. 启动服务

```bash
# 默认启动桌面窗口 (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 固定版本运行时，无需用户另装。

```bash
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
