# 移动端和桌面端配置

移动端和桌面端浏览器的配置方法和最佳实践。

---

## 代码结构参考

浏览器控制器：`vision_browser/browser.py`
示例智能体：`vision_browser/agent.py`

---

## 默认使用方式（移动模式）⭐

**重要**：Browser 类现在默认使用 **iPhone 12 Pro** 移动设备模式，适合大多数 H5 和移动端测试。

```python
from vision_browser.browser import Browser

# 默认启动（自动使用 iPhone 12 Pro 移动模式）
browser = Browser(headless=True)
browser.start()
browser.goto("https://m.example.com")  # 适合移动端页面

# 使用视觉分析
img_b64 = browser.screenshot_with_grid(cols=8, rows=16)  # 移动端推荐更密集网格

# 执行协调动作（移动端坐标 + JavaScript 点击）
browser.driver.execute_script(
    "const el=document.elementFromPoint(arguments[0], arguments[1]); if(el){el.click();}",
    195, 400
)
browser.type_text("hello")
browser.press_key("enter")

browser.close()
```

---

## 桌面模式

如需使用桌面模式，显式设置 `mobile_emulation=None`：

```python
from vision_browser.browser import Browser

# 桌面模式
browser = Browser(
    headless=True,
    window_width=1280,
    window_height=800,
    mobile_emulation=None  # 显式禁用移动模式
)
browser.start()
browser.goto("https://example.com")

# 桌面端坐标（JavaScript 点击）
browser.driver.execute_script(
    "const el=document.elementFromPoint(arguments[0], arguments[1]); if(el){el.click();}",
    640, 400
)

browser.close()
```

---

## 移动端模拟模式 📱

**默认行为**：Browser 类现在**默认使用 iPhone 12 Pro 移动模式**，无需额外配置！✨

**等同于**：在浏览器中按 F12 → 点击设备工具栏图标 → 选择"iPhone 12 Pro"

### 方法 1：使用默认配置（最简单）⭐

```python
from vision_browser.browser import Browser

# 自动使用 iPhone 12 Pro（390x844）
browser = Browser(headless=True)
browser.start()
browser.goto("https://m.example.com")

# 完成！已经在移动模式下了
```

### 方法 2：指定其他移动设备

```python
from vision_browser.browser import Browser

# 使用 mobile_emulation 参数（推荐，自动配置设备）
browser = Browser(
    headless=True,
    mobile_emulation={"deviceName": "iPhone 12 Pro"}
)
browser.start()
browser.goto("https://m.example.com")

# 或者自定义设备参数
browser = Browser(
    headless=True,
    mobile_emulation={
        "deviceMetrics": {
            "width": 390,
            "height": 844,
            "pixelRatio": 3.0
        },
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15"
    }
)
browser.start()
browser.goto("https://m.example.com")
```

### 方法 3：运行时动态切换

这个方法允许你在浏览器运行时动态切换移动/桌面模式，就像在 DevTools 中切换设备一样。

```python
from vision_browser.browser import Browser
from vision_browser.mobile_utils import enable_mobile_mode, disable_mobile_mode

# 启动桌面浏览器
browser = Browser(headless=False)
browser.start()
browser.goto("https://example.com")  # 桌面模式访问

# 动态切换到移动模式（就像按 F12 后切换设备）
enable_mobile_mode(browser.driver, device_name="iPhone 12 Pro")
browser.refresh()  # 刷新以应用移动模式

# 现在是移动模式
browser.goto("https://m.example.com")
browser.driver.execute_script(
    "const el=document.elementFromPoint(arguments[0], arguments[1]); if(el){el.click();}",
    195, 400
)

# 切换回桌面模式
disable_mobile_mode(browser.driver)
browser.refresh()
```

### 方法 4：查看可用设备列表

```python
from vision_browser.mobile_utils import list_available_devices

# 列出所有预设设备
list_available_devices()
```

输出：
```
可用的移动设备配置:

设备名称                 分辨率            像素比
--------------------------------------------------
iPhone SE            375x667         2.0
iPhone 12 Pro        390x844         3.0
iPhone 14 Pro Max    430x932         3.0
Pixel 5              393x851         2.75
Galaxy S20           360x800         3.0
Galaxy S21 Ultra     384x854         3.0
iPad Pro             1024x1366       2.0
iPad Mini            768x1024        2.0
```

---

## 移动端最佳实践

### 1. 触摸友好的点击区域
```python
# ✅ 瞄准按钮中心，确保足够的点击区域
browser.driver.execute_script(
    "const el=document.elementFromPoint(arguments[0], arguments[1]); if(el){el.click();}",
    195, 750
)  # 屏幕底部中心按钮

# ❌ 避免点击边缘
browser.driver.execute_script(
    "const el=document.elementFromPoint(arguments[0], arguments[1]); if(el){el.click();}",
    10, 750
)   # 太靠边缘
```

### 2. 滚动行为
```python
# 移动端滚动通常更快
browser.scroll(direction="down", pixels=300)  # 而不是 500
```

### 3. 视口验证
```python
# 始终验证视口尺寸
width, height = browser.get_viewport_size()
print(f"当前视口: {width}x{height}")

# 如果是移动端任务，确保 width < 500
assert width < 500, "当前不是移动端视口！"
```

### 4. 移动端坐标系统调整

**关键差异**：
- 移动端视口通常是 **390 x 844**（iPhone 12 Pro）或类似尺寸
- 坐标系统：`x ∈ [0, 390)`，`y ∈ [0, 844)`
- 元素更紧凑，点击区域更小
- 需要考虑触摸目标尺寸（建议至少 44x44 像素）

---

## 移动端示例工作流

**任务**：在移动端 H5 活动页面点击按钮

```python
from vision_browser.browser import Browser

# 启动移动端浏览器
browser = Browser(
    headless=True,
    mobile_emulation={"deviceName": "iPhone 12 Pro"}
)
browser.start()

# 打开移动端 H5 页面
browser.goto("https://m.example.com/activity")

# 🔄 重要：H5 页面必须先刷新
browser.refresh()

# 步骤1: 截图查看布局
img = browser.screenshot_with_grid(cols=8, rows=16)  # 移动端网格更密

# 步骤2: 分析并点击按钮（假设在屏幕底部中心，JavaScript 事件点击）
browser.driver.execute_script(
    "const el=document.elementFromPoint(arguments[0], arguments[1]); if(el){el.click();}",
    195, 750
)

# 步骤3: 验证
browser.screenshot_base64()

browser.close()
```

---

## 常用移动设备配置

```python
# iPhone 设备
DEVICES = {
    "iPhone 12 Pro": {"width": 390, "height": 844, "pixelRatio": 3.0},
    "iPhone SE": {"width": 375, "height": 667, "pixelRatio": 2.0},
    "iPhone 14 Pro Max": {"width": 430, "height": 932, "pixelRatio": 3.0},
}

# Android 设备
ANDROID_DEVICES = {
    "Pixel 5": {"width": 393, "height": 851, "pixelRatio": 2.75},
    "Galaxy S20": {"width": 360, "height": 800, "pixelRatio": 3.0},
}
```

---

[← 返回主文档](../SKILL.md)