QMK Mouse Keys 完整指南用键盘模拟鼠标指针的键码、五种移动模式与参数调优【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareQMK 固件的 Mouse Keys 功能让你把键盘当成鼠标使用指针以可配置的速度在 8 个方向移动可模拟 8 个鼠标按键和四向滚轮。读完本文你将掌握如何在 keymap 中启用该功能、映射鼠标动作键码并能依据 quantum/mousekey.h 中的真实默认值针对 Accelerated、Kinetic、Constant、Combined、Inertia 五种移动模式逐一调参让指针既有加速度响应又足够精准。启用 Mouse Keys 并映射鼠标键码使用 Mouse Keys 至少需要两步开启功能支持以及把鼠标动作映射到具体按键。在 rules.mk 中启用在 keymap 的rules.mk中加入MOUSEKEY_ENABLE yes从构建系统看builddefs/common_features.mk 中该开关除了使能 mousekey 模块本身还会强制打开 USB 鼠标描述符支持ifeq ($(strip $(MOUSEKEY_ENABLE)), yes) MOUSE_ENABLE : yes endif也就是说即使你的键盘没有独立鼠标芯片固件也会以 HID Mouse 复合设备的形式向上位机报告这正是“用键盘驱动指针”能够工作的前提。可用键码keymap 中可使用以下键码定义见 quantum/keycodes范围判断宏IS_MOUSEKEY_MOVE、IS_MOUSEKEY_BUTTON等位于 quantum/keycode.h#L31-L35KeyAliasesDescriptionQK_MOUSE_CURSOR_UPMS_UPMouse cursor upQK_MOUSE_CURSOR_DOWNMS_DOWNMouse cursor downQK_MOUSE_CURSOR_LEFTMS_LEFTMouse cursor leftQK_MOUSE_CURSOR_RIGHTMS_RGHTMouse cursor rightQK_MOUSE_BUTTON_1MS_BTN1Mouse button 1QK_MOUSE_BUTTON_2MS_BTN2Mouse button 2QK_MOUSE_BUTTON_3MS_BTN3Mouse button 3QK_MOUSE_BUTTON_4MS_BTN4Mouse button 4QK_MOUSE_BUTTON_5MS_BTN5Mouse button 5QK_MOUSE_BUTTON_6MS_BTN6Mouse button 6QK_MOUSE_BUTTON_7MS_BTN7Mouse button 7QK_MOUSE_BUTTON_8MS_BTN8Mouse button 8QK_MOUSE_WHEEL_UPMS_WHLUMouse wheel upQK_MOUSE_WHEEL_DOWNMS_WHLDMouse wheel downQK_MOUSE_WHEEL_LEFTMS_WHLLMouse wheel leftQK_MOUSE_WHEEL_RIGHTMS_WHLRMouse wheel rightQK_MOUSE_ACCELERATION_0MS_ACL0Set mouse acceleration to 0QK_MOUSE_ACCELERATION_1MS_ACL1Set mouse acceleration to 1QK_MOUSE_ACCELERATION_2MS_ACL2Set mouse acceleration to 2按住移动键持续按下的行为加速、间隔、最大速度由移动模式决定下文按模式展开。五种移动模式总览QMK 支持五种光标移动模式滚动在大多数模式下遵循同样的原则Accelerated默认按住移动键时光标持续加速直到达到最大速度。Kinetic加速曲线为二次函数——起步精准之后迅速拉满速度。Constant恒定速度移动无加速。Combined行为与 Accelerated 相同但按住加速键MS_ACL0/1/2期间切换为恒定速度。Inertia按键期间加速松键后沿二次曲线减速滑停X/Y 速度独立跟踪可做出多方向曲线运动仅作用于光标、不作用于滚轮。单位约定所有时间类参数延时、间隔以毫秒计滚轮速度以“默认滚动步长的倍数”表示例如滚动速度 8 意味着每次滚动动作覆盖操作系统定义默认步长的 8 倍。Accelerated 模式默认加速曲线的参数与源码这是默认模式。在 keymap 的config.h中可调参数如下默认值均已对照 quantum/mousekey.h#L38-L93 核对DefineDefaultDescriptionMOUSEKEY_DELAY10按下移动键到光标开始移动的延迟MOUSEKEY_INTERVAL20两次光标移动之间的时间msMOUSEKEY_MOVE_DELTA8步长MOUSEKEY_MAX_SPEED10停止加速的最大光标速度MOUSEKEY_TIME_TO_MAX30达到最大速度所需时间MOUSEKEY_WHEEL_DELAY10按下滚轮键到滚轮开始转动的延迟MOUSEKEY_WHEEL_INTERVAL80两次滚轮转动之间的时间MOUSEKEY_WHEEL_DELTA1滚轮每次转动步长MOUSEKEY_WHEEL_MAX_SPEED8每次滚动动作的最大滚轮步数MOUSEKEY_WHEEL_TIME_TO_MAX40滚动达到最大速度所需时间调参提示源自文档与实现一致MOUSEKEY_DELAY太小会让光标反应迟钝太大则难以做微小移动。源码中该值以 10ms 为粒度编译quantum/mousekey.c#L68 中mk_delay MOUSEKEY_DELAY / 10因此取 10 的整数倍最合理。想要更平滑可降低MOUSEKEY_INTERVAL。若屏幕刷新率为 60Hz可设为161/60 秒这会显著提升速度通常应同时下调MOUSEKEY_MAX_SPEED。将MOUSEKEY_TIME_TO_MAX或MOUSEKEY_WHEEL_TIME_TO_MAX设为0可分别禁用光标或滚轮的加速——这能让你让一方恒定、另一方加速而纯 Constant 模式做不到。MOUSEKEY_WHEEL_INTERVAL太低会让滚动过快太高则长按滚轮键时过慢。MS_ACL0、MS_ACL1、MS_ACL2分别把光标和滚动速度锁定为最大速度的 1/4、1/2 和最大值实现在 quantum/mousekey.c#L97-L102 的move_unit()中通过mousekey_accel位掩码选择。加速算法本身采用与 X Window System MouseKeys 相同的公式文档注明可查 Wikipedia “Mouse keys” 词条speed delta * max_speed * (repeat / time_to_max)。对应源码 quantum/mousekey.c#L95-L111static uint8_t move_unit(void) { uint16_t unit; if (mousekey_accel (1 0)) { unit (MOUSEKEY_MOVE_DELTA * mk_max_speed) / 4; } else if (mousekey_accel (1 1)) { unit (MOUSEKEY_MOVE_DELTA * mk_max_speed) / 2; } else if (mousekey_accel (1 2)) { unit (MOUSEKEY_MOVE_DELTA * mk_max_speed); } else if (mousekey_repeat 0) { unit MOUSEKEY_MOVE_DELTA; } else if (mousekey_repeat mk_time_to_max) { unit MOUSEKEY_MOVE_DELTA * mk_max_speed; } else { unit (MOUSEKEY_MOVE_DELTA * mk_max_speed * mousekey_repeat) / mk_time_to_max; } return (unit MOUSEKEY_MOVE_MAX ? MOUSEKEY_MOVE_MAX : (unit 0 ? 1 : unit)); }即速度随重复事件计数mousekey_repeat线性增长直到MK_TIME_TO_MAX后恒定于DELTA × MAX_SPEED并钳制在MOUSEKEY_MOVE_MAX默认 127见 quantum/mousekey.h#L26-L30之内。所有模式的共同点mousekey_task()在固件主循环中被周期性调用quantum/keyboard.c#L767按键按下/抬起则经由mousekey_on()/mousekey_off()更新报告。另一个值得注意的细节斜向移动如同时按住MS_UP和MS_LEFT会把两轴各乘以1/√2用整数近似 181/256 实现见 quantum/mousekey.c#L27-L38保证对角线速度与水平/垂直速度一致。Kinetic 模式二次加速曲线Kinetic 是 Accelerated 的扩展光标速度沿二次曲线增长起步段速度低适合精准定位之后迅速拉升以覆盖长距离。在config.h中启用并调参DefineDefaultDescriptionMK_KINETIC_SPEEDundefined启用 Kinetic 模式MOUSEKEY_DELAY5按下移动键到光标移动的延迟MOUSEKEY_INTERVAL10两次光标移动之间的时间msMOUSEKEY_MOVE_DELTA16从初始速度加速到基础速度的步长MOUSEKEY_INITIAL_SPEED100光标初始速度像素/秒MOUSEKEY_BASE_SPEED5000停止加速的最大光标速度MOUSEKEY_DECELERATED_SPEED400减速档光标速度MOUSEKEY_ACCELERATED_SPEED3000加速档光标速度MOUSEKEY_WHEEL_INITIAL_MOVEMENTS16滚轮初始每秒转动次数MOUSEKEY_WHEEL_BASE_MOVEMENTS32滚轮停止加速的最大转动次数MOUSEKEY_WHEEL_ACCELERATED_MOVEMENTS48滚轮加速档转动次数MOUSEKEY_WHEEL_DECELERATED_MOVEMENTS8滚轮减速档转动次数这些默认值同样来自 quantum/mousekey.h#L98-L121。调参提示流畅度取决于MOUSEKEY_INTERVAL间隔越短越平滑但过低会让光标反应迟钝微控制器足够快时可以更低。例如间隔8ms 意味着每秒发起125次移动若基础速度为1000像素/秒每次移动光标8像素。滚轮实现与光标不同光标一次可以移动多像素但滚轮这样做会顿挫因此滚轮始终以步长1输出调速方式是调整“每秒转动次数”而非单步大小。源码印证了文档描述的二次曲线quantum/mousekey.c#L180-L220/* * Kinetic movement acceleration algorithm * * current speed I A * T/50 A * (T/50)^2 * 1/2 | maximum B * * T: time since the mouse movement started * I: initial speed at time 0 * A: acceleration * B: base mouse travel speed */其中T按 50ms 为时间片累计最终速度换算成 USB 鼠标报告的 1–127 范围。MS_ACL0/MS_ACL2分别直接切到MOUSEKEY_DECELERATED_SPEED和MOUSEKEY_ACCELERATED_SPEED。Constant 模式多档恒定速度与两种选择方式Constant 模式为光标和滚轮分别定义多档固定速度无加速MS_ACL0、MS_ACL1、MS_ACL2分别切换到对应档位。速度选择有两种语义Momentary瞬时选中的速度仅在该键按住期间生效松键后回到未修饰速度。Tap-to-select点选保持按下即切换松键后保持默认速度即MS_ACL1档不存在“未修饰速度”。默认速度从慢到快MomentaryMS_ACL0MS_ACL1未修饰MS_ACL2Tap-to-selectMS_ACL0MS_ACL1MS_ACL2启用方式写入config.h#define MK_3_SPEED若使用 Momentary 语义再定义#define MK_MOMENTARY_ACCEL参数表默认值对照 quantum/mousekey.h#L125-L173DefineDefaultDescriptionMK_3_SPEEDNot defined启用恒定光标速度MK_MOMENTARY_ACCELNot defined启用瞬时速度选择MK_C_OFFSET_UNMOD16光标每次移动偏移未修饰档MK_C_INTERVAL_UNMOD16光标移动间隔未修饰档MK_C_OFFSET_01光标每次移动偏移MS_ACL0MK_C_INTERVAL_032光标移动间隔MS_ACL0MK_C_OFFSET_14光标每次移动偏移MS_ACL1MK_C_INTERVAL_116光标移动间隔MS_ACL1MK_C_OFFSET_232光标每次移动偏移MS_ACL2MK_C_INTERVAL_216光标移动间隔MS_ACL2MK_W_OFFSET_UNMOD1每次滚动动作的滚轮步数未修饰档MK_W_INTERVAL_UNMOD40滚轮步间隔未修饰档MK_W_OFFSET_01每次滚动动作的滚轮步数MS_ACL0MK_W_INTERVAL_0360滚轮步间隔MS_ACL0MK_W_OFFSET_11每次滚动动作的滚轮步数MS_ACL1MK_W_INTERVAL_1120滚轮步间隔MS_ACL1MK_W_OFFSET_21每次滚动动作的滚轮步数MS_ACL2MK_W_INTERVAL_220滚轮步间隔MS_ACL2实现上Constant 模式维护四档未修饰 三档的c_offsets[]/c_intervals[]与w_offsets[]/w_intervals[]表quantum/mousekey.c#L503-L515mousekey_on()按下MS_ACLx时切换mk_speed并调用adjust_speed()重标定当前报告量MK_MOMENTARY_ACCEL未定义时初始档位为mkspd_1定义后初始与恢复档位均为mkspd_unmodquantum/mousekey.c#L504-L509与文档的两种语义描述一一对应。Combined 模式加速与恒定速度叠加Combined 模式与Accelerated完全相同区别在于按住MS_ACL0、MS_ACL1、MS_ACL2期间光标与滚动速度会瞬时锁定为恒定值MS_ACL0锁定到最慢速度适合细小、精确定位的移动MS_ACL1锁定到用户定义最大速度的一半MS_ACL2锁定到最大速度适合大范围粗移动。未按住任何加速键时本模式与 Accelerated 无异所有 Accelerated 参数照常生效。启用#define MK_COMBINED对应实现 quantum/mousekey.c#L247-L281 中move_unit()的三个分支加速位 0 → 步长 1位 1 → 半速位 2 → 直接MOUSEKEY_MOVE_MAX其余情况走标准线性加速。Inertia 模式冰面滑行般的松键减速Inertia 模式提供“在冰面上滑行”般的运动手感按键期间光标沿二次曲线加速松键后惯性滑行并逐渐减速停止。垂直与水平速度独立跟踪因此可以同时按住多键做出任意方向的曲线轨迹。注意Inertia 不能与 Kinetic、Constant、Combined 同时使用源码中它们处于互斥的条件编译分支quantum/mousekey.c#L89-L94。推荐配置config.hDefineDefaultDescriptionMOUSEKEY_INERTIAundefined启用 Inertia 模式MOUSEKEY_DELAY150按下移动键到光标移动的延迟MOUSEKEY_INTERVAL16两次光标移动之间的时间16 60fpsMOUSEKEY_MAX_SPEED32停止加速的最大光标速度MOUSEKEY_TIME_TO_MAX32达到最大速度的帧数MOUSEKEY_FRICTION24松键后光标停止的快慢MOUSEKEY_MOVE_DELTA1首帧移动量强烈建议保持 1默认值见 quantum/mousekey.h#L50-L96MOUSEKEY_DELAY150、MOUSEKEY_INTERVAL16、MOUSEKEY_FRICTION24 等均为 Inertia 专属默认。调参提示MOUSEKEY_DELAY建议接近宿主系统的按键重复延迟推荐 100–300msMOUSEKEY_INTERVAL设为 1000 / 显示器帧率如 60FPS 对应 16MOUSEKEY_MAX_SPEED按屏幕宽度 / 帧率估算如 1920px / 60FPS ≈ 32 像素/帧MOUSEKEY_TIME_TO_MAX取约 FPS/2使光标在约半秒内达到全速MOUSEKEY_FRICTION取 1–255值越小滑行越久8–40 之间效果最明显MOUSEKEY_MOVE_DELTA保持 1保证滑行效应启动前仍可做精准移动滚轮参数沿用默认 Accelerated 模式滚轮不走惯性逻辑。实现上每帧由calc_inertia()更新各轴速度方向停止或反向时按velocity × (256 − FRICTION) / 256衰减quantum/mousekey.c#L287-L303方向键按住时速度向 ±MK_TIME_TO_MAX逐帧逼近位移则由二次曲线percent (inertia/time_to_max)² × max_speed计算quantum/mousekey.c#L113-L156。这解释了为什么“按住多键能走曲线”——X/Y 惯性各自独立互不干扰。重叠按键控制MOUSEKEY_OVERLAP_RESET当在移动过程中再按下另一个重叠的移动键时指针默认会带着现有加速度继续转向新方向。若希望新按键触发加速度重置、获得更精准的转向控制可启用以下定义DefineDefaultDescriptionMOUSEKEY_OVERLAP_RESETundefined启用重叠按键的加速度重置MOUSEKEY_OVERLAP_MOVE_DELTAMOUSEKEY_MOVE_DELTA重置后移动加速度的步长MOUSEKEY_OVERLAP_WHEEL_DELTAMOUSEKEY_WHEEL_DELTA重置后滚轮加速度的步长MOUSEKEY_OVERLAP_INTERVALMOUSEKEY_INTERVAL重置后光标移动间隔仅 Kinetic 模式对应逻辑在 quantum/mousekey.c#L395-L406mousekey_on()检测到“已有非零运动报告时又按下一个移动键”即重置mousekey_repeat计数。文档明确提示该特性在 Inertia 模式下不生效——源码条件编译defined(MOUSEKEY_OVERLAP_RESET) !defined(MOUSEKEY_INERTIA)与此一致。与 PS/2 鼠标及指向设备的报告合并Mouse Keys 的按键状态与 PS/2 鼠标 和 指向设备 共享同一份鼠标报告report_mouse_t因此MS_BTN1–MS_BTN8的按下/释放可以直接用于点击和拖拽与物理鼠标传感器驱动的光标移动叠加在同一设备上。对使用板载光学传感器POINTING_DEVICE_ENABLE或 PS/2 鼠标转接器的键盘这意味着鼠标键码补充了硬件鼠标不具备的多按键能力。小结如何为不同场景选模式通用打字间隙快速点击Accelerated默认按文档 Tips 微调MOUSEKEY_INTERVAL/MOUSEKEY_MAX_SPEED需要长距离疾速移动且起步要准KineticMK_KINETIC_SPEED注意MOUSEKEY_INTERVAL决定流畅度需要稳定可预期的三档速度如绘图/剪辑场景ConstantMK_3_SPEED可选MK_MOMENTARY_ACCEL既想保留加速手感、又想在按住快捷键时临时降速精调CombinedMK_COMBINED追求“滑停”手感与多方向曲线运动InertiaMOUSEKEY_INERTIA滚轮保持默认加速行为。所有参数均可在 keymap 的config.h覆盖 quantum/mousekey.h 中的默认值重新编译生效开启MOUSEKEY_ENABLE yes后固件即以上位机识别的 HID 复合设备键盘 鼠标上线指针移动、滚轮与按键行为完全由键码映射驱动。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QMK Mouse Keys 完整指南：用键盘模拟鼠标指针的键码、五种移动模式与参数调优
QMK Mouse Keys 完整指南用键盘模拟鼠标指针的键码、五种移动模式与参数调优【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareQMK 固件的 Mouse Keys 功能让你把键盘当成鼠标使用指针以可配置的速度在 8 个方向移动可模拟 8 个鼠标按键和四向滚轮。读完本文你将掌握如何在 keymap 中启用该功能、映射鼠标动作键码并能依据 quantum/mousekey.h 中的真实默认值针对 Accelerated、Kinetic、Constant、Combined、Inertia 五种移动模式逐一调参让指针既有加速度响应又足够精准。启用 Mouse Keys 并映射鼠标键码使用 Mouse Keys 至少需要两步开启功能支持以及把鼠标动作映射到具体按键。在 rules.mk 中启用在 keymap 的rules.mk中加入MOUSEKEY_ENABLE yes从构建系统看builddefs/common_features.mk 中该开关除了使能 mousekey 模块本身还会强制打开 USB 鼠标描述符支持ifeq ($(strip $(MOUSEKEY_ENABLE)), yes) MOUSE_ENABLE : yes endif也就是说即使你的键盘没有独立鼠标芯片固件也会以 HID Mouse 复合设备的形式向上位机报告这正是“用键盘驱动指针”能够工作的前提。可用键码keymap 中可使用以下键码定义见 quantum/keycodes范围判断宏IS_MOUSEKEY_MOVE、IS_MOUSEKEY_BUTTON等位于 quantum/keycode.h#L31-L35KeyAliasesDescriptionQK_MOUSE_CURSOR_UPMS_UPMouse cursor upQK_MOUSE_CURSOR_DOWNMS_DOWNMouse cursor downQK_MOUSE_CURSOR_LEFTMS_LEFTMouse cursor leftQK_MOUSE_CURSOR_RIGHTMS_RGHTMouse cursor rightQK_MOUSE_BUTTON_1MS_BTN1Mouse button 1QK_MOUSE_BUTTON_2MS_BTN2Mouse button 2QK_MOUSE_BUTTON_3MS_BTN3Mouse button 3QK_MOUSE_BUTTON_4MS_BTN4Mouse button 4QK_MOUSE_BUTTON_5MS_BTN5Mouse button 5QK_MOUSE_BUTTON_6MS_BTN6Mouse button 6QK_MOUSE_BUTTON_7MS_BTN7Mouse button 7QK_MOUSE_BUTTON_8MS_BTN8Mouse button 8QK_MOUSE_WHEEL_UPMS_WHLUMouse wheel upQK_MOUSE_WHEEL_DOWNMS_WHLDMouse wheel downQK_MOUSE_WHEEL_LEFTMS_WHLLMouse wheel leftQK_MOUSE_WHEEL_RIGHTMS_WHLRMouse wheel rightQK_MOUSE_ACCELERATION_0MS_ACL0Set mouse acceleration to 0QK_MOUSE_ACCELERATION_1MS_ACL1Set mouse acceleration to 1QK_MOUSE_ACCELERATION_2MS_ACL2Set mouse acceleration to 2按住移动键持续按下的行为加速、间隔、最大速度由移动模式决定下文按模式展开。五种移动模式总览QMK 支持五种光标移动模式滚动在大多数模式下遵循同样的原则Accelerated默认按住移动键时光标持续加速直到达到最大速度。Kinetic加速曲线为二次函数——起步精准之后迅速拉满速度。Constant恒定速度移动无加速。Combined行为与 Accelerated 相同但按住加速键MS_ACL0/1/2期间切换为恒定速度。Inertia按键期间加速松键后沿二次曲线减速滑停X/Y 速度独立跟踪可做出多方向曲线运动仅作用于光标、不作用于滚轮。单位约定所有时间类参数延时、间隔以毫秒计滚轮速度以“默认滚动步长的倍数”表示例如滚动速度 8 意味着每次滚动动作覆盖操作系统定义默认步长的 8 倍。Accelerated 模式默认加速曲线的参数与源码这是默认模式。在 keymap 的config.h中可调参数如下默认值均已对照 quantum/mousekey.h#L38-L93 核对DefineDefaultDescriptionMOUSEKEY_DELAY10按下移动键到光标开始移动的延迟MOUSEKEY_INTERVAL20两次光标移动之间的时间msMOUSEKEY_MOVE_DELTA8步长MOUSEKEY_MAX_SPEED10停止加速的最大光标速度MOUSEKEY_TIME_TO_MAX30达到最大速度所需时间MOUSEKEY_WHEEL_DELAY10按下滚轮键到滚轮开始转动的延迟MOUSEKEY_WHEEL_INTERVAL80两次滚轮转动之间的时间MOUSEKEY_WHEEL_DELTA1滚轮每次转动步长MOUSEKEY_WHEEL_MAX_SPEED8每次滚动动作的最大滚轮步数MOUSEKEY_WHEEL_TIME_TO_MAX40滚动达到最大速度所需时间调参提示源自文档与实现一致MOUSEKEY_DELAY太小会让光标反应迟钝太大则难以做微小移动。源码中该值以 10ms 为粒度编译quantum/mousekey.c#L68 中mk_delay MOUSEKEY_DELAY / 10因此取 10 的整数倍最合理。想要更平滑可降低MOUSEKEY_INTERVAL。若屏幕刷新率为 60Hz可设为161/60 秒这会显著提升速度通常应同时下调MOUSEKEY_MAX_SPEED。将MOUSEKEY_TIME_TO_MAX或MOUSEKEY_WHEEL_TIME_TO_MAX设为0可分别禁用光标或滚轮的加速——这能让你让一方恒定、另一方加速而纯 Constant 模式做不到。MOUSEKEY_WHEEL_INTERVAL太低会让滚动过快太高则长按滚轮键时过慢。MS_ACL0、MS_ACL1、MS_ACL2分别把光标和滚动速度锁定为最大速度的 1/4、1/2 和最大值实现在 quantum/mousekey.c#L97-L102 的move_unit()中通过mousekey_accel位掩码选择。加速算法本身采用与 X Window System MouseKeys 相同的公式文档注明可查 Wikipedia “Mouse keys” 词条speed delta * max_speed * (repeat / time_to_max)。对应源码 quantum/mousekey.c#L95-L111static uint8_t move_unit(void) { uint16_t unit; if (mousekey_accel (1 0)) { unit (MOUSEKEY_MOVE_DELTA * mk_max_speed) / 4; } else if (mousekey_accel (1 1)) { unit (MOUSEKEY_MOVE_DELTA * mk_max_speed) / 2; } else if (mousekey_accel (1 2)) { unit (MOUSEKEY_MOVE_DELTA * mk_max_speed); } else if (mousekey_repeat 0) { unit MOUSEKEY_MOVE_DELTA; } else if (mousekey_repeat mk_time_to_max) { unit MOUSEKEY_MOVE_DELTA * mk_max_speed; } else { unit (MOUSEKEY_MOVE_DELTA * mk_max_speed * mousekey_repeat) / mk_time_to_max; } return (unit MOUSEKEY_MOVE_MAX ? MOUSEKEY_MOVE_MAX : (unit 0 ? 1 : unit)); }即速度随重复事件计数mousekey_repeat线性增长直到MK_TIME_TO_MAX后恒定于DELTA × MAX_SPEED并钳制在MOUSEKEY_MOVE_MAX默认 127见 quantum/mousekey.h#L26-L30之内。所有模式的共同点mousekey_task()在固件主循环中被周期性调用quantum/keyboard.c#L767按键按下/抬起则经由mousekey_on()/mousekey_off()更新报告。另一个值得注意的细节斜向移动如同时按住MS_UP和MS_LEFT会把两轴各乘以1/√2用整数近似 181/256 实现见 quantum/mousekey.c#L27-L38保证对角线速度与水平/垂直速度一致。Kinetic 模式二次加速曲线Kinetic 是 Accelerated 的扩展光标速度沿二次曲线增长起步段速度低适合精准定位之后迅速拉升以覆盖长距离。在config.h中启用并调参DefineDefaultDescriptionMK_KINETIC_SPEEDundefined启用 Kinetic 模式MOUSEKEY_DELAY5按下移动键到光标移动的延迟MOUSEKEY_INTERVAL10两次光标移动之间的时间msMOUSEKEY_MOVE_DELTA16从初始速度加速到基础速度的步长MOUSEKEY_INITIAL_SPEED100光标初始速度像素/秒MOUSEKEY_BASE_SPEED5000停止加速的最大光标速度MOUSEKEY_DECELERATED_SPEED400减速档光标速度MOUSEKEY_ACCELERATED_SPEED3000加速档光标速度MOUSEKEY_WHEEL_INITIAL_MOVEMENTS16滚轮初始每秒转动次数MOUSEKEY_WHEEL_BASE_MOVEMENTS32滚轮停止加速的最大转动次数MOUSEKEY_WHEEL_ACCELERATED_MOVEMENTS48滚轮加速档转动次数MOUSEKEY_WHEEL_DECELERATED_MOVEMENTS8滚轮减速档转动次数这些默认值同样来自 quantum/mousekey.h#L98-L121。调参提示流畅度取决于MOUSEKEY_INTERVAL间隔越短越平滑但过低会让光标反应迟钝微控制器足够快时可以更低。例如间隔8ms 意味着每秒发起125次移动若基础速度为1000像素/秒每次移动光标8像素。滚轮实现与光标不同光标一次可以移动多像素但滚轮这样做会顿挫因此滚轮始终以步长1输出调速方式是调整“每秒转动次数”而非单步大小。源码印证了文档描述的二次曲线quantum/mousekey.c#L180-L220/* * Kinetic movement acceleration algorithm * * current speed I A * T/50 A * (T/50)^2 * 1/2 | maximum B * * T: time since the mouse movement started * I: initial speed at time 0 * A: acceleration * B: base mouse travel speed */其中T按 50ms 为时间片累计最终速度换算成 USB 鼠标报告的 1–127 范围。MS_ACL0/MS_ACL2分别直接切到MOUSEKEY_DECELERATED_SPEED和MOUSEKEY_ACCELERATED_SPEED。Constant 模式多档恒定速度与两种选择方式Constant 模式为光标和滚轮分别定义多档固定速度无加速MS_ACL0、MS_ACL1、MS_ACL2分别切换到对应档位。速度选择有两种语义Momentary瞬时选中的速度仅在该键按住期间生效松键后回到未修饰速度。Tap-to-select点选保持按下即切换松键后保持默认速度即MS_ACL1档不存在“未修饰速度”。默认速度从慢到快MomentaryMS_ACL0MS_ACL1未修饰MS_ACL2Tap-to-selectMS_ACL0MS_ACL1MS_ACL2启用方式写入config.h#define MK_3_SPEED若使用 Momentary 语义再定义#define MK_MOMENTARY_ACCEL参数表默认值对照 quantum/mousekey.h#L125-L173DefineDefaultDescriptionMK_3_SPEEDNot defined启用恒定光标速度MK_MOMENTARY_ACCELNot defined启用瞬时速度选择MK_C_OFFSET_UNMOD16光标每次移动偏移未修饰档MK_C_INTERVAL_UNMOD16光标移动间隔未修饰档MK_C_OFFSET_01光标每次移动偏移MS_ACL0MK_C_INTERVAL_032光标移动间隔MS_ACL0MK_C_OFFSET_14光标每次移动偏移MS_ACL1MK_C_INTERVAL_116光标移动间隔MS_ACL1MK_C_OFFSET_232光标每次移动偏移MS_ACL2MK_C_INTERVAL_216光标移动间隔MS_ACL2MK_W_OFFSET_UNMOD1每次滚动动作的滚轮步数未修饰档MK_W_INTERVAL_UNMOD40滚轮步间隔未修饰档MK_W_OFFSET_01每次滚动动作的滚轮步数MS_ACL0MK_W_INTERVAL_0360滚轮步间隔MS_ACL0MK_W_OFFSET_11每次滚动动作的滚轮步数MS_ACL1MK_W_INTERVAL_1120滚轮步间隔MS_ACL1MK_W_OFFSET_21每次滚动动作的滚轮步数MS_ACL2MK_W_INTERVAL_220滚轮步间隔MS_ACL2实现上Constant 模式维护四档未修饰 三档的c_offsets[]/c_intervals[]与w_offsets[]/w_intervals[]表quantum/mousekey.c#L503-L515mousekey_on()按下MS_ACLx时切换mk_speed并调用adjust_speed()重标定当前报告量MK_MOMENTARY_ACCEL未定义时初始档位为mkspd_1定义后初始与恢复档位均为mkspd_unmodquantum/mousekey.c#L504-L509与文档的两种语义描述一一对应。Combined 模式加速与恒定速度叠加Combined 模式与Accelerated完全相同区别在于按住MS_ACL0、MS_ACL1、MS_ACL2期间光标与滚动速度会瞬时锁定为恒定值MS_ACL0锁定到最慢速度适合细小、精确定位的移动MS_ACL1锁定到用户定义最大速度的一半MS_ACL2锁定到最大速度适合大范围粗移动。未按住任何加速键时本模式与 Accelerated 无异所有 Accelerated 参数照常生效。启用#define MK_COMBINED对应实现 quantum/mousekey.c#L247-L281 中move_unit()的三个分支加速位 0 → 步长 1位 1 → 半速位 2 → 直接MOUSEKEY_MOVE_MAX其余情况走标准线性加速。Inertia 模式冰面滑行般的松键减速Inertia 模式提供“在冰面上滑行”般的运动手感按键期间光标沿二次曲线加速松键后惯性滑行并逐渐减速停止。垂直与水平速度独立跟踪因此可以同时按住多键做出任意方向的曲线轨迹。注意Inertia 不能与 Kinetic、Constant、Combined 同时使用源码中它们处于互斥的条件编译分支quantum/mousekey.c#L89-L94。推荐配置config.hDefineDefaultDescriptionMOUSEKEY_INERTIAundefined启用 Inertia 模式MOUSEKEY_DELAY150按下移动键到光标移动的延迟MOUSEKEY_INTERVAL16两次光标移动之间的时间16 60fpsMOUSEKEY_MAX_SPEED32停止加速的最大光标速度MOUSEKEY_TIME_TO_MAX32达到最大速度的帧数MOUSEKEY_FRICTION24松键后光标停止的快慢MOUSEKEY_MOVE_DELTA1首帧移动量强烈建议保持 1默认值见 quantum/mousekey.h#L50-L96MOUSEKEY_DELAY150、MOUSEKEY_INTERVAL16、MOUSEKEY_FRICTION24 等均为 Inertia 专属默认。调参提示MOUSEKEY_DELAY建议接近宿主系统的按键重复延迟推荐 100–300msMOUSEKEY_INTERVAL设为 1000 / 显示器帧率如 60FPS 对应 16MOUSEKEY_MAX_SPEED按屏幕宽度 / 帧率估算如 1920px / 60FPS ≈ 32 像素/帧MOUSEKEY_TIME_TO_MAX取约 FPS/2使光标在约半秒内达到全速MOUSEKEY_FRICTION取 1–255值越小滑行越久8–40 之间效果最明显MOUSEKEY_MOVE_DELTA保持 1保证滑行效应启动前仍可做精准移动滚轮参数沿用默认 Accelerated 模式滚轮不走惯性逻辑。实现上每帧由calc_inertia()更新各轴速度方向停止或反向时按velocity × (256 − FRICTION) / 256衰减quantum/mousekey.c#L287-L303方向键按住时速度向 ±MK_TIME_TO_MAX逐帧逼近位移则由二次曲线percent (inertia/time_to_max)² × max_speed计算quantum/mousekey.c#L113-L156。这解释了为什么“按住多键能走曲线”——X/Y 惯性各自独立互不干扰。重叠按键控制MOUSEKEY_OVERLAP_RESET当在移动过程中再按下另一个重叠的移动键时指针默认会带着现有加速度继续转向新方向。若希望新按键触发加速度重置、获得更精准的转向控制可启用以下定义DefineDefaultDescriptionMOUSEKEY_OVERLAP_RESETundefined启用重叠按键的加速度重置MOUSEKEY_OVERLAP_MOVE_DELTAMOUSEKEY_MOVE_DELTA重置后移动加速度的步长MOUSEKEY_OVERLAP_WHEEL_DELTAMOUSEKEY_WHEEL_DELTA重置后滚轮加速度的步长MOUSEKEY_OVERLAP_INTERVALMOUSEKEY_INTERVAL重置后光标移动间隔仅 Kinetic 模式对应逻辑在 quantum/mousekey.c#L395-L406mousekey_on()检测到“已有非零运动报告时又按下一个移动键”即重置mousekey_repeat计数。文档明确提示该特性在 Inertia 模式下不生效——源码条件编译defined(MOUSEKEY_OVERLAP_RESET) !defined(MOUSEKEY_INERTIA)与此一致。与 PS/2 鼠标及指向设备的报告合并Mouse Keys 的按键状态与 PS/2 鼠标 和 指向设备 共享同一份鼠标报告report_mouse_t因此MS_BTN1–MS_BTN8的按下/释放可以直接用于点击和拖拽与物理鼠标传感器驱动的光标移动叠加在同一设备上。对使用板载光学传感器POINTING_DEVICE_ENABLE或 PS/2 鼠标转接器的键盘这意味着鼠标键码补充了硬件鼠标不具备的多按键能力。小结如何为不同场景选模式通用打字间隙快速点击Accelerated默认按文档 Tips 微调MOUSEKEY_INTERVAL/MOUSEKEY_MAX_SPEED需要长距离疾速移动且起步要准KineticMK_KINETIC_SPEED注意MOUSEKEY_INTERVAL决定流畅度需要稳定可预期的三档速度如绘图/剪辑场景ConstantMK_3_SPEED可选MK_MOMENTARY_ACCEL既想保留加速手感、又想在按住快捷键时临时降速精调CombinedMK_COMBINED追求“滑停”手感与多方向曲线运动InertiaMOUSEKEY_INERTIA滚轮保持默认加速行为。所有参数均可在 keymap 的config.h覆盖 quantum/mousekey.h 中的默认值重新编译生效开启MOUSEKEY_ENABLE yes后固件即以上位机识别的 HID 复合设备键盘 鼠标上线指针移动、滚轮与按键行为完全由键码映射驱动。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考