状态栏 API

Trae IDE 的状态栏 API 允许扩展在编辑器底部的状态栏中显示信息和交互元素。

概述

状态栏功能包括：

• 显示文本和图标
• 添加交互按钮
• 显示进度指示器
• 状态信息更新
• 自定义样式和颜色

主要接口

StatusBarItem

interface StatusBarItem {
  // 基本属性
  id: string
  alignment: StatusBarAlignment
  priority?: number
  
  // 显示内容
  text: string
  tooltip?: string | MarkdownString
  color?: string | ThemeColor
  backgroundColor?: ThemeColor
  
  // 交互
  command?: string | Command
  
  // 状态
  accessibilityInformation?: AccessibilityInformation
  
  // 操作方法
  show(): void
  hide(): void
  dispose(): void
}

StatusBarAlignment

enum StatusBarAlignment {
  Left = 1,
  Right = 2
}

创建状态栏项

基本创建

import { window, StatusBarAlignment } from 'trae-api'

// 创建状态栏项
const statusBarItem = window.createStatusBarItem(
  StatusBarAlignment.Right,  // 对齐方式
  100                        // 优先级（数字越大越靠右/左）
)

// 设置文本和图标
statusBarItem.text = '$(sync~spin) 同步中...'
statusBarItem.tooltip = '正在同步文件'

// 显示状态栏项
statusBarItem.show()

带命令的状态栏项

const statusBarItem = window.createStatusBarItem(
  StatusBarAlignment.Left,
  10
)

statusBarItem.text = '$(git-branch) main'
statusBarItem.tooltip = '点击切换分支'
statusBarItem.command = 'git.checkout'

statusBarItem.show()

文本和图标

使用图标

// 使用内置图标
statusBarItem.text = '$(check) 已保存'
statusBarItem.text = '$(error) 错误'
statusBarItem.text = '$(warning) 警告'
statusBarItem.text = '$(info) 信息'

// 组合图标和文本
statusBarItem.text = '$(file-code) TypeScript'
statusBarItem.text = '$(git-branch) main $(sync) 3'

// 旋转图标
statusBarItem.text = '$(sync~spin) 加载中'

动态更新文本

class StatusUpdater {
  private statusBarItem: StatusBarItem
  private timer: NodeJS.Timer | undefined
  
  constructor() {
    this.statusBarItem = window.createStatusBarItem(
      StatusBarAlignment.Right,
      100
    )
    this.statusBarItem.show()
    this.startUpdating()
  }
  
  private startUpdating() {
    this.updateStatus()
    this.timer = setInterval(() => {
      this.updateStatus()
    }, 1000)
  }
  
  private updateStatus() {
    const now = new Date()
    this.statusBarItem.text = `$(clock) ${now.toLocaleTimeString()}`
  }
  
  dispose() {
    if (this.timer) {
      clearInterval(this.timer)
    }
    this.statusBarItem.dispose()
  }
}

颜色和样式

设置颜色

import { ThemeColor } from 'trae-api'

// 使用主题颜色
statusBarItem.color = new ThemeColor('statusBarItem.errorForeground')
statusBarItem.backgroundColor = new ThemeColor('statusBarItem.errorBackground')

// 使用自定义颜色
statusBarItem.color = '#ff0000'  // 红色文本

// 根据状态设置颜色
function updateStatusColor(status: 'success' | 'warning' | 'error') {
  switch (status) {
    case 'success':
      statusBarItem.color = new ThemeColor('statusBarItem.prominentForeground')
      statusBarItem.backgroundColor = new ThemeColor('statusBarItem.prominentBackground')
      break
    case 'warning':
      statusBarItem.color = new ThemeColor('statusBarItem.warningForeground')
      statusBarItem.backgroundColor = new ThemeColor('statusBarItem.warningBackground')
      break
    case 'error':
      statusBarItem.color = new ThemeColor('statusBarItem.errorForeground')
      statusBarItem.backgroundColor = new ThemeColor('statusBarItem.errorBackground')
      break
  }
}

交互功能

命令绑定

// 绑定简单命令
statusBarItem.command = 'workbench.action.showCommands'

// 绑定带参数的命令
statusBarItem.command = {
  command: 'extension.customCommand',
  title: '执行自定义命令',
  arguments: ['参数1', '参数2']
}

工具提示

import { MarkdownString } from 'trae-api'

// 简单文本提示
statusBarItem.tooltip = '点击查看详情'

// Markdown 提示
const tooltip = new MarkdownString()
tooltip.appendMarkdown('**当前状态**: 正常\n\n')
tooltip.appendMarkdown('- 文件: 100\n')
tooltip.appendMarkdown('- 错误: 0\n')
tooltip.appendMarkdown('- 警告: 2\n')
tooltip.appendMarkdown('\n[查看详情](command:extension.showDetails)')

statusBarItem.tooltip = tooltip

实用示例

文件统计显示

class FileStatsStatusBar {
  private statusBarItem: StatusBarItem
  
  constructor() {
    this.statusBarItem = window.createStatusBarItem(
      StatusBarAlignment.Right,
      200
    )
    this.statusBarItem.command = 'extension.showFileStats'
    this.updateStats()
    this.statusBarItem.show()
  }
  
  async updateStats() {
    try {
      const stats = await this.getFileStats()
      this.statusBarItem.text = `$(file-code) ${stats.files} 文件`
      this.statusBarItem.tooltip = this.createTooltip(stats)
      this.statusBarItem.color = undefined // 正常颜色
    } catch (error) {
      this.statusBarItem.text = '$(error) 统计失败'
      this.statusBarItem.color = new ThemeColor('statusBarItem.errorForeground')
    }
  }
  
  private async getFileStats() {
    // 获取文件统计信息
    return {
      files: 150,
      lines: 5000,
      size: '2.5MB'
    }
  }
  
  private createTooltip(stats: any): MarkdownString {
    const tooltip = new MarkdownString()
    tooltip.appendMarkdown(`**项目统计**\n\n`)
    tooltip.appendMarkdown(`- 文件数: ${stats.files}\n`)
    tooltip.appendMarkdown(`- 代码行: ${stats.lines}\n`)
    tooltip.appendMarkdown(`- 总大小: ${stats.size}\n`)
    return tooltip
  }
}

构建状态指示器

class BuildStatusIndicator {
  private statusBarItem: StatusBarItem
  private isBuilding = false
  
  constructor() {
    this.statusBarItem = window.createStatusBarItem(
      StatusBarAlignment.Left,
      50
    )
    this.statusBarItem.command = 'extension.build'
    this.updateStatus('idle')
    this.statusBarItem.show()
  }
  
  startBuild() {
    this.isBuilding = true
    this.updateStatus('building')
    
    // 模拟构建过程
    setTimeout(() => {
      this.isBuilding = false
      this.updateStatus('success')
    }, 5000)
  }
  
  private updateStatus(status: 'idle' | 'building' | 'success' | 'error') {
    switch (status) {
      case 'idle':
        this.statusBarItem.text = '$(tools) 构建'
        this.statusBarItem.tooltip = '点击开始构建'
        this.statusBarItem.color = undefined
        break
        
      case 'building':
        this.statusBarItem.text = '$(sync~spin) 构建中'
        this.statusBarItem.tooltip = '构建进行中...'
        this.statusBarItem.color = new ThemeColor('statusBarItem.prominentForeground')
        break
        
      case 'success':
        this.statusBarItem.text = '$(check) 构建成功'
        this.statusBarItem.tooltip = '构建完成'
        this.statusBarItem.color = '#00ff00'
        
        // 3秒后恢复到空闲状态
        setTimeout(() => {
          if (!this.isBuilding) {
            this.updateStatus('idle')
          }
        }, 3000)
        break
        
      case 'error':
        this.statusBarItem.text = '$(error) 构建失败'
        this.statusBarItem.tooltip = '构建出现错误，点击重试'
        this.statusBarItem.color = new ThemeColor('statusBarItem.errorForeground')
        break
    }
  }
}

网络状态监控

class NetworkStatusMonitor {
  private statusBarItem: StatusBarItem
  private isOnline = true
  
  constructor() {
    this.statusBarItem = window.createStatusBarItem(
      StatusBarAlignment.Right,
      300
    )
    
    this.setupNetworkMonitoring()
    this.updateStatus()
    this.statusBarItem.show()
  }
  
  private setupNetworkMonitoring() {
    // 监听网络状态变化
    setInterval(() => {
      this.checkNetworkStatus()
    }, 5000)
  }
  
  private async checkNetworkStatus() {
    try {
      // 简单的网络检查
      const response = await fetch('https://api.github.com', {
        method: 'HEAD',
        mode: 'no-cors'
      })
      this.isOnline = true
    } catch (error) {
      this.isOnline = false
    }
    
    this.updateStatus()
  }
  
  private updateStatus() {
    if (this.isOnline) {
      this.statusBarItem.text = '$(globe) 在线'
      this.statusBarItem.tooltip = '网络连接正常'
      this.statusBarItem.color = undefined
    } else {
      this.statusBarItem.text = '$(globe) 离线'
      this.statusBarItem.tooltip = '网络连接断开'
      this.statusBarItem.color = new ThemeColor('statusBarItem.errorForeground')
    }
  }
}

进度指示

简单进度显示

class ProgressIndicator {
  private statusBarItem: StatusBarItem
  private progress = 0
  
  constructor() {
    this.statusBarItem = window.createStatusBarItem(
      StatusBarAlignment.Left,
      100
    )
  }
  
  showProgress(total: number) {
    this.progress = 0
    this.statusBarItem.show()
    this.updateProgress(total)
  }
  
  updateProgress(total: number) {
    const percentage = Math.round((this.progress / total) * 100)
    const progressBar = this.createProgressBar(percentage)
    
    this.statusBarItem.text = `${progressBar} ${percentage}%`
    this.statusBarItem.tooltip = `进度: ${this.progress}/${total}`
    
    if (this.progress >= total) {
      setTimeout(() => {
        this.statusBarItem.hide()
      }, 2000)
    }
  }
  
  private createProgressBar(percentage: number): string {
    const filled = Math.round(percentage / 10)
    const empty = 10 - filled
    return '█'.repeat(filled) + '░'.repeat(empty)
  }
  
  increment() {
    this.progress++
  }
}

最佳实践

1. 优先级设置: 合理设置优先级，避免重要信息被遮挡
2. 性能优化: 避免频繁更新状态栏，使用防抖或节流
3. 用户体验: 提供清晰的图标和有意义的提示信息
4. 资源清理: 在扩展停用时正确清理状态栏项
5. 响应式设计: 考虑不同屏幕尺寸下的显示效果

相关 API

• 窗口 API - 窗口管理
• 命令 API - 命令系统
• 主题 API - 主题和颜色