# Switchar

**Repository Path**: zivelin/switchar

## Basic Information

- **Project Name**: Switchar
- **Description**: MAC OS 窗口切换工具
- **Primary Language**: Swift
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 沙窗 (Switchar) - macOS 窗口管理器

一个轻量级的 macOS 窗口管理应用，提供快捷的窗口切换和布局管理功能。

## 功能特性

### 1. 窗口选择器

支持两种模式获取窗口列表：

#### 标准模式（右 Option）
按住 **右 Option** 键激活窗口选择器，使用 AXUIElement 获取窗口（与 Dock 的"显示所有窗口"行为一致）。

**特点：**
- 只显示可聚焦的窗口
- 过滤浮动面板和系统窗口
- 最小化窗口可自动恢复

#### CG 模式（右 Command）
按住 **右 Command** 键激活窗口选择器，使用 CGWindowList 获取窗口。

**特点：**
- 显示所有可见窗口，包括全屏应用
- 可访问 AXUIElement 无法获取的窗口（如 Ghostty、某些 Electron 应用）
- 包含其他桌面/Space的窗口

**导航按键（两种模式通用）：**
- **W / S** - 在应用间上下切换
- **A / D** - 在同一应用的不同窗口间切换
- **ESC** - 取消选择

**注意：**
- 选择器弹出时，W/S/A/D 按键会被拦截，不会输入到当前应用
- 显示应用图标和窗口标题

### 2. 窗口布局
通过状态栏菜单或快捷键调整窗口布局：

| 快捷键 | 功能 |
|--------|------|
| ⌃⌘F | 全屏 |
| ⌃⌘← | 左半屏 |
| ⌃⌘→ | 右半屏 |
| ⌃⌘↑ | 上半屏 |
| ⌃⌘↓ | 下半屏 |

*⌃ = Control, ⌘ = Command*

### 3. 状态栏菜单
点击菜单栏图标可访问：
- 窗口布局子菜单
- 检查辅助功能权限
- 使用帮助
- 设置（待实现）
- 退出应用

## 安装与运行

### 方式一：直接运行（推荐开发测试）

```bash
# 1. 生成 Xcode 项目
xcodegen generate

# 2. 构建应用
xcodebuild -project Switchar.xcodeproj -scheme Switchar -configuration Debug build

# 3. 运行应用
open ~/Library/Developer/Xcode/DerivedData/Switchar-*/Build/Products/Debug/Switchar.app
```

### 方式二：命令行调试运行

```bash
~/Library/Developer/Xcode/DerivedData/Switchar-*/Build/Products/Debug/Switchar.app/Contents/MacOS/Switchar
```

## 首次使用

1. 启动应用后，系统会提示需要**辅助功能权限**
2. 前往 **系统设置 → 隐私与安全性 → 辅助功能**
3. 添加并勾选 **Switchar** 应用
4. 重新启动应用

## 系统要求

- macOS 12.0+
- 需要辅助功能权限（用于全局键盘监听和窗口控制）

## 技术架构

- **CGEvent Tap** - 全局键盘事件监听
- **AXUIElement** - 窗口控制和辅助功能
- **Combine** - 响应式状态管理
- **Swift 5.9**

## 项目结构

```
Sources/
├── App/
│   ├── AppDelegate.swift          # 应用入口，服务初始化
│   └── main.swift                 # main 入口
├── Services/
│   └── EventTapService.swift      # 全局键盘事件监听
├── Core/
│   ├── Selector/
│   │   ├── WindowSelectorService.swift  # 窗口选择逻辑
│   │   ├── WindowSelectorPanel.swift    # 选择器面板 UI
│   │   └── WindowSelectorView.swift     # 视图渲染
│   ├── Window/
│   │   └── WindowManager.swift          # 窗口枚举和焦点控制
│   └── Layout/
│       └── LayoutEngine.swift           # 窗口布局引擎
└── UI/
    └── StatusBar/
        └── StatusBarController.swift    # 状态栏菜单
```

## 已知问题

1. 某些键盘可能需要使用 **Option** 键代替 FN 键
2. 部分 Electron 应用（如 Slack、VS Code）的窗口标题匹配可能不准确
3. 某些应用（如飞书）在最小化后可能无法通过标准模式（右 Option）显示，请使用 CG 模式（右 Command）访问

## 贡献

欢迎提交 Issue 和 Pull Request。

## 许可证

MIT License