Skip to content

About

Windows 鼠标侧键与横向滚轮映射工具;当前适配 SANWA 人体工学鼠标,支持原生设置界面、多键组合和常用动作。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SideKey Rust

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 版只允许一个实例,重复打开快捷方式会显示已有实例的配置窗口。

界面配置

  1. 双击快捷方式,或双击托盘图标;托盘右键菜单也有“映射设置…”。
  2. 找到后侧键、前侧键、滚轮向左或滚轮向右。在这一行的“动作 / 常用功能”下拉框选择“后退”“前进”等,不需要录制;自定义组合键则点击“录入”。
  3. 在键盘上按下需要一起发送的键,全部松开后完成。例如 Ctrl+Shift+W、A+S、Ctrl+A+S,最多 8 个键。录入期间的按键会被拦截,Esc 取消;切换到其他窗口也会取消。
  4. 点击“保存并应用”,写入配置文件并立即生效,无需重启。保存失败时保留原文件和当前生效的映射。

每行也可选择“保留原行为”或“禁用”。关闭窗口会放弃未保存的修改,程序继续在托盘运行;再次打开显示当前生效的配置。配置窗口获得焦点时不执行鼠标映射。此版本提供同时按下的键盘组合,不提供带延时的多步宏;录入保留键 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;开启监听模式会记录按键事件,分享日志前请先检查其中的内容。

About

Windows 鼠标侧键与横向滚轮映射工具;当前适配 SANWA 人体工学鼠标,支持原生设置界面、多键组合和常用动作。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages