Trae 学习指南

中文

English
日本語

中文

English
日本語

Appearance

API 参考 ​

欢迎使用 Trae IDE API 参考文档。本文档提供了完整的 API 接口说明，帮助您开发强大的 Trae IDE 扩展。

API 概述 ​

Trae IDE API 提供了丰富的接口，让您能够：n- 创建和管理扩展

  • 操作编辑器和文档
  • 利用 AI 功能
  • 自定义用户界面
  • 访问工作区和文件系统
  • 集成开发工具

API 分类 ​

核心 API ​

编辑器 API ​

文本编辑器操作、文档管理、选择和光标控制。

typescript
// 获取当前活动编辑器
const editor = TraeAPI.window.activeTextEditor;
if (editor) {
  // 插入文本
  editor.edit(editBuilder => {
    editBuilder.insert(editor.selection.active, 'Hello, World!');
  });
}

扩展 API ​

扩展生命周期、命令注册、UI 贡献、配置管理。

typescript
// 注册命令
const disposable = TraeAPI.commands.registerCommand('myExtension.hello', () => {
  TraeAPI.window.showInformationMessage('你好，世界！');
});
context.subscriptions.push(disposable);

AI 与智能功能 ​

AI API ​

人工智能代码生成、分析、聊天助手、智能补全。

typescript
// AI 代码生成
const response = await TraeAPI.ai.generateCode({
  prompt: '创建一个计算阶乘的函数',
  language: 'typescript'
});
console.log('生成的代码:', response.code);

开发工具 ​

调试 API ​

调试会话管理、断点控制、变量检查。

typescript
// 启动调试会话
const config = {
  type: 'node',
  request: 'launch',
  name: '启动程序',
  program: '${workspaceFolder}/app.js'
};
TraeAPI.debug.startDebugging(undefined, config);

任务 API ​

任务定义、执行、监控。

typescript
// 执行任务
const task = new TraeAPI.Task(
  { type: 'shell' },
  TraeAPI.TaskScope.Workspace,
  '构建项目',
  'npm',
  new TraeAPI.ShellExecution('npm run build')
);
TraeAPI.tasks.executeTask(task);

扩展与插件 ​

语言服务 API ​

语言支持、语法高亮、智能感知、代码操作。

typescript
// 注册悬停提供程序
TraeAPI.languages.registerHoverProvider('typescript', {
  provideHover(document, position) {
    const range = document.getWordRangeAtPosition(position);
    if (range) {
      const word = document.getText(range);
      return new TraeAPI.Hover(`关于 ${word} 的信息`);
    }
  }
});

主题 API ​

颜色主题、图标主题、自定义样式。

typescript
// 获取当前主题
const theme = TraeAPI.window.activeColorTheme;
console.log('当前主题类型:', theme.kind);

快速开始 ​

创建第一个扩展 ​

  1. 初始化扩展项目
bash
# 使用 Trae CLI 创建扩展
trae-cli create-extension my-first-extension
cd my-first-extension
  1. 扩展清单文件 (package.json)
json
{
  "name": "my-first-extension",
  "displayName": "我的第一个扩展",
  "description": "一个示例扩展",
  "version": "1.0.0",
  "publisher": "your-publisher",
  "engines": {
    "trae": "^1.0.0"
  },
  "categories": ["其他"],
  "activationEvents": [
    "onCommand:myExtension.helloWorld"
  ],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "myExtension.helloWorld",
        "title": "你好世界"
      }
    ]
  }
}
  1. 扩展入口文件 (src/extension.ts)
typescript
import * as TraeAPI from '@trae/api';

export function activate(context: TraeAPI.ExtensionContext) {
  console.log('扩展 "my-first-extension" 已激活！');
  
  const disposable = TraeAPI.commands.registerCommand(
    'myExtension.helloWorld',
    () => {
      TraeAPI.window.showInformationMessage('你好，来自我的扩展！');
    }
  );
  
  context.subscriptions.push(disposable);
}

export function deactivate() {
  console.log('扩展已停用');
}
  1. TypeScript 配置 (tsconfig.json)
json
{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2020",
    "outDir": "out",
    "lib": ["ES2020"],
    "sourceMap": true,
    "rootDir": "src",
    "strict": true
  },
  "exclude": ["node_modules", ".trae-test"]
}
  1. 构建和测试
bash
# 安装依赖
npm install

# 编译 TypeScript
npm run compile

# 在开发模式下测试扩展
F5 # 或使用调试面板

认证 ​

API 密钥管理 ​

typescript
// 存储 API 密钥
const secrets = context.secrets;
await secrets.store('apiKey', 'your-secret-key');

// 获取 API 密钥
const apiKey = await secrets.get('apiKey');

// 删除 API 密钥
await secrets.delete('apiKey');

用户认证 ​

typescript
// 获取用户信息
const user = await TraeAPI.authentication.getSession('github');
if (user) {
  console.log('用户已登录:', user.account.label);
} else {
  // 请求用户登录
  const session = await TraeAPI.authentication.getSession('github', [], {
    createIfNone: true
  });
}

错误处理 ​

常见错误类型 ​

typescript
try {
  await TraeAPI.commands.executeCommand('nonexistent.command');
} catch (error) {
  if (error instanceof TraeAPI.CommandNotFoundError) {
    TraeAPI.window.showErrorMessage('命令未找到');
  } else if (error instanceof TraeAPI.PermissionError) {
    TraeAPI.window.showErrorMessage('权限不足');
  } else {
    TraeAPI.window.showErrorMessage(`未知错误: ${error.message}`);
  }
}

错误报告 ​

typescript
// 报告错误到遥测
TraeAPI.telemetry.sendErrorTelemetry('extensionError', {
  errorMessage: error.message,
  stackTrace: error.stack,
  extensionId: context.extension.id
});

事件系统 ​

监听系统事件 ​

typescript
// 监听文件变化
TraeAPI.workspace.onDidChangeTextDocument(event => {
  console.log('文档已更改:', event.document.fileName);
});

// 监听活动编辑器变化
TraeAPI.window.onDidChangeActiveTextEditor(editor => {
  if (editor) {
    console.log('活动编辑器已更改:', editor.document.fileName);
  }
});

// 监听配置变化
TraeAPI.workspace.onDidChangeConfiguration(event => {
  if (event.affectsConfiguration('myExtension')) {
    console.log('扩展配置已更改');
  }
});

自定义事件 ​

typescript
// 创建事件发射器
const onDataChanged = new TraeAPI.EventEmitter<string>();
export const onDataChangedEvent = onDataChanged.event;

// 触发事件
function updateData(newData: string) {
  // 更新数据逻辑
  onDataChanged.fire(newData);
}

// 监听自定义事件
onDataChangedEvent(data => {
  console.log('数据已更新:', data);
});

配置 ​

扩展配置 ​

typescript
// 在 package.json 中定义配置
{
  "contributes": {
    "configuration": {
      "title": "我的扩展",
      "properties": {
        "myExtension.enable": {
          "type": "boolean",
          "default": true,
          "description": "启用我的扩展"
        },
        "myExtension.maxItems": {
          "type": "number",
          "default": 10,
          "minimum": 1,
          "maximum": 100,
          "description": "最大项目数"
        }
      }
    }
  }
}

// 读取配置
const config = TraeAPI.workspace.getConfiguration('myExtension');
const isEnabled = config.get<boolean>('enable', true);
const maxItems = config.get<number>('maxItems', 10);

// 更新配置
await config.update('maxItems', 20, TraeAPI.ConfigurationTarget.Global);

工作区配置 ​

typescript
// 读取工作区设置
const workspaceConfig = TraeAPI.workspace.getConfiguration();
const editorFontSize = workspaceConfig.get('editor.fontSize');
const editorTabSize = workspaceConfig.get('editor.tabSize');

// 获取工作区文件夹
const workspaceFolders = TraeAPI.workspace.workspaceFolders;
if (workspaceFolders && workspaceFolders.length > 0) {
  console.log('工作区根目录:', workspaceFolders[0].uri.fsPath);
}

测试 ​

单元测试 ​

typescript
// test/suite/extension.test.ts
import * as assert from 'assert';
import * as TraeAPI from '@trae/api';

suite('扩展测试套件', () => {
  test('扩展应该存在', () => {
    assert.ok(TraeAPI.extensions.getExtension('publisher.my-extension'));
  });
  
  test('应该注册命令', async () => {
    const commands = await TraeAPI.commands.getCommands();
    assert.ok(commands.includes('myExtension.helloWorld'));
  });
});

集成测试 ​

typescript
// test/suite/integration.test.ts
import * as assert from 'assert';
import * as TraeAPI from '@trae/api';
import * as path from 'path';

suite('集成测试套件', () => {
  test('应该打开文档', async () => {
    const uri = TraeAPI.Uri.file(path.join(__dirname, '../../test-fixtures/test.ts'));
    const document = await TraeAPI.workspace.openTextDocument(uri);
    assert.ok(document);
    assert.strictEqual(document.languageId, 'typescript');
  });
});

发布 ​

打包扩展 ​

bash
# 安装 Trae CLI
npm install -g @trae/cli

# 打包扩展
trae-cli package

# 发布到市场
trae-cli publish

版本管理 ​

json
{
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./",
    "package": "trae-cli package",
    "publish": "trae-cli publish"
  }
}

最佳实践 ​

性能优化 ​

  1. 延迟加载

    typescript
    // 延迟加载重型依赖
async function loadHeavyDependency() {
  const { heavyModule } = await import('./heavy-module');
  return heavyModule;
}

  2. 适当的激活事件

    json
    {
  "activationEvents": [
    "onLanguage:typescript",  // 仅在打开 TypeScript 文件时激活
    "onCommand:myExtension.specificCommand"  // 仅在执行特定命令时激活
  ]
}

  3. 资源清理

    typescript
    export function activate(context: TraeAPI.ExtensionContext) {
  const disposable = TraeAPI.workspace.onDidChangeTextDocument(() => {
    // 处理文档变化
  });
  
  // 确保在扩展停用时清理资源
  context.subscriptions.push(disposable);
}

用户体验 ​

  1. 提供进度指示

    typescript
    TraeAPI.window.withProgress({
  location: TraeAPI.ProgressLocation.Notification,
  title: '正在处理...',
  cancellable: true
}, async (progress, token) => {
  for (let i = 0; i < 100; i++) {
    if (token.isCancellationRequested) {
      break;
    }
    progress.report({ increment: 1, message: `步骤 ${i + 1}/100` });
    await new Promise(resolve => setTimeout(resolve, 100));
  }
});

  2. 错误处理和用户反馈

    typescript
    try {
  await performOperation();
  TraeAPI.window.showInformationMessage('操作成功完成！');
} catch (error) {
  TraeAPI.window.showErrorMessage(`操作失败: ${error.message}`);
}

安全性 ​

  1. 输入验证

    typescript
    function validateInput(input: string): boolean {
  // 验证用户输入
  return /^[a-zA-Z0-9_-]+$/.test(input);
}

  2. 安全存储

    typescript
    // 使用 SecretStorage 存储敏感信息
await context.secrets.store('apiToken', userToken);

迁移指南 ​

从 VS Code 扩展迁移 ​

大多数 VS Code 扩展可以直接在 Trae IDE 中运行，只需要少量修改：

  1. 更新 package.json

    json
    {
  "engines": {
    "trae": "^1.0.0"  // 替换 "vscode": "^1.x.x"
  }
}

  2. 更新导入语句

    typescript
    // 旧的
import * as vscode from 'vscode';

// 新的
import * as TraeAPI from '@trae/api';

  3. 利用 Trae 特有功能

    typescript
    // 使用 AI 功能
const aiResponse = await TraeAPI.ai.generateCode({
  prompt: '创建一个 React 组件',
  language: 'typescript'
});

示例 ​

完整的扩展示例 ​

typescript
// src/extension.ts
import * as TraeAPI from '@trae/api';

interface TodoItem {
  id: string;
  text: string;
  completed: boolean;
}

class TodoProvider implements TraeAPI.TreeDataProvider<TodoItem> {
  private _onDidChangeTreeData = new TraeAPI.EventEmitter<TodoItem | undefined | null | void>();
  readonly onDidChangeTreeData = this._onDidChangeTreeData.event;
  
  private todos: TodoItem[] = [];
  
  getTreeItem(element: TodoItem): TraeAPI.TreeItem {
    const item = new TraeAPI.TreeItem(element.text, TraeAPI.TreeItemCollapsibleState.None);
    item.id = element.id;
    item.description = element.completed ? '已完成' : '待完成';
    item.contextValue = element.completed ? 'completedTodo' : 'pendingTodo';
    return item;
  }
  
  getChildren(element?: TodoItem): Thenable<TodoItem[]> {
    return Promise.resolve(this.todos);
  }
  
  addTodo(text: string): void {
    const todo: TodoItem = {
      id: Date.now().toString(),
      text,
      completed: false
    };
    this.todos.push(todo);
    this._onDidChangeTreeData.fire();
  }
  
  toggleTodo(id: string): void {
    const todo = this.todos.find(t => t.id === id);
    if (todo) {
      todo.completed = !todo.completed;
      this._onDidChangeTreeData.fire();
    }
  }
  
  deleteTodo(id: string): void {
    this.todos = this.todos.filter(t => t.id !== id);
    this._onDidChangeTreeData.fire();
  }
}

export function activate(context: TraeAPI.ExtensionContext) {
  const todoProvider = new TodoProvider();
  
  // 注册树视图
  const treeView = TraeAPI.window.createTreeView('todoList', {
    treeDataProvider: todoProvider,
    showCollapseAll: false
  });
  
  // 注册命令
  const commands = [
    TraeAPI.commands.registerCommand('todoExtension.addTodo', async () => {
      const text = await TraeAPI.window.showInputBox({
        prompt: '输入待办事项',
        placeHolder: '例如：完成项目文档'
      });
      if (text) {
        todoProvider.addTodo(text);
      }
    }),
    
    TraeAPI.commands.registerCommand('todoExtension.toggleTodo', (item: TodoItem) => {
      todoProvider.toggleTodo(item.id);
    }),
    
    TraeAPI.commands.registerCommand('todoExtension.deleteTodo', (item: TodoItem) => {
      todoProvider.deleteTodo(item.id);
    })
  ];
  
  // 添加到订阅
  context.subscriptions.push(treeView, ...commands);
  
  // 状态栏项目
  const statusBarItem = TraeAPI.window.createStatusBarItem(
    TraeAPI.StatusBarAlignment.Left,
    100
  );
  statusBarItem.text = '$(checklist) 待办事项';
  statusBarItem.command = 'todoExtension.addTodo';
  statusBarItem.show();
  
  context.subscriptions.push(statusBarItem);
}

export function deactivate() {
  // 清理资源
}

您的终极 AI 驱动 IDE 学习指南

版权所有 © 2025 ykzm.cn