# xbmonitor

**Repository Path**: xiaobaiOTS/xbmonitor

## Basic Information

- **Project Name**: xbmonitor
- **Description**: 小白专用设备元素定位系统，包含设备截图、选择元素属性以及XPath表达式、自动生成代码等功能
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# XBMonitor

一个基于ADB的Android设备UI元素定位工具，提供可视化Web界面，支持多种测试框架代码生成。

## 功能特性

- 📱 **设备管理**: 自动检测并列出所有连接的Android设备
- 📷 **屏幕截图**: 获取设备实时截图，支持鼠标交互选择元素
- 🔍 **元素定位**: 可视化选择UI元素，自动生成定位表达式（XPath）
- 📋 **代码生成**: 支持Appium、UIAutomator2、ADB三种框架的样例代码生成
- 🎯 **强制XPath**: 支持强制使用XPath定位方式（ADB除外）
- 🔄 **多元素选择**: 支持连续选择多个元素，按顺序生成代码，默认开启
- ⚡ **智能定位优先级**: XPath > text > content-desc > resource-id(含index) > class+index > 坐标
- 🌐 **跨平台支持**: ADB命令自动适配Windows(`::`)和Linux/Mac(`#`)注释符
- 🔤 **中文输入支持**: Appium代码模板自动添加unicodeKeyboard参数支持中文输入
- 📦 **PO模型生成**: 支持生成完整的PO模式测试项目结构
- 📄 **代码下载**: 支持下载单文件源码或PO模型代码包（ZIP）
- 🚀 **快速启动**: 命令行一键启动，自动打开浏览器
- 🔒 **多页面模式**: 支持勾选后刷新数据不重置代码

## 安装方法

### 1. pip安装

```bash
# 从PyPI安装（推荐）
pip install xbmonitor
```

### 2. 源码安装

```bash
# 克隆或下载源码
git clone https://gitee.com/xiaobaiOTS/xbmonitor
cd xbmonitor

# 安装项目
pip install -e .
```

## 使用方法

```bash
# 启动服务（会自动打开浏览器）
xbmonitor

# 或使用选项启动
xbmonitor --host 0.0.0.0 --port 5000 --debug
```

## 命令行选项

| 选项             | 说明       | 默认值       |
| -------------- | -------- | --------- |
| `--host`       | 绑定的主机地址  | 127.0.0.1 |
| `--port`       | 监听端口     | 5000      |
| `--debug`      | 启用调试模式   | 关闭        |
| `--no-browser` | 不自动打开浏览器 | 自动打开      |
| `-h/--help`    | 显示帮助信息   | -         |

## 项目结构

```
xbmonitor/
├── src/
│   └── xbmonitor/
│       ├── __init__.py
│       ├── adb_device.py    # ADB设备管理模块
│       ├── app.py           # Flask Web服务
│       ├── cli.py           # 命令行入口
│       ├── element_locator.py # 元素定位与代码生成
│       └── static/          # 前端静态文件
│           ├── index.html
│           ├── style.css
│           └── script.js
└── README.md                # 项目说明
```

## 依赖

- Python 3.7+
- Flask
- ADB工具（需提前安装并配置环境变量）

## 使用场景

1. 连接Android设备并启用USB调试
2. 运行 `xbmonitor` 命令启动服务
3. 在浏览器中选择设备和UI元素
4. 查看元素属性和定位表达式
5. 选择测试框架，复制或下载样例代码

## 版本更新

v0.4.1

- 📦 **运行代码优化**：
  - Appium 和 UIAutomator2 脚本运行前自动在 `%temp%\xbmonitor` 目录创建虚拟环境
  - 在虚拟环境中安装依赖并运行脚本，避免系统环境依赖冲突

v0.4.0

- 🔧 **代码生成优化**：
  - UIAutomator2 代码末尾添加 `d.disconnect()` 关闭连接
  - ADB 命令添加 `-s $DEVICE_SERIAL` 设备参数支持多设备环境
  - 运行结果弹窗添加滚动条优化
  - PO 模型页面类和元素方法描述信息增强（text、content-desc、resource-id、class+index）
- 📦 **ADB 配置优化**：
  - 新增 `check_adb_available()` 函数检测 ADB 可用性
  - 新增 `find_adb_path()` 函数自动查找 ADB（支持常见 Android SDK 路径）
  - 新增 `generate_setup_scripts()` 生成一键配置脚本
  - 启动时自动检测并友好提示 ADB 配置状态
  - 新增 `xbmonitor --setup-adb` 命令行选项

<br />

### v0.1.3

- 🆕 **新增Ctrl+点击坐标功能**：在截图中按住Ctrl键并点击，可直接插入坐标点击代码，无需选择元素
- 🔧 **优化Ctrl按键体验**：按住Ctrl时移动鼠标不显示红色高亮框，坐标显示 `[Ctrl点击]` 标记
- 📋 **三种框架均支持**：Appium、UIAutomator2、ADB命令均支持坐标点击代码生成

### v0.1.2

- 🎯 新增强制XPath功能
- 🔄 新增多元素选择功能（默认开启）
- 📦 新增PO模型生成功能
- 📄 支持下载单文件源码或PO模型代码包（ZIP）

### v0.1.0

- 🎉 初始版本发布
- 📱 设备管理：自动检测连接的Android设备
- 📷 屏幕截图：获取设备实时截图
- 🔍 元素定位：可视化选择UI元素
- 📋 代码生成：支持Appium、UIAutomator2、ADB三种框架
- 🚀 命令行一键启动

## 许可证

MIT License