Windows x64 鼠标侧键与横向滚轮映射工具,使用 Rust 编写,带原生配置窗口、组合键录入和常用动作预设。后台托盘运行,保存配置后立即生效,无需 Python 环境。
当前适配和日常使用的设备是 SANWA 人体工学鼠标,支持两个侧键以及滚轮左右倾斜产生的横向滚动事件。
具体型号尚未确认。 当前 Windows 设备信息仅提供通用 HID / 无线接收器描述,没有可确认的 SANWA 产品型号,因此这里不标注未经核实的型号。可通过鼠标底部铭牌、包装或购买记录确认。
本项目按 Windows 标准鼠标事件工作,没有绑定某个品牌或 USB 设备编号。其他能产生 XButton1、XButton2、横向滚轮事件的鼠标可能适用,但尚未逐一验证;不保证覆盖 SANWA 全系列。当前不支持区分多只鼠标分别配置,也不提供 DPI、灯光、蓝牙配对或固件设置。
这是个人工具项目,与 SANWA 官方无隶属关系。
- 配置两个侧键、横向滚轮左拨和右拨,共 4 项映射。
- 直接录入单键或最多 8 个键的组合,包括
Ctrl+Shift+W和A+S。 - 常用动作:后退、前进、刷新、关闭标签页、音量和媒体播放控制。
- 可保留鼠标原行为或禁用指定按键;保存后立即生效。
- 托盘设置入口、单实例运行、配置检查、诊断日志和可选开机启动。
源码仓库不包含生成的 dist 和 target,首次使用请按下文“编译与验证”构建。构建完成后,双击 dist/SideKey Rust.lnk 打开配置窗口,或运行 dist/sidekey.exe 进入后台。
如使用便携发布包,解压后运行 SideKey Settings.cmd 打开设置,或运行 sidekey.exe 后双击托盘图标。
如果此前使用 Python 版 sanwa.py,请先通过它的托盘菜单退出。不要同时运行两个映射器。Rust 版只允许一个实例,重复打开快捷方式会显示已有实例的配置窗口。
- 双击快捷方式,或双击托盘图标;托盘右键菜单也有“映射设置…”。
- 找到后侧键、前侧键、滚轮向左或滚轮向右。在这一行的“动作 / 常用功能”下拉框选择“后退”“前进”等,不需要录制;自定义组合键则点击“录入”。
- 在键盘上按下需要一起发送的键,全部松开后完成。例如
Ctrl+Shift+W、A+S、Ctrl+A+S,最多 8 个键。录入期间的按键会被拦截,Esc取消;切换到其他窗口也会取消。 - 点击“保存并应用”,写入配置文件并立即生效,无需重启。保存失败时保留原文件和当前生效的映射。
每行也可选择“保留原行为”或“禁用”。关闭窗口会放弃未保存的修改,程序继续在托盘运行;再次打开显示当前生效的配置。配置窗口获得焦点时不执行鼠标映射。此版本提供同时按下的键盘组合,不提供带延时的多步宏;录入保留键 Esc 可通过 JSON 手动配置为映射目标。Windows 保留的安全组合(例如 Ctrl+Alt+Delete)不能作为普通组合键录入或发送。
“动作 / 常用功能”提供:后退、前进、刷新页面(F5)、关闭标签页(Ctrl+W)、音量增加、音量减小、静音 / 取消静音、播放 / 暂停、上一曲、下一曲、停止播放。已有映射会自动选中对应的常用功能,并显示中文名称。选择后仍需点击“保存并应用”。后退、前进适用于浏览器、Windows 文件资源管理器等支持导航的应用;“后退”不是“返回上级文件夹”。
dist/config.json 默认映射:
| 输入 | 动作 |
|---|---|
| 靠后侧键 XButton1 | Ctrl+W |
| 靠前侧键 XButton2 | Ctrl+R |
| 横向滚轮左拨 | 后退 |
| 横向滚轮右拨 | 前进 |
配置动作支持 default(原始事件通过)、disabled(禁用)、组合键,如 ctrl+shift+w 或 ctrl+a+s。支持 Ctrl/Shift/Alt/Win、左右修饰键、字母数字、F1–F24、导航键、媒体键、音量键和浏览器键。录入的标点和小键盘等按键可使用 vkXX 十六进制虚拟键名保存。未知字段或键名会明确报错,不会带着错误配置运行。直接手动修改 JSON 后需要退出再启动;在界面保存则立即生效。
程序总是从 EXE 所在目录读取默认配置、图标并写入 sidekey.log;不依赖快捷方式的起始目录。日志采用 JSON 行格式,记录启动、退出、错误和 panic;超过 2 MB 后保留一个 .1 备份。正常模式不记录普通键盘内容。
命令参数:
# 打开设置;已运行时显示已有实例的窗口。
Start-Process .\dist\sidekey.exe -ArgumentList '--settings' -WindowStyle Hidden
# 检查配置,不安装钩子;结果写入日志,退出码 0 表示通过。
$p = Start-Process .\dist\sidekey.exe -ArgumentList '--check-config' -Wait -PassThru -WindowStyle Hidden
$p.ExitCode
# 只监听,不拦截;键盘/鼠标事件写入日志。
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start.ps1 -Listen
# 正常启动,启动脚本会检测原 Python 映射器。
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start.ps1
# 正常退出 Rust 版。
Start-Process .\dist\sidekey.exe -ArgumentList '--quit' -Wait -WindowStyle Hidden也支持 --config PATH、--log PATH,相对路径以 EXE 所在目录为基准。日志无法创建时会显示启动错误;配置文件必须存在。
需要 Rustup 和 MinGW-w64 GCC,确保 gcc、windres 在 PATH 中(例如 MSYS2 的 mingw64/bin 目录)。项目配置使用 GNU 工具链,不需要 Visual Studio。当前验证使用 Rust 1.88.0:
rustup toolchain install 1.88.0-x86_64-pc-windows-gnu --profile minimal --component rustfmt --component clippy
cargo +1.88.0-x86_64-pc-windows-gnu fmt --check
cargo +1.88.0-x86_64-pc-windows-gnu test --lib --bins --locked
cargo +1.88.0-x86_64-pc-windows-gnu clippy --all-targets --locked -- -D warnings
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build.ps1构建脚本在 dist 内生成可执行文件和快捷方式,复制图标,首次复制默认配置;之后构建保留你编辑过的 dist/config.json。依赖版本锁定在 Cargo.lock。
重复验证可运行 powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify.ps1。加上 -LiveInput 会运行发布版真实输入测试:测试先安装保护钩子,再启动使用 F13–F16 的子进程,拦截测试鼠标事件及生成的按键,避免传递到原 Python 映射器或其他应用。运行前先退出已有 Rust 实例,测试期间避免操作侧键。测试日志保留在 docs/smoke-logs。
确认 Rust 版工作正常后,手动执行:
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\startup.ps1 -Action Install这会先备份当前用户注册表中的 sanwa 启动项,然后替换为 Rust EXE。不会结束已经运行的 Python 版,也不改原开始菜单快捷方式。撤销并恢复原启动项:
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\startup.ps1 -Action Uninstall安装和撤销脚本只有主动执行才会改注册表;如果启动项已被其他操作更改,撤销会拒绝覆盖。
配置在启动时预先校验;钩子回调不写文件、不等待工作线程;有界队列避免无限积压。队列满时原始鼠标事件通过。已按住的修饰键不会被程序主动松开。若焦点在动作排队期间变更,动作会跳过,避免对新的窗口发送关闭/刷新快捷键。
托盘在 Explorer 重启后重建,钩子在系统唤醒、会话解锁后重新安装。Windows 仍可能移除超时钩子;本实现减少阻塞,不承诺在所有系统负载下永远不失效。映射到管理员程序时,SideKey 需要匹配的权限;程序默认不会请求提权。
短时测试不能证明长期稳定性。出现异常可检查 EXE 同目录的 sidekey.log;开启监听模式会记录按键事件,分享日志前请先检查其中的内容。