企业官网建设流程全解析

用键盘接管手机：QtScrcpy 按键映射从 0 到调优

【免费下载链接】QtScrcpyAndroid实时投屏软件，此应用程序提供USB(或通过TCP/IP)连接的Android设备的显示和控制。它不需要任何root访问权限项目地址: https://gitcode.com/barry-ran/QtScrcpy

QtScrcpy 按键映射让你用键盘和鼠标完全接管手机画面。本文带你从零写出第一份 JSON 映射文件，再为射击游戏和办公场景各调出一套顺手的方案，写完整体就能直接跑起来。

这个功能到底在干什么

你可以把按键映射理解成给手机配了一套自定义遥控方案：键盘上每个键，都对应手机屏幕上的一个触摸动作。整条链路是这样的：

1. 你在电脑上按下某个键，或者移动、点击鼠标；
2. QtScrcpy 捕获这个输入事件；
3. 它去读 keymap 目录里你指定的 JSON 文件，查出这个键对应什么动作、作用在屏幕哪个位置；
4. 动作被翻译成触摸指令，通过 ADB 通道发到手机；
5. 手机执行点击、滑动或拖动，画面实时回传到电脑。

这里有个容易被忽略的双模式设计：QtScrcpy 默认处于普通映射，鼠标键盘的操作直接透传给手机；按下 switchKey 之后才切入自定义映射，你 JSON 里定义的规则开始接管输入。也就是说，同一套投屏，普通模式下它是"无线鼠标"，自定义模式下它才是"游戏手柄"。

另一个关键设计是坐标系统：所有位置都是 0 到 1 之间的相对值，把整块屏幕当成 1×1 的画布，(0.5, 0.5) 永远是屏幕正中。这就像用百分比给地图打点，同一份配置换不同分辨率的手机都能用，不用重新换算像素，也是 ADB 投屏控制能跨设备兼容的核心原因。

典型的用法有三类：游戏操控，把 WASD 变成虚拟摇杆、鼠标转视角；远程演示，在大屏上精确控制一台手机做操作讲解；多机批量操作，用分组功能同时驱动多台设备。

动手之前先备好这三样东西

写配置之前先把环境核对一遍，少一样后面全卡住：

• 已安装 QtScrcpy，并成功投屏过一次手机画面
• 手机已开启 USB 调试（设置 → 开发者选项 → USB 调试；不方便插线的话，后面也可以用 TCP/IP 无线连接）
• 电脑能通过 ADB 识别到这台设备

30 秒自检：不用打开命令行，直接在 QtScrcpy 主界面的 adb 命令框里输入devices，点执行，能列出设备序列号就说明链路是通的。顺手把开发者选项里的"显示指针位置"打开，之后调试坐标时手机屏幕会标出触摸点，省得对着黑盒猜。

🤔 想一下：你手机里最常点的按钮是哪个？先把它定下来，第一份配置就围绕它写。

手把手写你的第一份映射配置

5.1 配置文件放在哪、叫什么

映射文件就是普通的 JSON，放进项目的keymap/目录就能被识别，建议直接用应用或游戏名命名，比如mygame.json。目录里自带了几份参考配置，gameforpeace.json（和平精英）、tiktok.json（短视频上下滑）都可以对照着学写法。注意参考文件只看不改，你自己的配置另建新文件，文件名和内置的区分开，避免混淆。

5.2 最小可用骨架

下面这份配置只做一件事：按 Tab 切到自定义映射后，鼠标左键会点击手机屏幕 (0.86, 0.72) 的位置，模拟一次完整的按下抬起。

{ "switchKey": "Key_Tab", "keyMapNodes": [ { "comment": "开火", "type": "KMT_CLICK", "key": "LeftButton", "pos": { "x": 0.86, "y": 0.72 } } ] }

把它存进keymap/目录保存即可。先别急着堆功能，确认这一个节点生效之后，再往 keyMapNodes 数组里追加新节点。

5.3 五种映射节点速览

keyMapNodes 数组里每个节点都用 type 字段区分类型，项目一共支持五种，按需取用：

KMT_CLICK 普通点击：按键按下即手指按下，抬起即手指抬起，绝大多数按钮场景都用它。

{ "type": "KMT_CLICK", "key": "Key_Space", "pos": { "x": 0.8, "y": 0.8 } }

KMT_CLICK_TWICE 两次点击：一次按键触发两次完整的按下抬起，适合双击类操作。

{ "type": "KMT_CLICK_TWICE", "key": "Key_Q", "pos": { "x": 0.12, "y": 0.35 } }

KMT_CLICK_MULTI 多点连点：一次按键按 clickNodes 里的顺序、间隔触发多个位置的点击，适合"先点 A 再点 B"的连招。

{ "type": "KMT_CLICK_MULTI", "key": "Key_Space", "clickNodes": [ { "delay": 0, "pos": { "x": 0.5, "y": 0.5 } }, { "delay": 500, "pos": { "x": 0.8, "y": 0.8 } } ] }

KMT_DRAG 拖拽：从 startPos 按住、滑到 endPos 再抬手，滚动列表、拉地图这类连续滑动都交给它。

{ "type": "KMT_DRAG", "key": "Key_Up", "startPos": { "x": 0.5, "y": 0.7 }, "endPos": { "x": 0.5, "y": 0.3 } }

KMT_STEER_WHEEL 方向盘：四个键（一般是 WASD）各把虚拟摇杆推向一个方向，专治 FPS 手游里需要手指常驻的移动摇杆。

{ "type": "KMT_STEER_WHEEL", "centerPos": { "x": 0.16, "y": 0.75 }, "leftKey": "Key_A", "rightKey": "Key_D", "upKey": "Key_W", "downKey": "Key_S", "leftOffset": 0.1, "rightOffset": 0.1 }

所有 key 字段统一用 Qt 的键名枚举：字母数字写作 Key_W、Key_1，功能键写作 Key_Tab、Key_F1，鼠标用 LeftButton、RightButton。

5.4 参数速查表

不知道按钮坐标时，鼠标左键在手机上点一下，控制台会直接输出形如"pos": {"x": 0.75, "y": 0.46}的相对坐标，原样抄进配置就行，不用自己数像素。

✅ 验证点：启动应用、投屏一台手机，按一次 switchKey 切到自定义映射，再按你配置的 key——手机屏幕对应位置应该出现一次清晰的触摸反馈。左键点击没反应的话先别硬猜，直接跳到文末的排查表。

抄作业：两套完整场景模板

🎮 模板 A：射击 / 动作类手游

这份配置覆盖四件事：WASD 推动虚拟摇杆移动，鼠标移动转视角，左键开火，空格跳跃，基本是 FPS 手游的最低配置集。

{ "switchKey": "Key_Tab", "mouseMoveMap": { "startPos": { "x": 0.57, "y": 0.26 }, "speedRatioX": 3.25, "speedRatioY": 1.25 }, "keyMapNodes": [ { "comment": "方向盘", "type": "KMT_STEER_WHEEL", "centerPos": { "x": 0.16, "y": 0.75 }, "leftOffset": 0.1, "rightOffset": 0.1, "upOffset": 0.27, "downOffset": 0.2, "leftKey": "Key_A", "rightKey": "Key_D", "upKey": "Key_W", "downKey": "Key_S" }, { "comment": "开火", "type": "KMT_CLICK", "key": "LeftButton", "pos": { "x": 0.86, "y": 0.72 }, "switchMap": false }, { "comment": "跳跃", "type": "KMT_CLICK", "key": "Key_Space", "pos": { "x": 0.96, "y": 0.7 } } ] }

调参思路：mouseMoveMap 的 startPos 放在游戏里人物视野所在的区域——开启鼠标移动映射后，鼠标的位移会被转换成"以 startPos 为起点的手指拖屏"，同时鼠标本身会被隐藏、移动范围受限，所以起点放哪，视角就从哪转；centerPos 对准游戏里虚拟摇杆的中心，offset 决定推杆幅度，手感偏弱就往 0.15 加。

💡 调参口诀：speedRatio 数值越大，鼠标灵敏度越低。先用 3.25 / 1.25 这组起步，转视角太快就把对应轴的数值调大、迟钝了就调小，每次只动 0.25，一次只调一个轴，调完进游戏里跑一圈再动下一个。

模板 B：办公 / 效率类

办公场景别贪多，够用就好：回车发消息、方向键上下滑列表、Esc 返回，三个节点基本覆盖高频操作，多出来的键位留着给临时需求。

{ "switchKey": "Key_CapsLock", "keyMapNodes": [ { "comment": "发送", "type": "KMT_CLICK", "key": "Key_Enter", "pos": { "x": 0.9, "y": 0.92 } }, { "comment": "上滑", "type": "KMT_DRAG", "key": "Key_Up", "startPos": { "x": 0.5, "y": 0.7 }, "endPos": { "x": 0.5, "y": 0.3 } }, { "comment": "返回", "type": "KMT_CLICK", "key": "Key_Escape", "pos": { "x": 0.05, "y": 0.04 } } ] }

用 CapsLock 当切换键有个额外的好处：平时不碰它，进入映射模式后整个键被接管，不会和聊天软件里的快捷键打架。想一下：如果你一天要在手机上回几十条消息，把"上一条语音"和"收藏"也各配一个 KMT_CLICK，一天省下的时间会明显多于调参花掉的时间。

🔧 踩坑了？按这张表排查

表里的方法都试过还不行，把仓库克隆下来对照docs/KeyMapDes_zh.md逐字段检查你的 JSON，也可以到项目社区带着配置文件提问：git clone https://gitcode.com/barry-ran/QtScrcpy。

还能怎么玩

• 多设备分组控制：分组功能可以把多台手机排在同一界面同屏操作，同一套映射规则应用到每台设备，刷机测试、多账号维护都能直接用。
• 内置 adb 命令框：主界面就能执行 adb 命令、刷新脚本，排查设备连接问题时不用来回切窗口。
• 可视化辅助工具：社区有 QuickAssistant、ScrcpyKeyMapper 这类可视化配置工具，可以拖拽选点、导出 JSON 映射文件，坐标再不用靠控制台猜。

现在去 keymap 目录新建一个属于你的 json 文件，从映射你最常按的那一个按钮开始调。

【免费下载链接】QtScrcpyAndroid实时投屏软件，此应用程序提供USB(或通过TCP/IP)连接的Android设备的显示和控制。它不需要任何root访问权限项目地址: https://gitcode.com/barry-ran/QtScrcpy