Appium 手势操作双雄对决：W3C Actions 与 Mobile Commands 完全指南 + 命令对照表（小白向）
前言
刚接触 Appium 自动化的新手，最头疼的就是“怎么让手机屏幕动起来”——点击、长按、滑动、拖拽、缩放……
其实在 Appium 3.x + Python Client 5.x 时代，官方给了两套手势方案：一套是符合W3C 国际标准的Actions，另一套是 Appium 自家的mobile:扩展命令。
本文抛开复杂的理论，用最直白的代码模板，把这两套方案掰开揉碎讲清楚。结尾附上两大体系的功能对比表格 + 每个手势的详细命令对照表，并告诉你新手应该先学哪一套。
所有代码均可在雷电 9（Android 9）+ 系统设置 APP 下直接运行。
本文为个人原创学习笔记，发布于 CSDN 仅作技术交流；Appium 遵循 Apache 2.0 开源协议。
第一部分：正规军 —— W3C Actions（推荐必学）
这是 Appium 2.0+ 就开始推广的标准写法，逻辑非常清晰：手指按下 → 移动 → 抬起。
代码虽然长一点，但每一步都看得见，适合需要精细控制或面试时展示原理的场景。
环境准备（必须导入的库）
fromselenium.webdriver.common.action_chainsimportActionChainsfromselenium.webdriver.common.actionsimportinteractionfromselenium.webdriver.common.actions.action_builderimportActionBuilderfromselenium.webdriver.common.actions.pointer_inputimportPointerInput1. 点击坐标
# 定义一个“手指”（触摸输入）finger=PointerInput(interaction.POINTER_TOUCH,"touch")# 创建动作链actions=ActionBuilder(driver,mouse=finger,keyboard=None)# 动作：移动到坐标 (500, 500) → 按下 → 释放actions.pointer_action.move_to_location(500,500)actions.pointer_action.pointer_down()# 手指按下actions.pointer_action.pointer_up()# 手指抬起# 执行actions.perform()2. 长按
actions=ActionBuilder(driver,mouse=PointerInput(interaction.POINTER_TOUCH,"touch"),keyboard=None)actions.pointer_action.move_to_location(500,500)actions.pointer_action.pointer_down()actions.pointer_action.pause(2)# 按住不动 2 秒（单位：秒）actions.pointer_action.pointer_up()actions.perform()3. 滑动（从 A 点滑到 B 点）
start_x,start_y=500,1500end_x,end_y=500,500actions=ActionBuilder(driver,mouse=PointerInput(interaction.POINTER_TOUCH,"touch"),keyboard=None)actions.pointer_action.move_to_location(start_x,start_y)actions.pointer_action.pointer_down()actions.pointer_action.move_to_location(end_x,end_y)# 移动到终点actions.pointer_action.pointer_up()actions.perform()4. 拖拽（抓取元素 A 拖到坐标 B）
start_x,start_y=100,100# 元素 A 的坐标end_x,end_y=300,300# 目标坐标actions=ActionBuilder(driver,mouse=PointerInput(interaction.POINTER_TOUCH,"touch"),keyboard=None)actions.pointer_action.move_to_location(start_x,start_y)actions.pointer_action.pointer_down()actions.pointer_action.pause(0.5)# 稍停，确保“抓住”actions.pointer_action.move_to_location(end_x,end_y)actions.pointer_action.pause(0.5)actions.pointer_action.pointer_up()actions.perform()要点总结：W3C Actions 就像写剧本，手指的每一步动作（移动、按下、暂停、抬起）都要明确指令，非常适合复杂连续手势。
第二部分：捷径版 —— Mobile Commands（偷懒专用）
这套命令是 Appium 通过execute_script提供的“魔法咒语”，代码极短，功能强大，尤其适合滑动、缩放等操作。
这是目前企业升级到 3.x 后的主流写法。
1. 点击
# 方式一：点击坐标driver.execute_script("mobile: clickGesture",{"x":500,"y":500})# 方式二：点击元素（推荐，更稳定）el=driver.find_element(AppiumBy.XPATH,"//*[@text='电池']")driver.execute_script("mobile: clickGesture",{"elementId":el.id})2. 双击
el=driver.find_element(AppiumBy.XPATH,"//*[@text='电池']")driver.execute_script("mobile: doubleClickGesture",{"elementId":el.id})3. 长按
driver.execute_script("mobile: longClickGesture",{"elementId":el.id,"duration":2000# 按住 2000 毫秒 = 2 秒})4. 滑动（方向滑动，最好用！）
不需要算终点坐标，直接告诉方向：
driver.execute_script("mobile: swipeGesture",{"left":100,# 起点 X 坐标"top":1000,# 起点 Y 坐标"width":200,# 滑动区域宽度"height":200,# 滑动区域高度"direction":"up",# 方向：up / down / left / right"percent":0.75# 滑动距离占宽/高的比例（0.0~1.0）})举例：从屏幕底部向上滑 50% 的距离：
direction: "up", percent: 0.5。
也可以用精确坐标：
driver.execute_script("mobile: swipeGesture",{"startX":500,"startY":1200,"endX":500,"endY":400})5. 拖拽
source_el=driver.find_element(AppiumBy.XPATH,"//*[@text='WLAN、移动网络、流量使用']")driver.execute_script("mobile: dragGesture",{"elementId":source_el.id,"endX":1023,"endY":368})6. 双指缩放
# 放大（两指向外扩张）driver.execute_script("mobile: pinchOpenGesture",{"elementId":map_el.id,"percent":0.5# 扩张程度})# 缩小（两指向内捏合）driver.execute_script("mobile: pinchCloseGesture",{"elementId":map_el.id,"percent":0.5})要点总结：Mobile Commands 把常用手势高度封装，一句代码搞定，非常适合快速开发。
第三部分：双雄对决 —— 两版对比表格
1. 功能维度对比
| 对比维度 | W3C Actions | Mobile Commands (mobile:) |
|---|---|---|
| 代码量 | 较长，需逐步构建“按下-移动-抬起” | 极短，一个execute_script完成 |
| 上手难度 | 略高，需要理解 ActionBuilder 机制 | 低，参数名直观，照着模板改就行 |
| 跨语言一致性 | 强，Selenium/Appium 各语言通用 | 强，JSON 参数各语言一致 |
| 支持的手势 | 所有单点、多点（多指触控） | 覆盖 90% 常用手势 |
| 精确控制 | 高，可控制每一步的持续时间、坐标 | 一般，参数固定，无法自定义暂停 |
| 缩放、旋转等 | 需自己组合多个指针，较复杂 | 一行代码搞定，极爽 |
| 维护成本 | 代码多，修改稍微麻烦 | 代码少，修改快 |
| 适用场景 | 面试展示、极复杂手势、多指同时操作 | 日常脚本、快速开发、维护量大的项目 |
2. 详细命令对照表
| 手势操作 | W3C Actions 写法 | Mobile Commands 写法 |
|---|---|---|
| 点击坐标 | actions.move_to_location(x,y).pointer_down().pointer_up() | execute_script("mobile: clickGesture", {"x": x, "y": y}) |
| 点击元素 | 需先获取元素坐标再点击，或使用click() | execute_script("mobile: clickGesture", {"elementId": el.id}) |
| 长按坐标 | actions.move_to_location(x,y).pointer_down().pause(t).pointer_up() | execute_script("mobile: longClickGesture", {"x": x, "y": y, "duration": ms}) |
| 长按元素 | 同上（需坐标） | execute_script("mobile: longClickGesture", {"elementId": el.id, "duration": ms}) |
| 双击 | 需组合两次点击 + 短暂间隔 | execute_script("mobile: doubleClickGesture", {"elementId": el.id}) |
| 滑动（方向） | 手动计算起止坐标，构建动作链 | execute_script("mobile: swipeGesture", {"direction": "up", "percent": 0.5}) |
| 滑动（精确坐标） | actions.move_to(x1,y1).pointer_down().move_to(x2,y2).pointer_up() | execute_script("mobile: swipeGesture", {"startX": x1, "startY": y1, "endX": x2, "endY": y2}) |
| 拖拽（元素到坐标） | 需手动获取元素坐标，构建长按移动 | execute_script("mobile: dragGesture", {"elementId": el.id, "endX": x, "endY": y}) |
| 拖拽（元素到元素） | 需分别获取两元素坐标 | execute_script("mobile: dragGesture", {"elementId": el1.id, "elementId2": el2.id})(部分版本支持) |
| 双指放大 | 需同时管理两根手指的移动轨迹 | execute_script("mobile: pinchOpenGesture", {"elementId": el.id, "percent": 0.5}) |
| 双指缩小 | 同上 | execute_script("mobile: pinchCloseGesture", {"elementId": el.id, "percent": 0.5}) |
四、给小白的最优学习路线
- 先玩转
mobile:命令
把swipeGesture、clickGesture、dragGesture跑通，快速获得正反馈，写脚本更有信心。 - 再了解 W3C Actions 的基本结构
不要求全记住，但要知道“手指按下→移动→抬起”这个核心逻辑，面试时能说清楚。 - 实际工作中优先使用
mobile:命令
企业项目追求效率与可维护性，mobile:命令是目前的主流实践。
版权与参考说明
- 本文为个人原创学习笔记，所有代码与案例均为实操整理，发布于 CSDN 仅作技术交流；
- Appium 为开源自动化测试框架，遵循 Apache 2.0 开源协议；
- 参考资料：Appium Mobile Commands 文档。
