VSCode 插件 api 中文翻译

目的

学习VSCode插件开发流程，熟悉插件api具体功能

流程

暂时介绍一个大概，vscode插件通过package.json配置识别，暂时先不翻译这部分。

api

原文链接

介绍：

VS Code API 是一套 JavaScript API，您可以在 Visual Studio Code 扩展中调用它们。此页列出了所有 VS Code API 让开发插件的人去使用。

authentication (认证)

• onDidChangeSessions: Event<AuthenticationSessionsChangeEvent>
  • 在添加、删除或更改身份验证时触发的事件，提供程序的身份验证会话。
  • 简单来说，用户信息更改（增删改查）时会触发，包括登录。
• getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & {createIfNone: true}): Thenable<AuthenticationSession>
  • 获取与所需作用域匹配的身份验证会话。
  • 如果在vscode中写插件可能需要登录时这个插件才会启动，需要用到。
• registerAuthenticationProvider(id: string, label: string, provider: AuthenticationProvider, options?: AuthenticationProviderOptions): DisposableRegister an authentication provider.
  • 注册一个提供者（开发插件人）身份。

commands

package.json里面的配置，也可以用函数注册：

commands.registerCommand('extension.sayHello', () => {
  window.showInformationMessage('Hello World!');
});

• executeCommand(command: string, ...rest: any[]): Thenable<T>

  • 通过给定的命令标识符去执行命令标识。

• getCommands(filterInternal?: boolean): Thenable<string[]>

  • 检索所有可用命令的 list。

• registerCommand(command: string, callback: (args: any[]) => any, thisArg?: any): Disposable

  • 注册键盘快捷键、菜单项、操作或直接调用的命令

• registerTextEditorCommand(command: string, callback: (textEditor: TextEditor, edit: TextEditorEdit, args: any[]) => void, thisArg?: any): Disposable

  • 注册键盘快捷键、菜单项、操作或直接调用的文本编辑器命令。

comments

• createCommentController(id: string, label: string): CommentController
  • 创建一个新的注释控制器实例。

debug

VARIABLES

• activeDebugConsole: DebugConsole
  • 当前处于活动状态的调试控制台。
• breakpoints: readonly Breakpoint[]
  • 断点列表

EVENTS

• onDidChangeActiveDebugSession: Event<DebugSession | undefined>
  • 在活动调试会话发生更改时触发的事件。
  • 注意，当活动调试会话更改为未定义时，也会触发该事件。
• onDidChangeBreakpoints: Event<BreakpointsChangeEvent>
  • 增、删、改断点时触发该事件。
• onDidReceiveDebugSessionCustomEvent: Event<DebugSessionCustomEvent>
  • 调试器被接受一个自定义DAP事件时触发
• onDidStartDebugSession: Event<DebugSession>
  • 新调试会话被启动时触发
• onDidTerminateDebugSession: Event<DebugSession>
  • 一个debug会话被终止时启动

FUNCTIONS

• addBreakpoints(breakpoints: readonly Breakpoint[]): void
  • 添加断点
• asDebugSourceUri(source: DebugProtocolSource, session?: DebugSession): Uri
  • 将通过调试适配器协议接收的“源”描述符对象转换为可用于加载其内容的 Uri。
• registerDebugAdapterDescriptorFactory(debugType: string, factory: DebugAdapterDescriptorFactory): Disposable
  • 为一个特定的调试类型注册一个调试适配器解释器工厂
• registerDebugAdapterTrackerFactory(debugType: string, factory: DebugAdapterTrackerFactory): Disposable
  • 为指定的调试类型注册调试适配器跟踪器工厂。
• registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider, triggerKind?: DebugConfigurationProviderTriggerKind): Disposable
  • 开发人为了一个特定的debug类型注册一个debug配置
• removeBreakpoints(breakpoints: readonly Breakpoint[]): void
  • 删除断点
• startDebugging(folder: WorkspaceFolder, nameOrConfiguration: string | DebugConfiguration, parentSessionOrOptions?: DebugSession | DebugSessionOptions): Thenable<boolean>
  • 启动调试，通过使用命名启动 或 命名复合配置 或 直接传递调试配置。
• stopDebugging(session?: DebugSession): Thenable<void>
  • 停止指定的调试或者停止所有调试

env

描述编辑器运行环境的命名空间。

VARIABLES - 变量

• appHost: [string
  • 应用程序的托管位置在桌面上
• appName: string
  • 编辑器的应用程序名称，如“VS Code”。
• appRoot: string
  • 从中运行编辑器的应用程序根文件夹。
• clipboard: Clipboard
  • 系统剪贴板。
• isNewAppInstall: boolean
  • 表明这是一个全新安装的应用程序
• isTelemetryEnabled: boolean
  • 表明用户是否遥控启用
• language: string
  • 表示首选用户语言，如 de-CH、fr 或 en-US。
• machineId: string
  • 计算机唯一的标识符
• remoteName: string | undefined
  • 远程数据库名称
• sessionId: string
  • 当前会话的唯一标识符
• shell: string
  • 扩展host(主机)默认shell(壳子)被发现
• uiKind: UIKind
  • UI 种类， 表明来自于哪个UI扩展被访问
• uriScheme: string
  • 编辑器注册在正在运行的系统中，定制的uri方案

EVENTS - 事件

• onDidChangeTelemetryEnabled: Event<boolean>
  • 当用户启用或者禁用遥测时触发该事件 FUNCTIONS - 功能
• asExternalUri(target: Uri): Thenable<Uri>
  • 解析一个 uri 到表单展现为可以从外部访问的窗体
• openExternal(target: Uri): Thenable<boolean>
  • 用默认程序打开一个外部的链接

extensions

时间有限，暂不翻译

l10n

时间有限，暂不翻译

languages

用来参与特定语言编辑器的功能（如：智能感知、代码操作、诊断等）

许多编辑器语言存在巨大的不同，在语法、语义和规范。尽管如此，自动完成单词，代码导航，或者代码检查，这些已经在不同编程语言的不同工具里流行了。

编辑器提供了API，根据返回的位置信息等信息进行指定API调用，可以实现悬停、代码提示、替换等操作。（这段不是原文，意思是这个意思）

APi时间有限，暂不翻译，回头补上。这部分很重要。

• registerCompletionItemProvider(selector: DocumentSelector, provider: CompletionItemProvider<CompletionItem>, ...triggerCharacters: string[]): Disposable *

notebooks

笔记本相关的，时间有限，暂不翻译

scm

tasks

tests

任务功能

window

编辑器处理当前window的详细命名空间。
时间有限，暂不翻译

workspace

处理当前工作区的命名空间。工作区是在编辑器窗口中打开一个或者多个文件夹集合。

也可能在没有工作区的情况下打开一个编辑器。

VARIABLES

• fs: FileSystem
  • 文件系统实例，允许本地和远程文件交互
• isTrusted: boolean
  • 如果是 true 表明用户信任工作区内容
• name: string | undefined
  • 工作区名称，没定义时没打开工作区
• notebookDocuments: readonly NotebookDocument
  • 编辑器当前知道的所有笔记本文档
• rootPath: string | undefined
  • 作为字符串的工作区文件夹的第一个条目的 uri。如果没有第一个条目，则未定义。
• textDocuments: readonly TextDocument[]
  • 编辑者当前已知的所有文本文档。
• workspaceFile: Uri | undefined
  • 工作区文件的位置: 绝对路径
• workspaceFolders: readonly WorkspaceFolder[] | undefined
  • 在编辑器中打开的工作区文件夹 （0-N） 的列表。

EVENTS

• onDidChangeConfiguration: Event<ConfigurationChangeEvent>
  • 当配置更改时触发的事件。
• onDidChangeNotebookDocument: Event<NotebookDocumentChangeEvent>
  • 笔记本更改时触发的事件。
• onDidChangeTextDocument: Event<TextDocumentChangeEvent>
  • 更改文本文档时触发的事件。
• onDidChangeWorkspaceFolders: Event<WorkspaceFoldersChangeEvent>
  • 添加或删除工作区文件夹时触发的事件。
• onDidCloseNotebookDocument: Event<NotebookDocument>
  • 释放笔记本时触发的事件。
• onDidCloseTextDocument: Event<TextDocument>
  • 释放文本文档或更改文本文档的语言 ID 时触发的事件。
• onDidCreateFiles: Event<FileCreateEvent>
  • 创建文件时发出的事件。
• onDidDeleteFiles: Event<FileDeleteEvent>
  • 删除文件时发出的事件。
• onDidGrantWorkspaceTrust: Event<void>
  • 当前工作区受信任时触发的事件。
• onDidOpenNotebookDocument: Event<NotebookDocument>
  • 打开笔记本时发出的事件。
• onDidOpenTextDocument: Event<[TextDocument](code.visualstudio.com/api/referen…
  • 打开文本文档或更改文本文档的语言 ID 时发出的事件。
• onDidRenameFiles: Event<FileRenameEvent>
  • 重命名文件时发出的事件。
• onDidSaveNotebookDocument: Event<NotebookDocument>
  • 保存笔记本时发出的事件。
• onDidSaveTextDocument: Event<TextDocument>
  • 将文本文档保存到磁盘时发出的事件。
• onWillCreateFiles: Event<FileWillCreateEvent>
  • 创建文件时发出的事件。
• onWillDeleteFiles: Event<FileWillDeleteEvent>
  • 删除文件时触发的事件
• onWillRenameFiles: Event<FileWillRenameEvent>
  • 重命名文件时触发的事件
• onWillSaveTextDocument: Event<TextDocumentWillSaveEvent>
  • 将文本文档保存到磁盘时发出的事件。

FUNCTIONS

• applyEdit(edit: WorkspaceEdit, metadata?: WorkspaceEditMetadata): Thenable<boolean>
  • 对一个或多个资源进行更改，或者创建、删除和重命名给定工作区编辑定义的资源。
• asRelativePath(pathOrUri: string | Uri, includeWorkspaceFolder?: boolean): string
  • 返回相对于一个或多个工作区文件夹的路径。
• createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher
  • 创建一个文件系统观察者，该观察者根据提供的参数在文件事件（创建、更改、删除）时收到通知。
• findFiles(include: GlobPattern, exclude?: GlobPattern, maxResults?: number, token?: CancellationToken): Thenable<Uri[]>
  • 在工作区中对所有工作区文件夹中查找文件。
• getConfiguration(section?: string, scope?: ConfigurationScope): WorkspaceConfiguration
  • 获取工作区配置对象。
• getWorkspaceFolder(uri: Uri): WorkspaceFolder | undefined
  • 返回包含给定 URI 的工作区文件夹。
• openNotebookDocument(uri: Uri): Thenable<NotebookDocument>
  • 打开一个笔记本文档
• openNotebookDocument(notebookType: string, content?: NotebookData): Thenable<NotebookDocument>
  • 打开无标题笔记本。保存文档时，编辑器将提示用户输入文件路径。
• openTextDocument(uri: Uri): Thenable<TextDocument>
  • 打开文档。如果此文档已打开，将提前返回。
• openTextDocument(fileName: string): Thenable<TextDocument>
  • openTextDocument 的简写。
• openTextDocument(options?: {content: string, language: string}): Thenable<TextDocument>
  • 打开无标题的文本文档。
• registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options?: {isCaseSensitive: boolean, isReadonly: boolean}): Disposable
  • 为给定方案注册文件系统提供程序，例如 ftp。
• registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions): Disposable
  • 注册笔记本序列化程序。
• registerTextDocumentContentProvider(scheme: string, provider: TextDocumentContentProvider): Disposable
  • 注册文本文档内容提供程序。
• saveAll(includeUntitled?: boolean): Thenable<boolean>
  • 保存所有的脏文件。
• updateWorkspaceFolders(start: number, deleteCount: number, ...workspaceFoldersToAdd: {name: string, uri: Uri}[]): boolean
  • 此方法将 deleteCount 从索引开始的工作区文件夹替换为一组可选的 workspaceFolderToAdd 在 vscode.workspace.workspaceFolder 数组上。

总结

暂时先翻译到这里，如有新的学习陆续也会补充进去，学习到之后会把代码例子放进去。