iQuick - macOS 快捷操作工具

iQuick 是一个 macOS 实用工具，通过将滚轮手势映射到屏幕不同区域来触发各种系统操作，提升用户生产力。该应用以菜单栏应用的形式运行，提供加速滚动、音量控制和自定义快捷键等功能。

功能特性

• 加速滚动：在屏幕左/右边缘滚动时，放大滚动速度
• 音量控制：在屏幕左上角滚动，调整系统音量
• 自定义快捷键：在屏幕上边缘滚动，触发自定义键盘快捷键（Cmd+Shift+L / Cmd+Shift+H）
• 可配置设置：可调整滚动倍数、音量步长和滚动方向反转
• 菜单栏集成：系统托盘图标，可访问设置和查看日志

系统要求

• macOS 12.0 或更高版本
• Xcode 14.0+ 或 Swift 6.1+ 命令行工具
• 辅助功能权限（用于事件监控）

编译和运行

前置条件

确保已安装 Xcode 命令行工具：

xcode-select --install

编译项目

# 编译调试版本
swift build

# 编译发布版本
swift build -c release

运行应用

# 运行调试版本
swift run

# 或直接运行编译好的可执行文件
.build/debug/iQuick

创建应用包

# 编译发布版本
swift build -c release

# 创建 macOS app bundle
./make_app.sh

# App bundle 将生成在 iQuick.app
# 可以双击运行或使用 open iQuick.app

使用说明

首次启动

1. 编译并运行应用
2. 系统会提示授予辅助功能权限（系统设置 > 隐私与安全性 > 辅助功能）
3. 授予权限后，应用会在菜单栏显示闪电图标
4. 通过菜单栏图标访问设置

屏幕区域操作

屏幕区域	操作	说明
左上角	音量控制	向上滚动增加音量，向下滚动减少音量
上边缘	自定义快捷键	向上滚动触发 Cmd+Shift+L，向下滚动触发 Cmd+Shift+H
左/右边缘	加速滚动	滚动速度根据设置的倍数放大
其他区域	正常滚动	无特殊效果

设置选项

通过菜单栏图标打开设置，可以调整以下选项：

• 滚动倍数：调整屏幕边缘的滚动放大倍数（2x-30x）
• 音量步长：调整每次滚动的音量变化量（1%-25%）
• 反转滚动：仅对音量控制反转滚动方向

登录时启动

在菜单栏中选择 "Launch at Login" 选项，应用会在登录时自动启动。

日志

调试日志会写入以下位置：

~/Library/Application Support/iQuick/Logs/iQuickDebug.log

日志包含时间戳和详细的事件信息，可用于排查问题。

开发说明

项目结构

Sources/
└── iQuickApp.swift    # 单文件应用，包含所有逻辑

应用采用单文件架构，具有清晰的关注点分离：

• 配置模型（ObservableObject）
• 数据模型和操作执行器
• 全局事件回调
• 应用和代理
• SwiftUI 视图
• 辅助代码（日志、系统音量）

代码规范

• SwiftUI 用于 UI：所有用户界面组件使用 SwiftUI
• MARK 注释：使用 // MARK: 组织代码以便导航
• 类型安全：使用 Swift 枚举实现强类型屏幕区域和操作
• 内存管理：正确使用 Unmanaged 处理 CGEvent
• 并发：MainActor 用于 UI 相关的代理方法，DispatchQueue 用于日志记录

权限处理

• 应用需要辅助功能权限来全局监控滚动事件
• 启动时和打开设置时检查权限状态
• 根据权限状态自动启用/禁用事件监听

故障排除

应用无法监控滚动事件

确保已授予辅助功能权限：

1. 打开系统设置 > 隐私与安全性 > 辅助功能
2. 找到 iQuick 并启用
3. 重启应用

音量控制不工作

检查系统音频输出设备是否正常，查看日志文件获取详细错误信息。

技术栈

• 语言：Swift 6.1
• 框架：SwiftUI, Cocoa, CoreAudio, AudioToolbox
• 平台：macOS 12.0+
• 包管理器：Swift Package Manager (SPM)

许可证

本项目采用 MIT 许可证。

贡献

欢迎提交问题和拉取请求！