Ice核心功能解析：菜单栏项管理与隐藏机制

本文深入解析了macOS菜单栏管理工具Ice的核心功能实现机制。文章详细介绍了Ice的三段式菜单栏项分类系统（可见/隐藏/始终隐藏），基于AXSwift的无障碍API菜单栏项检测技术，拖拽排序与布局管理的实现原理，以及智能化的自动重隐藏策略与触发条件。通过技术架构图、代码示例和系统流程图，全面展现了Ice如何实现对macOS菜单栏的精细化管理。

菜单栏项的三段式分类管理（可见/隐藏/始终隐藏）

Ice作为macOS菜单栏管理工具，其核心功能之一就是通过三段式分类系统对菜单栏项进行精细化管理。这种分类机制不仅提供了直观的用户界面，还实现了强大的隐藏和显示控制逻辑。

分类体系架构

Ice将菜单栏项划分为三个明确的分类，每个分类都有其特定的用途和行为模式：

enum Name: CaseIterable {
    case visible      // 可见区域 - 始终显示的菜单项
    case hidden       // 隐藏区域 - 可临时显示的菜单项  
    case alwaysHidden // 始终隐藏区域 - 永不显示的菜单项
}

这种分类体系通过MenuBarSection.Name枚举定义，每个分类都有对应的显示字符串和日志字符串，便于用户界面展示和调试。

分类管理的数据结构

Ice使用专门的数据结构来管理不同分类的菜单栏项：

struct ItemCache: Hashable {
    private var items = [MenuBarSection.Name: [MenuBarItem]]()
    
    var allItems: [MenuBarItem] {
        MenuBarSection.Name.allCases.reduce(into: []) { result, section in
            result.append(contentsOf: self[section])
        }
    }
    
    var managedItems: [MenuBarItem] {
        MenuBarSection.Name.allCases.reduce(into: []) { result, section in
            result.append(contentsOf: managedItems(for: section))
        }
    }
}

这种设计允许Ice高效地按分类存储和检索菜单栏项，同时提供对整个菜单栏项的聚合视图。

分类判定逻辑

Ice使用谓词系统来确定每个菜单栏项所属的分类：

flowchart TD
    A[菜单栏项输入] --> B{是否为临时显示项?}
    B -->|是| C[按返回目的地分类]
    B -->|否| D{应用分类谓词}
    D --> E[可见区域]
    D --> F[隐藏区域]
    D --> G[始终隐藏区域]
    D --> H[未分类项]

分类判定过程基于控制项的位置和特定的空间关系：

private func uncheckedCacheItems(
    hiddenControlItem: MenuBarItem,
    alwaysHiddenControlItem: MenuBarItem?,
    otherItems: [MenuBarItem]
) {
    let predicates = Predicates.sectionPredicates(
        hiddenControlItem: hiddenControlItem,
        alwaysHiddenControlItem: alwaysHiddenControlItem
    )
    
    for item in otherItems {
        if predicates.isInVisibleSection(item) {
            cache[.visible].append(item)
        } else if predicates.isInHiddenSection(item) {
            cache[.hidden].append(item)
        } else if predicates.isInAlwaysHiddenSection(item) {
            cache[.alwaysHidden].append(item)
        }
    }
}

各分类的行为特性

可见区域 (Visible Section)

• 默认状态: 始终显示
• 控制逻辑: 不受隐藏操作影响
• 典型用途: 系统核心功能、常用应用图标

隐藏区域 (Hidden Section)

• 默认状态: 隐藏
• 触发显示: 鼠标悬停、点击空白区域、滚动操作
• 自动重隐藏: 支持定时自动重新隐藏
• 典型用途: 不常用但需要偶尔访问的应用

始终隐藏区域 (Always-Hidden Section)

• 默认状态: 永久隐藏
• 显示条件: 需要用户主动触发特殊操作
• 无自动显示: 不会因常规交互而显示
• 典型用途: 调试工具、后台服务、极少使用的应用

分类间的交互关系

三个分类之间存在复杂的交互逻辑，特别是在显示和隐藏操作时：

sequenceDiagram
    participant User
    participant Visible
    participant Hidden
    participant AlwaysHidden
    
    User->>Hidden: 显示隐藏区域
    Hidden->>Visible: 同步显示
    Hidden->>AlwaysHidden: 保持隐藏
    
    User->>AlwaysHidden: 显示始终隐藏区域
    AlwaysHidden->>Visible: 同步显示  
    AlwaysHidden->>Hidden: 同步显示
    
    User->>Visible: 隐藏可见区域
    Visible->>Hidden: 同步隐藏
    Visible->>AlwaysHidden: 同步隐藏

技术实现细节

缓存管理

Ice采用智能缓存机制来维护分类信息：

func cacheItemsIfNeeded() {
    guard !isMovingItem && !itemHasRecentlyMoved && !mouseHasRecentlyMoved else {
        logSkippingCache(reason: "item is moving or was recently moved")
        return
    }
    
    let items = MenuBarItem.getMenuBarItems(onScreenOnly: false, activeSpaceOnly: true)
    // 分类和缓存逻辑...
}

临时显示项处理

对于临时显示的菜单项，Ice维护特殊的上下文信息：

private struct TempShownItemContext {
    let info: MenuBarItemInfo
    let returnDestination: MoveDestination
    let shownInterfaceWindow: WindowInfo?
    
    var isShowingInterface: Bool {
        // 复杂的界面显示状态检测逻辑
    }
}

用户界面集成

分类系统与用户界面紧密集成，在设置面板中提供直观的控制：

分类	显示名称	默认状态	可配置选项
Visible	可见	显示	无
Hidden	隐藏	隐藏	自动重隐藏、触发条件
Always-Hidden	始终隐藏	隐藏	特殊访问权限

这种三段式分类管理系统为macOS菜单栏提供了前所未有的组织灵活性，让用户能够根据使用频率和重要性对菜单项进行精细化管理，同时保持了系统的简洁性和易用性。

基于AXSwift的无障碍API菜单栏项检测

Ice项目通过AXSwift框架实现了强大的菜单栏项检测功能，这是整个应用的核心基础。AXSwift是macOS无障碍API的Swift封装，为菜单栏管理提供了实时、精确的窗口信息获取能力。

核心检测机制

Ice使用多层次的检测策略来识别和管理菜单栏项：

1. 窗口层级检测

通过Core Graphics的私有API CGSGetProcessMenuBarWindowList 获取所有菜单栏项的窗口ID：

private static func getMenuBarWindowList() -> [CGWindowID] {
    let windowCount = getWindowCount()
    var list = [CGWindowID](repeating: 0, count: windowCount)
    var realCount: Int32 = 0
    let result = CGSGetProcessMenuBarWindowList(
        CGSMainConnectionID(),
        0,
        Int32(windowCount),
        &list,
        &realCount
    )
    guard result == .success else {
        Logger.bridging.error("CGSGetProcessMenuBarWindowList failed with error \(result.logString)")
        return []
    }
    return [CGWindowID](list[..<Int(realCount)])
}

2. 菜单栏项识别逻辑

每个菜单栏项通过 WindowInfo 结构体进行封装，包含完整的窗口信息：

struct WindowInfo {
    let windowID: CGWindowID
    let frame: CGRect
    let title: String?
    let layer: Int
    let alpha: Double
    let ownerPID: pid_t
    let ownerName: String?
    let isOnScreen: Bool
    let isBackedByVideoMemory: Bool
    
    var isMenuBarItem: Bool {
        layer == kCGStatusWindowLevel
    }
}

3. 菜单栏窗口验证

使用AXSwift验证菜单栏窗口的有效性：

func hasValidMenuBar(in windows: [WindowInfo], for display: CGDirectDisplayID) -> Bool {
    guard let menuBarWindow = WindowInfo.getMenuBarWindow(from: windows, for: display) else {
        return false
    }
    let position = menuBarWindow.frame.origin
    do {
        let uiElement = try systemWideElement.elementAtPosition(Float(position.x), Float(position.y))
        return try uiElement?.role() == .menuBar
    } catch {
        return false
    }
}

菜单栏项获取流程

Ice的菜单栏项检测遵循一个清晰的流程：

flowchart TD
    A[开始检测] --> B[获取窗口列表]
    B --> C[过滤菜单栏项窗口]
    C --> D[创建WindowInfo对象]
    D --> E[验证菜单栏项有效性]
    E --> F[封装为MenuBarItem]
    F --> G[分类到相应区域]
    G --> H[更新缓存]
    H --> I[完成检测]

权限管理与无障碍访问

Ice需要无障碍权限才能正常工作，通过 AccessibilityPermission 类管理：

final class AccessibilityPermission: Permission {
    init() {
        super.init(
            title: "Accessibility",
            details: [
                "Get real-time information about the menu bar.",
                "Arrange menu bar items.",
            ],
            isRequired: true,
            settingsURL: nil,
            check: {
                checkIsProcessTrusted()
            },
            request: {
                checkIsProcessTrusted(prompt: true)
            }
        )
    }
}

实时监控与更新机制

Ice实现了高效的实时监控系统：

定时检测

每5秒自动检测菜单栏项变化：

Timer.publish(every: 5, on: .main, in: .default)
    .autoconnect()
    .merge(with: Just(.now))
    .sink { [weak self] _ in
        guard let self else { return }
        Task { await self.cacheItemsIfNeeded() }
    }

应用状态监听

监控应用程序启动和退出：

NSWorkspace.shared.publisher(for: \.runningApplications)
    .delay(for: 0.25, scheduler: DispatchQueue.main)
    .sink { [weak self] _ in
        guard let self else { return }
        Task { await self.cacheItemsIfNeeded() }
    }

菜单栏项分类策略

Ice使用智能分类算法将菜单栏项分配到不同的区域：

区域类型	检测条件	处理方式
可见区域	frame.minX >= hiddenControlItem.frame.maxX	正常显示
隐藏区域	frame.maxX <= hiddenControlItem.frame.minX	可隐藏显示
始终隐藏区域	frame.maxX <= alwaysHiddenControlItem.frame.minX	完全隐藏

技术挑战与解决方案

1. 窗口层级识别

通过 kCGStatusWindowLevel 常量准确识别菜单栏项窗口层级，避免误判其他系统窗口。

2. 多显示器支持

使用 CGDirectDisplayID 参数支持多显示器环境下的菜单栏项检测：

static func getMenuBarItems(on display: CGDirectDisplayID? = nil, 
                           onScreenOnly: Bool, 
                           activeSpaceOnly: Bool) -> [MenuBarItem] {
    // 多显示器处理逻辑
}

3. 实时性能优化

采用懒加载和缓存机制减少不必要的窗口查询，确保界面流畅性。

错误处理与日志记录

完善的错误处理机制确保检测过程的稳定性：

do {
    let uiElement = try systemWideElement.elementAtPosition(Float(position.x), Float(position.y))
    return try uiElement?.role() == .menuBar
} catch {
    Logger.menuBarManager.error("AXSwift accessibility check failed: \(error)")
    return false
}

总结

Ice基于AXSwift的无障碍API菜单栏项检测机制展现了macOS系统级编程的精妙之处。通过结合Core Graphics底层API和AXSwift无障碍框架，实现了高效、准确的菜单栏项识别和管理。这种多层次、实时监控的架构设计为菜单栏自定义工具提供了坚实的技术基础，确保了应用的稳定性和用户体验的流畅性。

拖拽排序与布局管理实现原理

Ice的拖拽排序功能是其菜单栏管理的核心特性之一，它允许用户通过直观的拖放操作来重新排列菜单栏项的位置。这一功能的实现涉及多个层次的协作，从用户界面交互到底层的系统事件处理，展现了macOS应用程序开发的复杂性和精妙性。

核心架构设计

Ice的拖拽排序系统采用分层架构设计，主要包含以下几个核心组件：

组件名称	职责描述	关键技术
LayoutBar	布局栏容器视图	SwiftUI NSViewRepresentable
LayoutBarScrollView	滚动视图容器	NSScrollView 子类化
LayoutBarPaddingView	拖拽处理视图	NSDraggingDestination 协议
LayoutBarContainer	项布局管理器	NSView 自动布局
LayoutBarItemView	菜单栏项视图	NSDraggingSource 协议

flowchart TD
    A[用户拖拽操作] --> B[LayoutBarItemView<br>开始拖拽会话]
    B --> C[LayoutBarPaddingView<br>处理拖拽事件]
    C --> D{判断拖拽位置}
    D -->|在目标项左侧| E[移动到目标项左边]
    D -->|在目标项右侧| F[移动到目标项右边]
    E --> G[MenuBarItemManager<br>执行实际移动]
    F --> G
    G --> H[更新布局缓存]
    H --> I[刷新界面显示]

拖拽事件处理流程

拖拽排序的实现基于macOS的NSDraggingSource和NSDraggingDestination协议，整个处理流程如下：

1. 拖拽开始阶段：当用户在LayoutBarItemView上按下鼠标并拖动时，会触发mouseDragged(with:)方法，创建NSDraggingSession。

2. 拖拽进行阶段：拖拽过程中，LayoutBarPaddingView作为拖拽目标接收以下事件：

   • draggingEntered(_:) - 拖拽进入视图
   • draggingUpdated(_:) - 拖拽位置更新
   • draggingExited(_:) - 拖拽退出视图

3. 拖拽结束阶段：当用户释放鼠标时，调用performDragOperation(_:)方法执行实际的菜单栏项移动操作。

布局管理算法

LayoutBarContainer负责管理菜单栏项的布局排列，其核心算法包括：

private func layoutArrangedViews(oldViews: [LayoutBarItemView]? = nil) {
    // 移除不再属于排列视图的旧视图
    for view in oldViews where !arrangedViews.contains(view) {
        view.removeFromSuperview()
        view.hasContainer = false
    }
    
    // 计算最大高度用于垂直居中
    let maxHeight = arrangedViews.lazy
        .map { $0.bounds.height }
        .max() ?? 0
    
    // 按顺序排列视图
    var previous: NSView?
    for var view in arrangedViews {
        if subviews.contains(view) {
            // 已有视图，可能位置发生变化
            view = view.animator() // 启用动画效果
        } else {
            // 新添加的视图
            addSubview(view)
            view.hasContainer = true
        }
        
        // 设置视图位置
        view.setFrameOrigin(
            CGPoint(
                x: previous.map { $0.frame.maxX + spacing } ?? 0,
                y: (maxHeight / 2) - view.bounds.midY
            )
        )
        previous = view
    }
}

菜单栏项移动机制

实际的菜单栏项移动由MenuBarItemManager负责，通过模拟鼠标事件来实现：

func move(item: MenuBarItem, to destination: MoveDestination) async throws {
    // 检查是否已在正确位置
    if try itemHasCorrectPosition(item: item, for: destination) {
        return
    }
    
    // 等待修饰键释放和鼠标停止移动
    try await waitForNoModifiersPressed()
    try await waitForMouseToStopMoving()
    
    // 隐藏鼠标光标并保存当前位置
    MouseCursor.hide()
    defer {
        MouseCursor.warp(to: cursorLocation)
        MouseCursor.show()
    }
    
    // 最多重试5次移动操作
    for n in 1...5 {
        do {
            try await moveItemWithoutRestoringMouseLocation(item, to: destination)
            if let newFrame = getCurrentFrame(for: item), newFrame != initialFrame {
                break // 移动成功
            }
        } catch where n < 5 {
            try await wakeUpItem(item) // 唤醒无响应的项
            continue // 重试
        }
    }
}

坐标计算与位置判断

移动操作的核心是精确计算目标位置：

private func getEndPoint(for destination: MoveDestination) throws -> CGPoint {
    switch destination {
    case .leftOfItem(let targetItem):
        guard let currentFrame = getCurrentFrame(for: targetItem) else {
            throw EventError(code: .invalidItem, item: targetItem)
        }
        return CGPoint(x: currentFrame.minX, y: currentFrame.midY)
    case .rightOfItem(let targetItem):
        guard let currentFrame = getCurrentFrame(for: targetItem) else {
            throw EventError(code: .invalidItem, item: targetItem)
        }
        return CGPoint(x: currentFrame.maxX, y: currentFrame.midY)
    }
}

拖拽过程中的视觉反馈

为了提供良好的用户体验，Ice实现了多种视觉反馈机制：

1. 拖拽占位符：当项被拖拽时，显示半透明的占位符图像
2. 动画效果：使用NSView的animator()代理实现平滑的位置过渡
3. 禁用状态指示：对于不可移动的项显示禁用图标和警告提示
4. 无响应项标识：对于无响应的应用程序项显示警告标志

错误处理与恢复机制

考虑到菜单栏项移动可能失败的各种情况，Ice实现了完善的错误处理：

sequenceDiagram
    participant User
    participant LayoutBar
    participant MenuBarManager
    participant System

    User->>LayoutBar: 开始拖拽