QtScrcpy按键映射教程
QtScrcpy可将键盘鼠标操作映射为手机触摸，用键鼠畅玩安卓手游。内置和平精英、抖音等脚本，也支持完全自定义。
快速上手
使用QtScrcpy内置脚本，只需四步即可启用按键映射。
选择脚本
点击「刷新脚本」，从下拉列表中选择需要的映射脚本（如和平精英、抖音）。
连接设备
连接手机并点击「启动服务」，开始投屏。
点击「应用」
应用所选映射脚本。
按 ~ 键切换
按~键（数字键1左边）切换到自定义映射模式，再按一次切回普通模式。
脚本编写规则
QtScrcpy按键映射脚本采用JSON格式，参考自带脚本即可快速上手。
脚本格式
映射文件为JSON格式，需放置到keymap目录下才能被QtScrcpy识别。文件可参考自带的按键映射文件写法。
按键代码
键映射中的按键代码使用Qt枚举表示，可参考Qt官方文档中的按键名称。
坐标定义方式
相对坐标
所有坐标均使用相对位置表示，屏幕宽、高均表示为1，以屏幕左上角为原点。
换算示例
1920×1080的屏幕中，坐标(0.5, 0.5)对应像素坐标(1920,1080) × (0.5,0.5) = (960,540)。
调试技巧
鼠标左键点击时，控制台会输出当前pos值，可直接使用；开启手机开发者选项中的「显示触摸位置」可观察触点坐标。
顶层映射类型
QtScrcpy按键映射脚本包含以下三个顶层配置项。
① switchKey —— 映射切换键
② mouseMoveMap —— 鼠标移动映射
鼠标移动被映射为：以startPos为起点、鼠标移动方向为手指拖动方向的操作。开启后鼠标会隐藏并限制移动范围，常用于FPS手游中调整角色视野（转视角）。
| 字段 | 含义 | 约束 |
|---|---|---|
startPos | 手指拖动起始点 | - |
speedRatio | 手指拖动的鼠标灵敏度 | 必须 ≥ 0.00225，值越大灵敏度越低；Y轴按2.25比例 |
speedRatioX | 鼠标X轴灵敏度 | 必须 ≥ 0.001 |
speedRatioY | 鼠标Y轴灵敏度 | 必须 ≥ 0.001 |
smallEyes | 触发「小眼睛」的按钮 | 按下后以smallEyes.pos为起点、鼠标移动方向映射为手指拖动 |
③ keyMapNodes —— 通用按键映射
JSON数组，所有通用按键映射放在此数组中，将键盘按键映射为普通手指点击，每个元素需指定type。
keyMapNodes节点类型
QtScrcpy提供五种操作映射类型，可组合实现点击、拖拽和方向控制。
KMT_CLICK · 普通点击
按键按下模拟手指按下，按键抬起模拟手指抬起。
keyposswitchMap
switchMap：点击此键后是否释放鼠标操作（参考和平精英M键效果）。
KMT_CLICK_TWICE · 双击
按键按下模拟手指「按下再抬起」，按键抬起再模拟一次「按下再抬起」。
keypos
KMT_CLICK_MULTI · 多次点击
按一次键模拟触摸多个位置，依据clickNodes数组。
delaypos
delay：模拟触摸前延迟的毫秒数。
KMT_DRAG · 拖拽
按键按下模拟手指按下并拖动一段距离，按键抬起模拟手指抬起。
keystartPosendPosdragSpeedstartDelay
dragSpeed：拖动速度（0-1，默认1.0，值越大越快）；startDelay：可选，初始触摸后开始拖动前的等待毫秒数。
KMT_STEER_WHEEL · 方向盘映射
专用于FPS游戏移动角色的方向盘映射，需要4个按键配合。
centerPosleftKeyrightKeyUpKeydownKeyleftOffsetrightOffsetupOffsetdownOffset
centerPos：方向盘中心点；各Offset为按下方向键后相对中心点的偏移距离。
可视化编辑工具
不想手写JSON？使用图形化工具轻松创建映射。
ScrcpyKeyMapper（开源）
免费开源的Web GUI工具：可视化创建、实时测试、导入导出JSON映射。
可在网上搜索「ScrcpyKeyMapper」获取该工具。