QtScrcpy 自定义按键映射完全指南JSON 格式、五种映射类型与实战配置【免费下载链接】QtScrcpyAndroid real-time display control software项目地址: https://gitcode.com/GitHub_Trending/qt/QtScrcpy导读QtScrcpy 是一款基于 scrcpy 的 Android 实时投屏控制软件其内置的**自定义按键映射Key Mapping**功能允许你将键盘按键、鼠标移动映射为手机屏幕上的触摸点击、拖拽、多次点击与方向盘操作从而实现用键鼠畅玩手游、在电脑端批量控制安卓设备。本文以仓库文档 docs/KeyMapDes.md 为骨架结合源码与自带映射文件系统讲解按键映射 JSON 文件的编写格式、五种映射类型的字段含义、相对坐标系的换算方法以及如何使用调试输出与可视化工具快速生成映射配置。读完本文你将能独立编写、调试并导入一套可在 FPS 手游等场景直接使用的自定义按键映射。一、按键映射的加载机制与目录约定按键映射文件采用 JSON 格式。要新增自己的映射需要将 JSON 文件放入keymap目录中QtScrcpy 启动后即可识别并加载。从源码 QtScrcpy/ui/dialog.cpp 的getKeyMapPath()可以看到映射目录的解析顺序优先读取环境变量QTSCRCPY_KEYMAP_PATH若该变量未设置或指向的路径不是有效目录则回退到程序可执行文件所在目录下的keymap子目录。而getGameScript()QtScrcpy/ui/dialog.cpp会以getKeyMapPath() / fileName拼接出完整路径并读取 JSON 文本内容随后交给设备控制层解析执行。也就是说只要把 JSON 文件放进 keymap 目录或通过环境变量指定的目录并在界面中选中它映射即可生效。当前仓库的 keymap 目录下自带多份可直接参考的映射文件gameforpeace.json和平精英PUBG Mobile完整映射覆盖方向盘、开镜、开枪、换弹、舔包等几十个操作test.json演示KMT_CLICK_MULTI一键多点与KMT_DRAG拖拽两种类型的迷你示例FRAG.json、identityv.json、tiktok.json分别面向其他游戏的映射示例。二、JSON 脚本通用格式2.1 相对坐标系统映射文件中的坐标位置全部使用相对位置表示屏幕的宽和高都用 1 表示。以屏幕像素为 1920x1080 为例坐标(0.5, 0.5)表示以屏幕左上角为原点、按公式像素坐标 (屏幕宽, 屏幕高) * 相对坐标计算出的位置即(1920, 1080) * (0.5, 0.5) (960, 540)。这种设计的好处是同一份映射文件可以适配任意分辨率的手机屏幕不需要为不同机型重新计算像素坐标。JSON 中的坐标对象统一写作pos: { x: 0.5, y: 0.5 }2.2 按键码使用 Qt 枚举映射中的按键码使用Qt 枚举表示例如Key_Space空格、Key_W、Key_A、Key_Shift、Key_F1等。完整取值可查阅 Qt 官方文档中 The key names used by Qt. 一节快速定位。此外映射还支持鼠标按键如和平精英映射中的LeftButton左键开枪、RightButton右键开镜。2.3 坐标调试两种获取触摸坐标的方式编写映射前你需要先确定每个操作按钮在屏幕上的相对坐标。文档提供了两种便捷方法方法一控制台输出 pos。在投屏窗口中用鼠标左键单击目标位置控制台会直接输出该点的相对坐标。对应源码位于 QtScrcpy/ui/videoform.cpp// debug keymap pos if (event-button() Qt::LeftButton) { qreal x localPos.x() / vw-size().width(); qreal y localPos.y() / vw-size().height(); QString posTip QString(R(pos: {x: %1, y: %2})).arg(x).arg(y); qInfo() posTip.toStdString().c_str(); }即用窗口内局部坐标 / 视频控件尺寸实时换算相对坐标并直接以 JSON 片段格式输出复制即可粘贴进映射文件。方法二开启安卓开发者选项的指针位置显示。在手机的开发者选项中打开显示指针位置和显示触摸两项屏幕上会实时标注每个触摸点的像素坐标再用像素坐标除以屏幕分辨率即可得到相对坐标。三、映射文件的顶层结构与映射类型总览一份按键映射 JSON 由三个顶层字段构成字段类型说明switchKey字符串切换自定义按键映射的开关键默认映射与自定义映射之间切换mouseMoveMap对象鼠标移动映射将鼠标移动转为以startPos为起点、鼠标方向为移动方向的手指拖动keyMapNodes数组一般按键映射集合将键盘按键映射为普通的手指点击其中keyMapNodes中每个元素都必须通过type字段指明映射类型共五种类型常量中文含义典型用途KMT_CLICK普通点击按键按下模拟手指按下按键抬起模拟手指抬起KMT_CLICK_TWICE两次点击按键按下模拟一次按下-抬起按键抬起再模拟一次按下-抬起KMT_CLICK_MULTI多次点击按clickNodes数组中的delay与pos一键依次触摸多个位置KMT_DRAG拖拽按键按下模拟手指按下并拖动一段距离抬起模拟手指抬起KMT_STEER_WHEEL方向盘映射专用于 FPS 游戏中移动角色需要 4 个方向键配合四、五种映射类型的字段详解与示例4.1 KMT_CLICK普通点击字段说明key要映射的按键码pos模拟触摸的位置switchMap点击此键后除了默认的模拟触摸映射外是否释放出鼠标操作switchMap的典型应用见和平精英映射中的地图Key_MswitchMap: true与背包Key_TabswitchMap: true游戏内点击地图后需要鼠标去操作界面因此释放鼠标而跳跃Key_Space、蹲下Key_C、趴下Key_Z等纯粹触摸操作则设为false鼠标保持在隐藏的映射状态。参考 keymap/gameforpeace.json{ comment: 跳, type: KMT_CLICK, key: Key_Space, pos: { x: 0.96, y: 0.7 }, switchMap: false }4.2 KMT_CLICK_TWICE两次点击字段与KMT_CLICK相同keypos区别在于行为按键按下时模拟一次手指按下再抬起按键抬起时再模拟一次手指按下再抬起。适合探头这类需要快速双击的操作例如左探头Key_Q、右探头Key_E{ comment: 右探头, type: KMT_CLICK_TWICE, key: Key_E, pos: { x: 0.2, y: 0.35 } }4.3 KMT_CLICK_MULTI一键多次点击通过clickNodes数组实现按一次键、依次点击多个位置字段说明key要映射的按键码clickNodes数组每个元素含delay延迟delay毫秒后再模拟触摸与pos模拟触摸的位置参考 keymap/test.json 的完整示例按下空格键后先延迟 500ms 点击(0.5, 0.5)再延迟 500ms 点击(0.8, 0.8){ comment: 测试一键多点, type: KMT_CLICK_MULTI, key: Key_Space, clickNodes: [ { delay: 500, pos: { x: 0.5, y: 0.5 } }, { delay: 500, pos: { x: 0.8, y: 0.8 } } ] }4.4 KMT_DRAG拖拽字段说明key要映射的按键码startPos模拟触摸拖动的开始位置endPos模拟触摸拖动的结束位置dragSpeed拖动移动速度范围 0-1默认 1.0数值越大移动越快startDelay可选毫秒按下初始触摸后、开始拖动移动前等待的时间startDelay适用于先按住再滑动的场景——例如某些手游需要在按住物体片刻后才能拖动此时设置该字段可保证拖拽动作被游戏正确识别。示例按下方向键上键从屏幕下方拖到上方{ comment: 测试拖拽, type: KMT_DRAG, key: Key_Up, startPos: { x: 0.5, y: 0.7 }, endPos: { x: 0.5, y: 0.3 } }4.5 KMT_STEER_WHEEL方向盘映射专用于 FPS 游戏中移动角色脚步的虚拟方向盘需要 4 个按键协同工作字段说明centerPos方向盘中心点leftKey/rightKey/upKey/downKey左 / 右 / 上 / 下四个方向的按键控制leftOffset按下左键后模拟拖动到相对centerPos水平偏左leftOffset处rightOffset按下右键后模拟拖动到相对centerPos水平偏右rightOffset处upOffset按下上键后模拟拖动到相对centerPos垂直偏上upOffset处downOffset按下下键后模拟拖动到相对centerPos垂直偏下downOffset处四个 offset 决定方向盘的可移动范围值越大角色移动的幅度越大。和平精英映射中用 WASD 控制移动keymap/gameforpeace.json{ 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 }五、鼠标移动映射mouseMoveMapFPS 视野控制mouseMoveMap将鼠标移动映射为手指拖动操作用于在 FPS 手游中调整人物视野。开启后鼠标会被隐藏并限制移动范围鼠标的移动方向即手指拖动的方向。其字段如下字段说明startPos手指拖动的起始点speedRatio鼠标移动映射为手指拖动的比例控制灵敏度数值必须大于 0.00225数值越大灵敏度越低Y 轴以 2.25 的比率平移。若不适用当前手机屏幕可用下面两个字段单独设置speedRatioX鼠标 X 轴的灵敏度值必须至少为 0.001speedRatioY鼠标 Y 轴的灵敏度值必须至少为 0.001smallEyes触发小眼睛的按键通常为一组KMT_CLICK映射按下后鼠标移动被映射为以smallEyes.pos为起点、以鼠标移动方向为方向的手指拖动和平精英映射的示例keymap/gameforpeace.json展示了完整结构其中 Alt 键作为小眼睛触发键——按住 Alt 即可在不转动人物视角的情况下环顾四周mouseMoveMap: { startPos: { x: 0.57, y: 0.26 }, speedRatioX: 3.25, speedRatioY: 1.25, speedRatio: 10, smallEyes: { comment: 小眼睛, type: KMT_CLICK, key: Key_Alt, pos: { x: 0.8, y: 0.31 }, switchMap: false } }注意smallEyes本身是一个完整的KMT_CLICK节点说明它复用了普通点击的字段结构可视为嵌套映射。六、从零编写一份映射完整流程结合以上内容编写一份自定义映射的推荐流程如下确定开关键指定switchKey如Key_QuoteLeft即键盘左上角的反引号键运行时通过它切换普通映射与自定义映射采集坐标连接手机后开启投屏鼠标左键单击目标按钮从控制台复制输出的pos: {x: ..., y: ...}片段或开启安卓开发者选项的显示指针位置后手动换算编排映射节点在keyMapNodes中按需填入KMT_CLICK、KMT_CLICK_TWICE、KMT_CLICK_MULTI、KMT_DRAG、KMT_STEER_WHEEL节点每个节点均需指定type与key配置视野控制可选填写mouseMoveMap的startPos与灵敏度参数放入 keymap 目录将 JSON 文件保存到 keymap 目录或QTSCRCPY_KEYMAP_PATH环境变量指定的目录在 QtScrcpy 界面中重新加载并选中该映射。七、可视化按键映射工具手工编写 JSON 字段较多、坐标调整繁琐文档推荐了两类可视化工具QuickAssistant可直接使用的按键映射辅助工具用于可视化编排映射并生成 JSONScrcpyKeyMapper基于 Web 的 GUI 工具支持直观地创建按键映射、实时测试映射效果、将映射导出为 JSON 文件、导入现有映射进行编辑。注意该工具生成/编辑的 JSON 仍需符合本文档描述的格式并放入 QtScrcpy 的 keymap 目录后才能被识别加载。八、常见问题与调试技巧映射目录找不到源码 QtScrcpy/ui/dialog.cpp 在扫描 keymap 目录时会输出日志keymap directory not find。若控制台出现该提示请确认 keymap 目录与程序可执行文件位于同一级或正确设置了QTSCRCPY_KEYMAP_PATH环境变量。自定义映射未生效QtScrcpy 通过device-isCurrentCustomKeymap()见 QtScrcpy/ui/videoform.cpp判断当前是否处于自定义映射模式。若未生效请先按switchKey从普通映射切换到自定义映射此外在自定义映射模式下投屏窗口的鼠标中键与鼠标右键不再执行默认的 Home / 返回操作而是交给映射逻辑处理。坐标偏差相对坐标与视频控件尺寸相关若手机分辨率变化较大建议重新采集坐标灵敏度异常时优先检查speedRatio、speedRatioX、speedRatioY是否满足文档规定的最小值0.00225/0.001/0.001。JSON 语法错误映射文件必须为合法 JSON注意字段名如centerPos、leftOffset拼写、逗号与引号可直接参考 keymap/test.json 作为最小可运行模板起步。结语按键映射是 QtScrcpy 将手机屏幕变为键鼠可操作界面的核心能力。理解相对坐标、Qt 按键枚举与五种KMT_*映射类型的字段语义后你便能以 keymap 目录下的现成映射为模板为任意手游定制专属键位方案。编写时善用控制台坐标输出与安卓开发者选项的指针位置显示必要时借助可视化工具即可快速完成从坐标采集到映射落地的完整闭环。【免费下载链接】QtScrcpyAndroid real-time display control software项目地址: https://gitcode.com/GitHub_Trending/qt/QtScrcpy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考