14.9 菜单栏图标

macOS伴侣应用macOS伴侣应用

菜单栏图标通过视觉状态反馈 OpenClaw 应用的实时工作状态。

概述

菜单栏图标是用户与 OpenClaw 交互的主要视觉入口。图标会根据智能体的活动状态动态变化,包括图标样式、动画效果和色调,让用户一目了然地了解应用状态。

图标状态

状态类型

enum IconState {
  case idle                       // 空闲
  case workingMain(ActivityKind)  // 主会话工作中
  case workingOther(ActivityKind) // 其他会话工作中
  case overridden(ActivityKind)   // 调试覆盖状态
}

活动类型

enum ActivityKind {
  case exec      // 执行命令
  case read      // 读取文件
  case write     // 写入文件
  case edit      // 编辑文件
  case attach    // 附加资源
  case other     // 其他操作
}

视觉效果

状态映射

状态 图标 动画 色调
idle 静态龙虾 无 正常
workingMain(exec) 💻 脉冲 完整
workingMain(read) 📄 脉冲 完整
workingMain(write) ✍️ 脉冲 完整
workingMain(edit) 📝 脉冲 完整
workingMain(attach) 📎 脉冲 完整
workingOther(*) 对应图标 无 柔和

色调说明

  • 完整色调: 使用系统强调色,图标鲜明
  • 柔和色调: 降低饱和度和亮度,图标柔和
  • 正常色调: 系统默认菜单栏颜色

动画效果

  • 脉冲动画: 图标周期性缩放(0.9x - 1.0x)
  • 持续时间: 1.5 秒循环
  • 缓动函数: ease-in-out
  • 仅主会话: 只有主会话工作时显示动画

状态优先级

优先级规则

  1. Main 会话: 最高优先级,始终显示主会话状态
  2. Other 会话: 无主会话活动时显示
  3. 健康状态: 所有会话空闲时显示
  4. Idle 状态: 默认状态

会话判定

// 通过 sessionKey 判定主会话
if sessionKey == "main" {
  // 使用 workingMain 状态
} else {
  // 使用 workingOther 状态
}

事件驱动

状态更新来源

图标状态通过控制通道的 agent 流更新:

  • job 事件: 任务执行状态变化
  • tool 事件: 工具调用阶段变化

活动识别

系统通过解析 args.command 或文件路径确定活动类型:

// 命令类型识别
if command.contains("bash") || command.contains("sh") {
  activityKind = .exec
}

// 文件操作识别
if path.endsWith(".swift") || path.endsWith(".ts") {
  if operation == "read" {
    activityKind = .read
  } else if operation == "write" {
    activityKind = .write
  }
}

调试功能

图标覆盖

开发时可以通过 @AppStorage 覆盖图标状态:

// 设置覆盖状态
@AppStorage("iconOverride") var iconOverride: String?

// 使用示例
iconOverride = "workingMain.exec"  // 强制显示执行状态

测试要点

  • 状态切换稳定性: 状态变化无抖动
  • 无闪烁: 图标更新平滑过渡
  • 正确降级: 优先级处理正确
  • 动画性能: 动画流畅不卡顿

自定义配置

动画配置

{
  "menuIcon": {
    "animation": {
      "enabled": true,
      "duration": 1.5,
      "scale": [0.9, 1.0],
      "easing": "ease-in-out"
    }
  }
}

显示配置

{
  "menuIcon": {
    "display": {
      "showActivityGlyph": true,
      "showAnimation": true,
      "prioritizeMain": true,
      "colorMode": "auto"
    }
  }
}

辅助功能

VoiceOver 支持

  • 图标状态的语音描述
  • 活动类型的无障碍标签
  • 状态变化的提示音

高对比度模式

  • 自动调整图标对比度
  • 增强色调区分度
  • 保持可读性

最佳实践

设计原则

  • 保持图标简洁清晰
  • 使用直观的活动图标
  • 确保动画不影响性能
  • 适配浅色/深色模式
  • 提供辅助功能支持

性能考虑

  • 限制动画帧率
  • 使用系统原生动画 API
  • 避免过于复杂的图标
  • 缓存图标资源
相关资源