配置管理 API

Trae IDE 提供了灵活的配置管理系统，允许用户和扩展自定义编辑器的行为和外观。

概述

配置管理 API 支持：

• 用户设置管理
• 工作区配置
• 扩展配置
• 配置监听和更新

配置层级

Trae IDE 使用分层配置系统：

1. 默认配置 - 系统默认设置
2. 用户配置 - 全局用户设置
3. 工作区配置 - 特定工作区设置
4. 文件夹配置 - 特定文件夹设置

主要接口

Configuration 对象

interface Configuration {
  // 获取配置值
  get<T>(section: string): T | undefined
  get<T>(section: string, defaultValue: T): T
  
  // 检查配置是否存在
  has(section: string): boolean
  
  // 更新配置
  update(section: string, value: any, target?: ConfigurationTarget): Promise<void>
  
  // 获取配置详情
  inspect<T>(section: string): ConfigurationInspect<T> | undefined
}

配置目标

enum ConfigurationTarget {
  Global = 1,      // 全局配置
  Workspace = 2,   // 工作区配置
  WorkspaceFolder = 3  // 工作区文件夹配置
}

基本用法

读取配置

import { workspace } from 'trae-api'

// 获取编辑器配置
const config = workspace.getConfiguration('editor')

// 读取字体大小
const fontSize = config.get<number>('fontSize', 14)

// 读取主题设置
const theme = config.get<string>('theme')

更新配置

// 更新全局配置
await config.update('fontSize', 16, ConfigurationTarget.Global)

// 更新工作区配置
await config.update('tabSize', 2, ConfigurationTarget.Workspace)

检查配置来源

// 检查配置的详细信息
const fontSizeInspect = config.inspect('fontSize')
console.log('默认值:', fontSizeInspect?.defaultValue)
console.log('全局值:', fontSizeInspect?.globalValue)
console.log('工作区值:', fontSizeInspect?.workspaceValue)

配置监听

监听配置变化

import { workspace } from 'trae-api'

// 监听所有配置变化
workspace.onDidChangeConfiguration((event) => {
  if (event.affectsConfiguration('editor.fontSize')) {
    console.log('字体大小已更改')
    updateFontSize()
  }
  
  if (event.affectsConfiguration('editor.theme')) {
    console.log('主题已更改')
    updateTheme()
  }
})

特定配置监听

// 只监听特定配置节的变化
workspace.onDidChangeConfiguration((event) => {
  // 检查是否影响特定配置
  if (event.affectsConfiguration('myExtension')) {
    const newConfig = workspace.getConfiguration('myExtension')
    handleConfigurationChange(newConfig)
  }
}, null, context.subscriptions)

配置架构

定义配置架构

// 在 package.json 中定义配置架构
{
  "contributes": {
    "configuration": {
      "title": "我的扩展",
      "properties": {
        "myExtension.enable": {
          "type": "boolean",
          "default": true,
          "description": "启用我的扩展"
        },
        "myExtension.maxItems": {
          "type": "number",
          "default": 10,
          "minimum": 1,
          "maximum": 100,
          "description": "最大项目数量"
        },
        "myExtension.theme": {
          "type": "string",
          "enum": ["light", "dark", "auto"],
          "default": "auto",
          "description": "主题设置"
        }
      }
    }
  }
}

高级用法

配置验证

function validateConfiguration(config: any): boolean {
  // 验证配置值的有效性
  if (typeof config.maxItems !== 'number' || config.maxItems < 1) {
    return false
  }
  
  if (!['light', 'dark', 'auto'].includes(config.theme)) {
    return false
  }
  
  return true
}

// 使用验证
const config = workspace.getConfiguration('myExtension')
if (!validateConfiguration(config)) {
  console.error('配置无效')
}

配置迁移

// 处理配置版本迁移
function migrateConfiguration() {
  const config = workspace.getConfiguration('myExtension')
  const version = config.get<string>('version', '1.0.0')
  
  if (version === '1.0.0') {
    // 从 1.0.0 迁移到 2.0.0
    const oldSetting = config.get('oldSetting')
    if (oldSetting !== undefined) {
      config.update('newSetting', transformOldSetting(oldSetting))
      config.update('oldSetting', undefined) // 删除旧设置
    }
    config.update('version', '2.0.0')
  }
}

实用示例

动态配置更新

class ConfigurationManager {
  private config: Configuration
  
  constructor() {
    this.config = workspace.getConfiguration('myExtension')
    this.setupConfigurationWatcher()
  }
  
  private setupConfigurationWatcher() {
    workspace.onDidChangeConfiguration((event) => {
      if (event.affectsConfiguration('myExtension')) {
        this.config = workspace.getConfiguration('myExtension')
        this.applyConfiguration()
      }
    })
  }
  
  private applyConfiguration() {
    const enabled = this.config.get<boolean>('enable', true)
    const theme = this.config.get<string>('theme', 'auto')
    
    if (enabled) {
      this.enableFeature()
    } else {
      this.disableFeature()
    }
    
    this.applyTheme(theme)
  }
}

配置备份和恢复

// 备份当前配置
function backupConfiguration(): any {
  const config = workspace.getConfiguration()
  return {
    editor: config.get('editor'),
    workbench: config.get('workbench'),
    extensions: config.get('extensions')
  }
}

// 恢复配置
async function restoreConfiguration(backup: any): Promise<void> {
  const config = workspace.getConfiguration()
  
  for (const [section, value] of Object.entries(backup)) {
    await config.update(section, value, ConfigurationTarget.Global)
  }
}

最佳实践

1. 默认值: 始终为配置项提供合理的默认值
2. 验证: 验证用户输入的配置值
3. 文档: 为每个配置项提供清晰的描述
4. 向后兼容: 处理配置架构的变更和迁移
5. 性能: 避免频繁读取配置，考虑缓存机制

相关 API

• 工作区 API - 工作区管理
• 扩展 API - 扩展开发
• 设置 API - 设置管理