VS Code API
VS Code API 是一组 JavaScript API,你可以在 Visual Studio Code 扩展中调用它们。此页面列出了扩展作者可用的所有 VS Code API。
API 命名空间和类
此列表编译自 VS Code 仓库中的 vscode.d.ts 文件。
身份验证
事件
onDidChangeSessions: Event<AuthenticationSessionsChangeEvent>
当身份验证提供程序的身份验证会话被添加、删除或更改时触发的 事件。
函数
getAccounts(providerId: string): Thenable<readonly AuthenticationSessionAccountInformation[]>
获取用户为指定提供程序登录的所有帐户。将其与 getSession 配对使用,以便获取特定帐户的身份验证会话。
目前,只有两个身份验证提供程序是由编辑器的内置扩展贡献的,它们实现了 GitHub 和 Microsoft 身份验证:它们的 providerId 分别是 'github' 和 'microsoft'。
注意:获取帐户并不意味着你的扩展有权访问该帐户或其身份验证会话。你可以通过调用 getSession 来验证对帐户的访问权限。
参数 | 描述 |
---|---|
providerId: string | 要使用的提供程序的 ID |
返回值 | 描述 |
Thenable<readonly AuthenticationSessionAccountInformation[]> | 一个 thenable,它解析为身份验证帐户的只读数组。 |
getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & {createIfNone: true | AuthenticationGetSessionPresentationOptions}): Thenable<AuthenticationSession>
获取与所需 scopes 匹配的身份验证会话。如果未注册 providerId 的提供程序,或者用户不同意与扩展共享身份验证信息,则拒绝。如果存在具有相同 scopes 的多个会话,则会向用户显示一个快速选择列表,以选择他们想要使用的帐户。
目前,只有两个身份验证提供程序是由编辑器的内置扩展贡献的,它们实现了 GitHub 和 Microsoft 身份验证:它们的 providerId 分别是 'github' 和 'microsoft'。
参数 | 描述 |
---|---|
providerId: string | 要使用的提供程序的 ID |
scopes: readonly string[] | 表示请求的权限的 scopes 列表。这些 scopes 取决于身份验证提供程序 |
options: AuthenticationGetSessionOptions & {createIfNone: true | AuthenticationGetSessionPresentationOptions} | |
返回值 | 描述 |
Thenable<AuthenticationSession> | 一个 thenable,它解析为身份验证会话 |
getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & {forceNewSession: true | AuthenticationGetSessionPresentationOptions}): Thenable<AuthenticationSession>
获取与所需 scopes 匹配的身份验证会话。如果未注册 providerId 的提供程序,或者用户不同意与扩展共享身份验证信息,则拒绝。如果存在具有相同 scopes 的多个会话,则会向用户显示一个快速选择列表,以选择他们想要使用的帐户。
目前,只有两个身份验证提供程序是由编辑器的内置扩展贡献的,它们实现了 GitHub 和 Microsoft 身份验证:它们的 providerId 分别是 'github' 和 'microsoft'。
参数 | 描述 |
---|---|
providerId: string | 要使用的提供程序的 ID |
scopes: readonly string[] | 表示请求的权限的 scopes 列表。这些 scopes 取决于身份验证提供程序 |
options: AuthenticationGetSessionOptions & {forceNewSession: true | AuthenticationGetSessionPresentationOptions} | |
返回值 | 描述 |
Thenable<AuthenticationSession> | 一个 thenable,它解析为身份验证会话 |
getSession(providerId: string, scopes: readonly string[], options?: AuthenticationGetSessionOptions): Thenable<AuthenticationSession | undefined>
获取与所需 scopes 匹配的身份验证会话。如果未注册 providerId 的提供程序,或者用户不同意与扩展共享身份验证信息,则拒绝。如果存在具有相同 scopes 的多个会话,则会向用户显示一个快速选择列表,以选择他们想要使用的帐户。
目前,只有两个身份验证提供程序是由编辑器的内置扩展贡献的,它们实现了 GitHub 和 Microsoft 身份验证:它们的 providerId 分别是 'github' 和 'microsoft'。
参数 | 描述 |
---|---|
providerId: string | 要使用的提供程序的 ID |
scopes: readonly string[] | 表示请求的权限的 scopes 列表。这些 scopes 取决于身份验证提供程序 |
options?: AuthenticationGetSessionOptions | |
返回值 | 描述 |
Thenable<AuthenticationSession | undefined> | 一个 thenable,如果身份验证会话可用,则解析为身份验证会话,如果没有任何会话,则解析为 undefined |
registerAuthenticationProvider(id: string, label: string, provider: AuthenticationProvider, options?: AuthenticationProviderOptions): Disposable
注册身份验证提供程序。
每个 ID 只能有一个提供程序,如果 ID 已被另一个提供程序使用,则会抛出错误。ID 区分大小写。
参数 | 描述 |
---|---|
id: string | 提供程序的唯一标识符。 |
label: string | 提供程序的人类可读名称。 |
provider: AuthenticationProvider | 身份验证提供程序。 |
options?: AuthenticationProviderOptions | 提供程序的其他选项。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
聊天
用于聊天功能的命名空间。用户通过在聊天视图中向聊天参与者发送消息来与他们互动。聊天参与者可以通过 ChatResponseStream 以 markdown 或其他类型的内容进行响应。
函数
createChatParticipant(id: string, handler: ChatRequestHandler): ChatParticipant
创建一个新的 聊天参与者 实例。
参数 | 描述 |
---|---|
id: string | 参与者的唯一标识符。 |
handler: ChatRequestHandler | 参与者的请求处理程序。 |
返回值 | 描述 |
ChatParticipant | 一个新的聊天参与者 |
命令
用于处理命令的命名空间。简而言之,命令是一个具有唯一标识符的函数。该函数有时也称为命令处理程序。
可以使用 registerCommand 和 registerTextEditorCommand 函数将命令添加到编辑器。可以手动或从 UI 手势执行命令。这些手势包括:
- 调色板 - 在
package.json
中使用commands
部分,使命令显示在命令面板中。 - 键盘快捷键 - 在
package.json
中使用keybindings
部分,为你的扩展启用键盘快捷键。
扩展可以访问来自其他扩展和编辑器本身的命令。但是,当调用编辑器命令时,并非所有参数类型都受支持。
这是一个示例,它注册一个命令处理程序,并将该命令的条目添加到调色板。首先,使用标识符 extension.sayHello
注册一个命令处理程序。
commands.registerCommand('extension.sayHello', () => {
window.showInformationMessage('Hello World!');
});
其次,将命令标识符绑定到一个标题,该标题将显示在调色板中 (package.json
)。
{
"contributes": {
"commands": [
{
"command": "extension.sayHello",
"title": "Hello World"
}
]
}
}
函数
executeCommand<T>(command: string, ...rest: any[]): Thenable<T>
执行由给定命令标识符表示的命令。
参数 | 描述 |
---|---|
command: string | 要执行的命令的标识符。 |
...rest: any[] | 传递给命令函数的参数。 |
返回值 | 描述 |
Thenable<T> | 一个 thenable,它解析为给定命令的返回值。当命令处理程序函数不返回任何内容时,返回 |
getCommands(filterInternal?: boolean): Thenable<string[]>
检索所有可用命令的列表。以下划线开头的命令被视为内部命令。
参数 | 描述 |
---|---|
filterInternal?: boolean | 设置为 |
返回值 | 描述 |
Thenable<string[]> | Thenable,它解析为命令 ID 列表。 |
registerCommand(command: string, callback: (args: any[]) => any, thisArg?: any): Disposable
注册可以通过键盘快捷键、菜单项、操作或直接调用的命令。
使用已存在的命令标识符注册命令两次将导致错误。
参数 | 描述 |
---|---|
command: string | 命令的唯一标识符。 |
callback: (args: any[]) => any | 命令处理程序函数。 |
thisArg?: any | 调用处理程序函数时使用的 |
返回值 | 描述 |
Disposable | Disposable,它在释放时取消注册此命令。 |
registerTextEditorCommand(command: string, callback: (textEditor: TextEditor, edit: TextEditorEdit, args: any[]) => void, thisArg?: any): Disposable
注册可以通过键盘快捷键、菜单项、操作或直接调用的文本编辑器命令。
文本编辑器命令与普通的 commands 不同,因为它们仅在调用命令时存在活动编辑器时执行。此外,编辑器命令的命令处理程序可以访问活动编辑器和 edit 构建器。请注意,edit 构建器仅在回调执行时有效。
参数 | 描述 |
---|---|
command: string | 命令的唯一标识符。 |
callback: (textEditor: TextEditor, edit: TextEditorEdit, args: any[]) => void | |
thisArg?: any | 调用处理程序函数时使用的 |
返回值 | 描述 |
Disposable | Disposable,它在释放时取消注册此命令。 |
评论
函数
createCommentController(id: string, label: string): CommentController
创建一个新的 评论控制器 实例。
参数 | 描述 |
---|---|
id: string | 评论控制器的 |
label: string | 评论控制器的人类可读字符串。 |
返回值 | 描述 |
CommentController | 评论控制器 的实例。 |
调试
用于调试功能的命名空间。
变量
activeDebugConsole: DebugConsole
当前活动的 调试控制台。如果没有任何调试会话处于活动状态,则发送到调试控制台的输出不会显示。
activeDebugSession: DebugSession | undefined
当前活动的 调试会话 或 undefined
。活动调试会话是由调试操作浮动窗口表示的会话,或当前显示在调试操作浮动窗口下拉菜单中的会话。如果没有任何调试会话处于活动状态,则值为 undefined
。
activeStackItem: DebugThread | DebugStackFrame | undefined
当前聚焦的线程或堆栈帧,如果没有线程或堆栈被聚焦,则为 undefined
。线程可以在任何有活动调试会话时被聚焦,而堆栈帧只能在会话暂停且已检索调用堆栈时被聚焦。
breakpoints: readonly Breakpoint[]
断点列表。
事件
onDidChangeActiveDebugSession: Event<DebugSession | undefined>
onDidChangeActiveStackItem: Event<DebugThread | DebugStackFrame | undefined>
当 debug.activeStackItem 发生更改时触发的事件。
onDidChangeBreakpoints: Event<BreakpointsChangeEvent>
当断点集被添加、删除或更改时发出的 事件。
onDidReceiveDebugSessionCustomEvent: Event<DebugSessionCustomEvent>
onDidStartDebugSession: Event<DebugSession>
onDidTerminateDebugSession: Event<DebugSession>
函数
addBreakpoints(breakpoints: readonly Breakpoint[]): void
添加断点。
参数 | 描述 |
---|---|
breakpoints: readonly Breakpoint[] | 要添加的断点。 |
返回值 | 描述 |
void |
asDebugSourceUri(source: DebugProtocolSource, session?: DebugSession): Uri
将通过调试适配器协议接收的“Source”描述符对象转换为 Uri,该 Uri 可用于加载其内容。如果源描述符基于路径,则返回文件 Uri。如果源描述符使用引用编号,则构造一个特定的调试 Uri(方案为 'debug'),该 Uri 需要相应的 ContentProvider 和正在运行的调试会话
如果“Source”描述符没有足够的信息来创建 Uri,则会抛出错误。
参数 | 描述 |
---|---|
source: DebugProtocolSource | 符合调试适配器协议中定义的 Source 类型的对象。 |
session?: DebugSession | 可选的调试会话,当源描述符使用引用编号从活动调试会话加载内容时,将使用该会话。 |
返回值 | 描述 |
Uri | 可用于加载源内容的 uri。 |
registerDebugAdapterDescriptorFactory(debugType: string, factory: DebugAdapterDescriptorFactory): Disposable
为特定的调试类型注册 调试适配器描述符工厂。扩展程序仅允许为扩展程序定义的调试类型注册 DebugAdapterDescriptorFactory。否则会抛出错误。为调试类型注册多个 DebugAdapterDescriptorFactory 会导致错误。
参数 | 描述 |
---|---|
debugType: string | 工厂注册的调试类型。 |
factory: DebugAdapterDescriptorFactory | 要注册的 调试适配器描述符工厂。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此工厂。 |
registerDebugAdapterTrackerFactory(debugType: string, factory: DebugAdapterTrackerFactory): Disposable
为给定的调试类型注册调试适配器跟踪器工厂。
参数 | 描述 |
---|---|
debugType: string | 工厂注册的调试类型,或 '*' 以匹配所有调试类型。 |
factory: DebugAdapterTrackerFactory | 要注册的 调试适配器跟踪器工厂。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此工厂。 |
registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider, triggerKind?: DebugConfigurationProviderTriggerKind): Disposable
为特定的调试类型注册 调试配置提供程序。可选的 triggerKind 可用于指定何时触发提供程序的 provideDebugConfigurations
方法。目前有两种可能的触发器类型:值为 Initial
(或如果未给出触发器类型参数)时,provideDebugConfigurations
方法用于提供要复制到新创建的 launch.json 中的初始调试配置。使用触发器类型 Dynamic
时,provideDebugConfigurations
方法用于动态确定要呈现给用户的调试配置(除了来自 launch.json 的静态配置之外)。请注意,triggerKind
参数仅适用于 provideDebugConfigurations
方法:因此 resolveDebugConfiguration
方法完全不受影响。为不同的触发器类型注册具有解析方法的单个提供程序,会导致多次调用相同的解析方法。可以为同一类型注册多个提供程序。
参数 | 描述 |
---|---|
debugType: string | 提供程序注册的调试类型。 |
provider: DebugConfigurationProvider | 要注册的 调试配置提供程序。 |
triggerKind?: DebugConfigurationProviderTriggerKind | 提供程序的 'provideDebugConfiguration' 方法注册的 触发器。如果缺少 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
removeBreakpoints(breakpoints: readonly Breakpoint[]): void
移除断点。
参数 | 描述 |
---|---|
breakpoints: readonly Breakpoint[] | 要移除的断点。 |
返回值 | 描述 |
void |
startDebugging(folder: WorkspaceFolder, nameOrConfiguration: string | DebugConfiguration, parentSessionOrOptions?: DebugSession | DebugSessionOptions): Thenable<boolean>
通过使用命名的启动或命名的复合配置,或直接传递 DebugConfiguration 来启动调试。命名的配置在给定文件夹中找到的 '.vscode/launch.json' 中查找。在调试开始之前,所有未保存的文件都会被保存,并且启动配置会更新到最新状态。配置中使用的文件夹特定变量(例如 '${workspaceFolder}')会针对给定的文件夹进行解析。
参数 | 描述 |
---|---|
folder: WorkspaceFolder | 用于查找命名配置和解析变量的 工作区文件夹,或用于非文件夹设置的 |
nameOrConfiguration: string | DebugConfiguration | 调试或复合配置的名称,或 DebugConfiguration 对象。 |
parentSessionOrOptions?: DebugSession | DebugSessionOptions | 调试会话选项。当传递父 调试会话 时,假定选项仅包含此父会话。 |
返回值 | 描述 |
Thenable<boolean> | 一个 thenable,当调试可以成功启动时解析。 |
stopDebugging(session?: DebugSession): Thenable<void>
停止给定的调试会话,如果省略 session,则停止所有调试会话。
参数 | 描述 |
---|---|
session?: DebugSession | 要停止的 调试会话;如果省略,则停止所有会话。 |
返回值 | 描述 |
Thenable<void> | 一个 thenable,当会话已停止时解析。 |
环境
描述编辑器运行环境的命名空间。
变量
应用程序的托管位置。在桌面上,这是 'desktop'。在 Web 中,这是指定的嵌入器,例如 'github.dev'、'codespaces',如果嵌入器未提供该信息,则为 'web'
编辑器的应用程序名称,例如 'VS Code'。
编辑器运行的应用程序根文件夹。
注意,当在没有应用程序根文件夹表示的环境中运行时,该值为空字符串。
clipboard: Clipboard
系统剪贴板。
指示这是应用程序的全新安装。如果在安装的第一天内,则为 true
,否则为 false
。
指示用户是否启用了遥测。可以观察以确定扩展是否应发送遥测数据。
表示首选用户语言,例如 de-CH
、fr
或 en-US
。
logLevel: LogLevel
编辑器的当前日志级别。
计算机的唯一标识符。
remoteName: string | undefined
远程名称。由扩展定义,常见的示例包括用于 Windows Subsystem for Linux 的 wsl
或用于使用安全 shell 的远程的 ssh-remote
。
注意,当没有远程扩展主机时,该值是 undefined
,但是当存在远程扩展主机时,在所有扩展主机(本地和远程)中,该值都是已定义的。使用 Extension.extensionKind 来了解特定扩展是否在远程运行。
当前会话的唯一标识符。每次编辑器启动时都会更改。
扩展主机的检测到的默认 shell,这将被扩展主机的平台的 terminal.integrated.defaultProfile
设置覆盖。请注意,在不支持 shell 的环境中,该值为空字符串。
uiKind: UIKind
uiKind
属性指示从哪个 UI 访问扩展。例如,可以从桌面应用程序或 Web 浏览器访问扩展。
编辑器在操作系统中注册的自定义 URI 方案。
事件
onDidChangeLogLevel: Event<LogLevel>
当编辑器的日志级别更改时触发的 Event。
onDidChangeShell: Event<string>
当默认 shell 更改时触发的 Event。这将使用新的 shell 路径触发。
onDidChangeTelemetryEnabled: Event<boolean>
当用户启用或禁用遥测时触发的 Event。如果用户已启用遥测,则为 true
;如果用户已禁用遥测,则为 false
。
函数
asExternalUri(target: Uri): Thenable<Uri>
将 URI 解析为可外部访问的形式。
http:
或 https:
方案
解析外部 URI,例如 http:
或 https:
链接,从扩展运行的位置到客户端计算机上相同资源的 URI。
如果扩展在客户端计算机上运行,则此操作无效。
如果扩展在远程运行,此函数会自动建立从本地计算机到远程计算机上 target
的端口转发隧道,并返回隧道的本地 URI。端口转发隧道的生命周期由编辑器管理,用户可以关闭隧道。
注意,通过 openExternal
传递的 URI 会自动解析,您不应在它们之上调用 asExternalUri
。
vscode.env.uriScheme
创建一个 URI,如果在浏览器中打开(例如,通过 openExternal
),将导致注册的 UriHandler 被触发。
扩展不应对生成的 URI 做任何假设,也不应以任何方式更改它。相反,扩展可以使用此 URI 在身份验证流程中,例如,通过将 URI 作为回调查询参数添加到要进行身份验证的服务器。
注意,如果服务器决定向 URI 添加额外的查询参数(例如,令牌或密钥),它将出现在传递给 UriHandler 的 URI 中。
身份验证流程的示例
vscode.window.registerUriHandler({
handleUri(uri: vscode.Uri): vscode.ProviderResult<void> {
if (uri.path === '/did-authenticate') {
console.log(uri.toString());
}
}
});
const callableUri = await vscode.env.asExternalUri(
vscode.Uri.parse(vscode.env.uriScheme + '://my.extension/did-authenticate')
);
await vscode.env.openExternal(callableUri);
注意,扩展不应缓存 asExternalUri
的结果,因为解析的 URI 可能会由于系统或用户操作而失效 — 例如,在远程情况下,用户可能会关闭由 asExternalUri
打开的端口转发隧道。
任何其他方案
任何其他方案都将像提供的 URI 是工作区 URI 一样处理。在这种情况下,该方法将返回一个 URI,当处理该 URI 时,将使编辑器打开工作区。
createTelemetryLogger(sender: TelemetrySender, options?: TelemetryLoggerOptions): TelemetryLogger
创建一个新的 遥测记录器。
参数 | 描述 |
---|---|
sender: TelemetrySender | 遥测记录器使用的遥测发送器。 |
options?: TelemetryLoggerOptions | 遥测记录器的选项。 |
返回值 | 描述 |
TelemetryLogger | 一个新的遥测记录器 |
openExternal(target: Uri): Thenable<boolean>
使用默认应用程序在外部打开链接。根据使用的方案,这可以是:
- 浏览器 (
http:
,https:
) - 邮件客户端 (
mailto:
) - VSCode 本身(来自
vscode.env.uriScheme
的vscode:
)
注意,showTextDocument 是在编辑器内打开文本文档的正确方法,而不是此函数。
参数 | 描述 |
---|---|
target: Uri | 应打开的 URI。 |
返回值 | 描述 |
Thenable<boolean> | 指示打开是否成功的 Promise。 |
扩展
用于处理已安装扩展的命名空间。扩展由 Extension 接口表示,该接口可以对它们进行反射。
扩展编写者可以通过从 activate
调用返回其 API 公开表面来向其他扩展提供 API。
export function activate(context: vscode.ExtensionContext) {
let api = {
sum(a, b) {
return a + b;
},
mul(a, b) {
return a * b;
}
};
// 'export' public api-surface
return api;
}
当依赖另一个扩展的 API 时,请将 extensionDependencies
条目添加到 package.json
,并使用 getExtension 函数和 exports 属性,如下所示:
let mathExt = extensions.getExtension('genius.math');
let importedApi = mathExt.exports;
console.log(importedApi.mul(42, 1));
变量
all: readonly Extension<any>[]
系统中当前已知的所有扩展。
事件
onDidChange: Event<void>
当 extensions.all
更改时触发的事件。当扩展被安装、卸载、启用或禁用时,可能会发生这种情况。
函数
getExtension<T>(extensionId: string): Extension<T> | undefined
按其完整标识符获取扩展,格式为:publisher.name
。
参数 | 描述 |
---|---|
extensionId: string | 扩展标识符。 |
返回值 | 描述 |
Extension<T> | undefined | 扩展或 |
本地化
扩展 API 中与本地化相关的功能的命名空间。要正确使用此功能,您必须在扩展清单中定义 l10n
并拥有 bundle.l10n。
注意:内置扩展(例如,Git、TypeScript 语言特性、GitHub 身份验证)不包含在 l10n
属性要求中。换句话说,它们不需要在扩展清单中指定 l10n
,因为它们的翻译字符串来自语言包。
变量
已为扩展加载的本地化字符串包。如果没有加载任何包,则为 undefined。如果未找到任何包或当我们使用默认语言运行时,通常不会加载该包。
uri: Uri | undefined
已为扩展加载的本地化包的 URI。如果没有加载任何包,则为 undefined。如果未找到任何包或当我们使用默认语言运行时,通常不会加载该包。
函数
t(message: string, ...args: Array<string | number | boolean>): string
标记要本地化的字符串。如果为 env.language 指定的语言提供了本地化包,并且该包具有此消息的本地化值,则将返回该本地化值(对于任何模板化值,都注入了 args 值)。
示例
l10n.t('Hello {0}!', 'World');
参数 | 描述 |
---|---|
message: string | 要本地化的消息。支持索引模板,其中诸如 |
...args: Array<string | number | boolean> | 要在本地化字符串中使用的参数。参数的索引用于匹配本地化字符串中的模板占位符。 |
返回值 | 描述 |
string | 带有注入参数的本地化字符串。 |
t(message: string, args: Record<string, any>): string
标记要本地化的字符串。如果为 env.language 指定的语言提供了本地化包,并且该包具有此消息的本地化值,则将返回该本地化值(对于任何模板化值,都注入了 args 值)。
示例
l10n.t('Hello {name}', { name: 'Erich' });
参数 | 描述 |
---|---|
message: string | 要本地化的消息。支持命名模板,其中诸如 |
args: Record<string, any> | 要在本地化字符串中使用的参数。记录中键的名称用于匹配本地化字符串中的模板占位符。 |
返回值 | 描述 |
string | 带有注入参数的本地化字符串。 |
t(options: {args: Array<string | number | boolean> | Record<string, any>, comment: string | string[], message: string}): string
标记要本地化的字符串。如果为 env.language 指定的语言提供了本地化包,并且该包具有此消息的本地化值,则将返回该本地化值(对于任何模板化值,都注入了 args 值)。
参数 | 描述 |
---|---|
options: {args: Array<string | number | boolean> | Record<string, any>, comment: string | string[], message: string} | 本地化消息时要使用的选项。 |
返回值 | 描述 |
string | 带有注入参数的本地化字符串。 |
语言
用于参与特定于语言的编辑器 功能(如 IntelliSense、代码操作、诊断等)的命名空间。
存在许多编程语言,并且在语法、语义和范例方面存在巨大差异。尽管如此,诸如自动单词完成、代码导航或代码检查之类的功能已在不同编程语言的不同工具中变得流行。
编辑器提供了一个 API,通过预先设置所有 UI 和操作,并允许您仅通过提供数据来参与,从而可以轻松提供此类常用功能。例如,要贡献悬停,您只需提供一个可以使用 TextDocument 和 Position 调用的函数,该函数返回悬停信息。其余的,例如跟踪鼠标、定位悬停、保持悬停稳定等,都由编辑器负责。
languages.registerHoverProvider('javascript', {
provideHover(document, position, token) {
return new Hover('I am a hover!');
}
});
注册是使用 文档选择器 完成的,该选择器可以是语言 ID(如 javascript
)或更复杂的 过滤器(如 { language: 'typescript', scheme: 'file' }
)。将文档与此类选择器匹配将产生一个 分数,该分数用于确定是否以及如何使用提供程序。当分数相等时,最后一个提供程序获胜。对于允许完全元数的功能(如 hover),仅检查分数是否 >0
;对于其他功能(如 IntelliSense),分数用于确定要求提供程序参与的顺序。
事件
onDidChangeDiagnostics: Event<DiagnosticChangeEvent>
当全局诊断集更改时触发的 Event。这是新添加和删除的诊断。
函数
createDiagnosticCollection(name?: string): DiagnosticCollection
创建诊断集合。
参数 | 描述 |
---|---|
name?: string | 集合的 name。 |
返回值 | 描述 |
DiagnosticCollection | 一个新的诊断集合。 |
createLanguageStatusItem(id: string, selector: DocumentSelector): LanguageStatusItem
创建一个新的 语言状态项。
参数 | 描述 |
---|---|
id: string | 项的标识符。 |
selector: DocumentSelector | 文档选择器,用于定义该项在哪些编辑器中显示。 |
返回值 | 描述 |
LanguageStatusItem | 一个新的语言状态项。 |
getDiagnostics(resource: Uri): Diagnostic[]
获取给定资源的所有诊断。
参数 | 描述 |
---|---|
resource: Uri | 资源 |
返回值 | 描述 |
Diagnostic[] | diagnostics 对象数组或空数组。 |
getDiagnostics(): Array<[Uri, Diagnostic[]]>
获取所有诊断。
参数 | 描述 |
---|---|
返回值 | 描述 |
Array<[Uri, Diagnostic[]]> | URI 诊断元组数组或空数组。 |
getLanguages(): Thenable<string[]>
返回所有已知语言的标识符。
参数 | 描述 |
---|---|
返回值 | 描述 |
Thenable<string[]> | Promise,解析为标识符字符串数组。 |
match(selector: DocumentSelector, document: TextDocument): number
计算文档 选择器 和文档之间的匹配度。值大于零表示选择器与文档匹配。
根据以下规则计算匹配度:
- 当 DocumentSelector 是数组时,计算每个包含的
DocumentFilter
或语言标识符的匹配度,并取最大值。 - 字符串将被解糖以成为 DocumentFilter 的
language
部分,因此"fooLang"
类似于{ language: "fooLang" }
。 - 将 DocumentFilter 与文档进行匹配,方法是将其各个部分与文档进行比较。以下规则适用:
- 当
DocumentFilter
为空 ({}
) 时,结果为0
- 当
scheme
、language
、pattern
或notebook
已定义但其中一个不匹配时,结果为0
- 与
*
匹配得到的分数为5
,通过相等性或通过 glob 模式匹配得到的分数为10
- 结果是每个匹配的最大值
- 当
示例
// default document from disk (file-scheme)
doc.uri; //'file:///my/file.js'
doc.languageId; // 'javascript'
match('javascript', doc); // 10;
match({ language: 'javascript' }, doc); // 10;
match({ language: 'javascript', scheme: 'file' }, doc); // 10;
match('*', doc); // 5
match('fooLang', doc); // 0
match(['fooLang', '*'], doc); // 5
// virtual document, e.g. from git-index
doc.uri; // 'git:/my/file.js'
doc.languageId; // 'javascript'
match('javascript', doc); // 10;
match({ language: 'javascript', scheme: 'git' }, doc); // 10;
match('*', doc); // 5
// notebook cell document
doc.uri; // `vscode-notebook-cell:///my/notebook.ipynb#gl65s2pmha`;
doc.languageId; // 'python'
match({ notebookType: 'jupyter-notebook' }, doc); // 10
match({ notebookType: 'fooNotebook', language: 'python' }, doc); // 0
match({ language: 'python' }, doc); // 10
match({ notebookType: '*' }, doc); // 5
参数 | 描述 |
---|---|
selector: DocumentSelector | 文档选择器。 |
document: TextDocument | 文本文档。 |
返回值 | 描述 |
number | 当选择器匹配时,数字 |
registerCallHierarchyProvider(selector: DocumentSelector, provider: CallHierarchyProvider): Disposable
注册调用层次结构提供程序。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: CallHierarchyProvider | 调用层次结构提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerCodeActionsProvider(selector: DocumentSelector, provider: CodeActionProvider<CodeAction>, metadata?: CodeActionProviderMetadata): Disposable
注册代码操作提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: CodeActionProvider<CodeAction> | 代码操作提供程序。 |
metadata?: CodeActionProviderMetadata | 有关提供程序提供的代码操作种类元数据。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerCodeLensProvider(selector: DocumentSelector, provider: CodeLensProvider<CodeLens>): Disposable
注册代码镜头提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: CodeLensProvider<CodeLens> | 代码镜头提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerColorProvider(selector: DocumentSelector, provider: DocumentColorProvider): Disposable
注册颜色提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DocumentColorProvider | 颜色提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerCompletionItemProvider(selector: DocumentSelector, provider: CompletionItemProvider<CompletionItem>, ...triggerCharacters: string[]): Disposable
注册完成项提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序按其 分数 排序,并且按顺序询问相等分数组的完成项。当一组或多组提供程序返回结果时,该过程停止。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
完成项提供程序可以与一组 triggerCharacters
关联。当键入触发字符时,会请求完成项,但仅从注册了键入字符的提供程序请求。因此,触发字符应与 单词字符 不同,常见的触发字符是 .
,用于触发成员完成。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: CompletionItemProvider<CompletionItem> | 完成提供程序。 |
...triggerCharacters: string[] | 当用户键入其中一个字符时触发完成。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerDeclarationProvider(selector: DocumentSelector, provider: DeclarationProvider): Disposable
注册声明提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DeclarationProvider | 声明提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerDefinitionProvider(selector: DocumentSelector, provider: DefinitionProvider): Disposable
注册定义提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DefinitionProvider | 定义提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerDocumentDropEditProvider(selector: DocumentSelector, provider: DocumentDropEditProvider<DocumentDropEdit>, metadata?: DocumentDropEditProviderMetadata): Disposable
注册新的 DocumentDropEditProvider。
可以为一个语言注册多个拖放提供程序。当将内容拖放到编辑器中时,将根据其 DocumentDropEditProviderMetadata 指定的处理的 MIME 类型,调用编辑器语言的所有已注册提供程序。
每个提供程序可以返回一个或多个 DocumentDropEdit。这些编辑使用 DocumentDropEdit.yieldTo 属性排序。默认情况下,将应用第一个编辑。如果有任何其他编辑,这些编辑将在拖放小部件中作为可选择的拖放选项向用户显示。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DocumentDropEditProvider<DocumentDropEdit> | 拖放提供程序。 |
metadata?: DocumentDropEditProviderMetadata | 有关提供程序的其他元数据。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在处理时取消注册此提供程序。 |
registerDocumentFormattingEditProvider(selector: DocumentSelector, provider: DocumentFormattingEditProvider): Disposable
注册文档的格式化提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序按其 分数 排序,并使用最佳匹配的提供程序。所选提供程序的失败将导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DocumentFormattingEditProvider | 文档格式化编辑提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerDocumentHighlightProvider(selector: DocumentSelector, provider: DocumentHighlightProvider): Disposable
注册文档高亮显示提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序按其 分数 排序,并按顺序询问文档高亮显示组。当提供程序返回 non-falsy
或 non-failure
结果时,该过程停止。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DocumentHighlightProvider | 文档高亮显示提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerDocumentLinkProvider(selector: DocumentSelector, provider: DocumentLinkProvider<DocumentLink>): Disposable
注册文档链接提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DocumentLinkProvider<DocumentLink> | 文档链接提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerDocumentPasteEditProvider(selector: DocumentSelector, provider: DocumentPasteEditProvider<DocumentPasteEdit>, metadata: DocumentPasteProviderMetadata): Disposable
注册一个新的 DocumentPasteEditProvider。
可以为一种语言注册多个提供程序。将根据 DocumentPasteProviderMetadata 指定的它们处理的 MIME 类型,为语言注册的所有提供程序调用复制和粘贴操作。
对于 复制操作,每个提供程序对 DataTransfer 所做的更改将合并到单个 DataTransfer 中,该 DataTransfer 用于填充剪贴板。
对于 [DocumentPasteEditProvider.providerDocumentPasteEdits 粘贴操作](#DocumentPasteEditProvider.providerDocumentPasteEdits paste operations),将调用每个提供程序,并且可以返回一个或多个 DocumentPasteEdits。编辑将使用 DocumentPasteEdit.yieldTo 属性进行排序。默认情况下,将应用第一个编辑,其余编辑将作为可选择的粘贴选项在粘贴小组件中向用户显示。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DocumentPasteEditProvider<DocumentPasteEdit> | 粘贴编辑器提供程序。 |
metadata: DocumentPasteProviderMetadata | 有关提供程序的其他元数据。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在处理时取消注册此提供程序。 |
registerDocumentRangeFormattingEditProvider(selector: DocumentSelector, provider: DocumentRangeFormattingEditProvider): Disposable
为文档范围注册格式化提供程序。
注意: 文档范围提供程序也是一个 文档格式化程序,这意味着在注册范围提供程序时,无需 注册 文档格式化程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序按其 分数 排序,并使用最佳匹配的提供程序。所选提供程序的失败将导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DocumentRangeFormattingEditProvider | 文档范围格式化编辑提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerDocumentRangeSemanticTokensProvider(selector: DocumentSelector, provider: DocumentRangeSemanticTokensProvider, legend: SemanticTokensLegend): Disposable
为文档范围注册语义标记提供程序。
注意: 如果文档同时具有 DocumentSemanticTokensProvider
和 DocumentRangeSemanticTokensProvider
,则范围提供程序将仅在初始时被调用,用于完整文档提供程序解析第一个请求所需的时间。一旦完整文档提供程序解析了第一个请求,通过范围提供程序提供的语义标记将被丢弃,并且从那时起,将仅使用文档提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序按其 分数 排序,并使用最佳匹配的提供程序。所选提供程序的失败将导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DocumentRangeSemanticTokensProvider | 文档范围语义标记提供程序。 |
legend: SemanticTokensLegend | |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerDocumentSemanticTokensProvider(selector: DocumentSelector, provider: DocumentSemanticTokensProvider, legend: SemanticTokensLegend): Disposable
为整个文档注册语义标记提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序按其 分数 排序,并使用最佳匹配的提供程序。所选提供程序的失败将导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DocumentSemanticTokensProvider | 文档语义标记提供程序。 |
legend: SemanticTokensLegend | |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerDocumentSymbolProvider(selector: DocumentSelector, provider: DocumentSymbolProvider, metaData?: DocumentSymbolProviderMetadata): Disposable
注册文档符号提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: DocumentSymbolProvider | 文档符号提供程序。 |
metaData?: DocumentSymbolProviderMetadata | 有关提供程序的元数据 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerEvaluatableExpressionProvider(selector: DocumentSelector, provider: EvaluatableExpressionProvider): Disposable
注册一个提供程序,用于在文本文档中定位可求值的表达式。编辑器将在活动调试会话中求值表达式,并将结果显示在调试悬停窗口中。
如果为一种语言注册了多个提供程序,则将使用任意提供程序。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: EvaluatableExpressionProvider | 可求值表达式提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerFoldingRangeProvider(selector: DocumentSelector, provider: FoldingRangeProvider): Disposable
注册折叠范围提供程序。
可以为一种语言注册多个提供程序。在这种情况下,将并行询问提供程序,并将结果合并。如果多个折叠范围在同一位置开始,则仅使用第一个注册的提供程序的范围。如果折叠范围与另一个位置较小的范围重叠,则也会忽略该范围。
失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: FoldingRangeProvider | 折叠范围提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerHoverProvider(selector: DocumentSelector, provider: HoverProvider): Disposable
注册悬停提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: HoverProvider | 悬停提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerImplementationProvider(selector: DocumentSelector, provider: ImplementationProvider): Disposable
注册实现提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: ImplementationProvider | 实现提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerInlayHintsProvider(selector: DocumentSelector, provider: InlayHintsProvider<InlayHint>): Disposable
注册内嵌提示提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: InlayHintsProvider<InlayHint> | 内嵌提示提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerInlineCompletionItemProvider(selector: DocumentSelector, provider: InlineCompletionItemProvider): Disposable
注册内联完成提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: InlineCompletionItemProvider | 内联完成提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerInlineValuesProvider(selector: DocumentSelector, provider: InlineValuesProvider): Disposable
注册一个提供程序,该提供程序返回调试器的“内联值”功能的数据。每当通用调试器在源文件中停止时,都会调用为文件语言注册的提供程序,以返回将在编辑器中行尾显示的文本数据。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: InlineValuesProvider | 内联值提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerLinkedEditingRangeProvider(selector: DocumentSelector, provider: LinkedEditingRangeProvider): Disposable
注册链接编辑范围提供程序。
可以为一种语言注册多个提供程序。在这种情况下,提供程序按其 评分 排序,并使用具有结果的最佳匹配提供程序。所选提供程序的失败将导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: LinkedEditingRangeProvider | 链接编辑范围提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerOnTypeFormattingEditProvider(selector: DocumentSelector, provider: OnTypeFormattingEditProvider, firstTriggerCharacter: string, ...moreTriggerCharacter: string[]): Disposable
注册一个在键入时工作的格式化提供程序。当用户启用 editor.formatOnType
设置时,该提供程序处于活动状态。
可以为一个语言注册多个提供程序。在这种情况下,提供程序按其 分数 排序,并使用最佳匹配的提供程序。所选提供程序的失败将导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: OnTypeFormattingEditProvider | 键入时格式化编辑提供程序。 |
firstTriggerCharacter: string | 应触发格式化的字符,例如 |
...moreTriggerCharacter: string[] | 更多触发字符。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerReferenceProvider(selector: DocumentSelector, provider: ReferenceProvider): Disposable
注册引用提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: ReferenceProvider | 引用提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerRenameProvider(selector: DocumentSelector, provider: RenameProvider): Disposable
注册重命名提供程序。
可以为一种语言注册多个提供程序。在这种情况下,提供程序按其 评分 排序并按顺序询问。第一个产生结果的提供程序定义整个操作的结果。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: RenameProvider | 重命名提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerSelectionRangeProvider(selector: DocumentSelector, provider: SelectionRangeProvider): Disposable
注册选择范围提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: SelectionRangeProvider | 选择范围提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, ...triggerCharacters: string[]): Disposable
注册签名帮助提供程序。
可以为一种语言注册多个提供程序。在这种情况下,提供程序按其 评分 排序并按顺序调用,直到提供程序返回有效结果。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: SignatureHelpProvider | 签名帮助提供程序。 |
...triggerCharacters: string[] | 当用户键入字符(如 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, metadata: SignatureHelpProviderMetadata): Disposable
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: SignatureHelpProvider | 签名帮助提供程序。 |
metadata: SignatureHelpProviderMetadata | 有关提供程序的信息。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerTypeDefinitionProvider(selector: DocumentSelector, provider: TypeDefinitionProvider): Disposable
注册类型定义提供程序。
可以为一个语言注册多个提供程序。在这种情况下,提供程序会并行询问,结果会合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: TypeDefinitionProvider | 类型定义提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerTypeHierarchyProvider(selector: DocumentSelector, provider: TypeHierarchyProvider): Disposable
注册类型层次结构提供程序。
参数 | 描述 |
---|---|
selector: DocumentSelector | 一个选择器,用于定义此提供程序适用于哪些文档。 |
provider: TypeHierarchyProvider | 类型层次结构提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerWorkspaceSymbolProvider(provider: WorkspaceSymbolProvider<SymbolInformation>): Disposable
注册工作区符号提供程序。
可以注册多个提供程序。在这种情况下,将并行询问提供程序,并将结果合并。失败的提供程序(拒绝的 Promise 或异常)不会导致整个操作失败。
参数 | 描述 |
---|---|
provider: WorkspaceSymbolProvider<SymbolInformation> | 工作区符号提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
setLanguageConfiguration(language: string, configuration: LanguageConfiguration): Disposable
为语言设置 语言配置。
参数 | 描述 |
---|---|
language: string | 语言标识符,例如 |
configuration: LanguageConfiguration | 语言配置。 |
返回值 | 描述 |
Disposable | 一个 Disposable,用于取消设置此配置。 |
setTextDocumentLanguage(document: TextDocument, languageId: string): Thenable<TextDocument>
设置(和更改)与给定文档关联的 语言。
注意 调用此函数将触发 onDidCloseTextDocument 事件,然后触发 onDidOpenTextDocument 事件。
参数 | 描述 |
---|---|
document: TextDocument | 要更改其语言的文档 |
languageId: string | 新的语言标识符。 |
返回值 | 描述 |
Thenable<TextDocument> | 一个 thenable,它解析为更新后的文档。 |
语言模型
用于语言模型相关功能的命名空间。
变量
tools: readonly LanguageModelToolInformation[]
所有扩展使用 lm.registerTool 注册的所有可用工具的列表。可以使用 lm.invokeTool 以及与其声明的 inputSchema
匹配的输入来调用它们。
事件
onDidChangeChatModels: Event<void>
当可用聊天模型的集合更改时触发的事件。
函数
invokeTool(name: string, options: LanguageModelToolInvocationOptions<object>, token?: CancellationToken): Thenable<LanguageModelToolResult>
使用给定的输入,按名称调用 lm.tools 中列出的工具。输入将根据工具声明的模式进行验证
工具可以由聊天参与者在处理聊天请求的上下文中调用,也可以由任何扩展在任何自定义流程中全局调用。
在前一种情况下,调用者应传递 toolInvocationToken,它带有 聊天请求。这确保聊天 UI 为正确的对话显示工具调用。
工具 result 是 text- 和 prompt-tsx-parts 的数组。如果工具调用者正在使用 vscode/prompt-tsx
,则可以使用 ToolResult
将响应部分合并到其提示中。如果不是,则可以通过带有 LanguageModelToolResultPart 的用户消息将这些部分传递给 LanguageModelChat。
如果聊天参与者想要为跨多个回合的请求保留工具结果,则可以将工具结果存储在从处理程序返回的 ChatResult.metadata 中,并在下一个回合中从 ChatResponseTurn.result 中检索它们。
参数 | 描述 |
---|---|
name: string | 要调用的工具的名称。 |
options: LanguageModelToolInvocationOptions<object> | 调用工具时要使用的选项。 |
token?: CancellationToken | 取消令牌。有关如何创建一个取消令牌,请参阅 CancellationTokenSource。 |
返回值 | 描述 |
Thenable<LanguageModelToolResult> | 工具调用的结果。 |
registerTool<T>(name: string, tool: LanguageModelTool<T>): Disposable
注册 LanguageModelTool。该工具还必须在 package.json languageModelTools
贡献点中注册。注册的工具在 lm.tools 列表中可供任何扩展查看。但是,为了让语言模型看到它,必须在 LanguageModelChatRequestOptions.tools 中可用的工具列表中传递它。
参数 | 描述 |
---|---|
name: string | |
tool: LanguageModelTool<T> | |
返回值 | 描述 |
Disposable | 一个 Disposable,用于在处置时取消注册工具。 |
selectChatModels(selector?: LanguageModelChatSelector): Thenable<LanguageModelChat[]>
通过 选择器 选择聊天模型。这可能会产生多个或零个聊天模型,扩展必须优雅地处理这些情况,尤其是在没有聊天模型存在时。
const models = await vscode.lm.selectChatModels({ family: 'gpt-3.5-turbo' });
if (models.length > 0) {
const [first] = models;
const response = await first.sendRequest(...)
// ...
} else {
// NO chat models available
}
可以编写选择器来广泛匹配给定供应商或系列的所有模型,或者它可以狭隘地按 ID 选择一个模型。请记住,可用模型的集合会随着时间而变化,但提示在不同模型中的表现也可能不同。
注意 扩展可以保留此函数返回的结果并在以后使用它们。但是,当 onDidChangeChatModels-事件触发时,聊天模型列表可能已更改,扩展应重新查询。
参数 | 描述 |
---|---|
selector?: LanguageModelChatSelector | 聊天模型选择器。省略时,将返回所有聊天模型。 |
返回值 | 描述 |
Thenable<LanguageModelChat[]> | 聊天模型数组,可以为空! |
笔记本
笔记本的命名空间。
笔记本功能由三个松散耦合的组件组成
- NotebookSerializer 使编辑器能够打开、显示和保存笔记本
- NotebookController 拥有笔记本的执行权,例如,它们从代码单元格创建输出。
- NotebookRenderer 在编辑器中呈现笔记本输出。它们在单独的上下文中运行。
函数
createNotebookController(id: string, notebookType: string, label: string, handler?: (cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController) => void | Thenable<void>): NotebookController
创建一个新的笔记本控制器。
参数 | 描述 |
---|---|
id: string | 控制器的标识符。每个扩展必须是唯一的。 |
notebookType: string | 此控制器适用的笔记本类型。 |
label: string | 控制器的标签。 |
handler?: (cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController) => void | Thenable<void> | 控制器的执行处理程序。 |
返回值 | 描述 |
NotebookController | 一个新的笔记本控制器。 |
createRendererMessaging(rendererId: string): NotebookRendererMessaging
创建一个新的消息传递实例,用于与特定的渲染器通信。
- 注意 1: 扩展只能创建它们在
package.json
文件中定义的渲染器 - 注意 2: 只有当渲染器的
notebookRenderer
贡献中的requiresMessaging
设置为always
或optional
时,渲染器才有权访问消息传递。
参数 | 描述 |
---|---|
rendererId: string | 要与之通信的渲染器 ID |
返回值 | 描述 |
NotebookRendererMessaging | 一个新的笔记本渲染器消息传递对象。 |
registerNotebookCellStatusBarItemProvider(notebookType: string, provider: NotebookCellStatusBarItemProvider): Disposable
为给定的笔记本类型注册 单元格状态栏项目提供程序。
参数 | 描述 |
---|---|
notebookType: string | 要注册的笔记本类型。 |
provider: NotebookCellStatusBarItemProvider | 单元格状态栏提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
源代码管理
源代码管理命名空间。
变量
inputBox: SourceControlInputBox
扩展创建的最后一个源代码管理的 输入框。
- 已弃用 - 请改用 SourceControl.inputBox
函数
createSourceControl(id: string, label: string, rootUri?: Uri): SourceControl
创建一个新的 源代码管理 实例。
参数 | 描述 |
---|---|
id: string | 源代码管理的 |
label: string | 源代码管理的人类可读字符串。例如: |
rootUri?: Uri | 源代码根目录的可选 Uri。例如: |
返回值 | 描述 |
SourceControl | 一个 源代码管理 的实例。 |
任务
任务功能的命名空间。
变量
taskExecutions: readonly TaskExecution[]
当前活动的任务执行或空数组。
事件
onDidEndTask: Event<TaskEndEvent>
任务结束时触发。
onDidEndTaskProcess: Event<TaskProcessEndEvent>
当底层进程结束时触发。此事件不会为不执行底层进程的任务触发。
onDidStartTask: Event<TaskStartEvent>
任务开始时触发。
onDidStartTaskProcess: Event<TaskProcessStartEvent>
当底层进程已启动时触发。此事件不会为不执行底层进程的任务触发。
函数
executeTask(task: Task): Thenable<TaskExecution>
执行由编辑器管理的任务。返回的任务执行可用于终止任务。
- throws - 当在无法启动新进程的环境中运行 ShellExecution 或 ProcessExecution 任务时抛出异常。在这种环境中,只能运行 CustomExecution 任务。
参数 | 描述 |
---|---|
task: Task | 要执行的任务 |
返回值 | 描述 |
Thenable<TaskExecution> | 一个可 then 的对象,它解析为一个任务执行。 |
fetchTasks(filter?: TaskFilter): Thenable<Task[]>
获取系统中所有可用的任务。这包括来自 tasks.json
文件的任务以及通过扩展贡献的任务提供程序提供的任务。
参数 | 描述 |
---|---|
filter?: TaskFilter | 可选过滤器,用于选择特定类型或版本的任务。 |
返回值 | 描述 |
Thenable<Task[]> | 一个可 then 的对象,它解析为一个任务数组。 |
registerTaskProvider(type: string, provider: TaskProvider<Task>): Disposable
注册一个任务提供程序。
参数 | 描述 |
---|---|
type: string | 此提供程序注册的任务类型。 |
provider: TaskProvider<Task> | 一个任务提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
测试
用于测试功能的命名空间。测试通过注册 TestController 实例,然后添加 TestItems 来发布。控制器还可以通过创建一个或多个 TestRunProfile 实例来描述如何运行测试。
函数
createTestController(id: string, label: string): TestController
创建一个新的测试控制器。
参数 | 描述 |
---|---|
id: string | 控制器的标识符,必须是全局唯一的。 |
label: string | 控制器的用户可读标签。 |
返回值 | 描述 |
TestController | TestController 的一个实例。 |
窗口
用于处理编辑器当前窗口的命名空间。即可见和活动的编辑器,以及用于显示消息、选择和请求用户输入的 UI 元素。
变量
activeColorTheme: ColorTheme
当前活动颜色主题,如设置中所配置。可以通过 workbench.colorTheme
设置更改活动主题。
activeNotebookEditor: NotebookEditor | undefined
当前活动的 笔记本编辑器 或 undefined
。活动编辑器是当前具有焦点的编辑器,或者,当没有焦点时,是最近更改输入的编辑器。
activeTerminal: Terminal | undefined
当前活动的终端或 undefined
。活动终端是当前具有焦点或最近具有焦点的终端。
activeTextEditor: TextEditor | undefined
当前活动的编辑器或 undefined
。活动编辑器是当前具有焦点的编辑器,或者,当没有焦点时,是最近更改输入的编辑器。
state: WindowState
表示当前窗口的状态。
tabGroups: TabGroups
表示主编辑器区域内的网格小部件
terminals: readonly Terminal[]
当前打开的终端或一个空数组。
visibleNotebookEditors: readonly NotebookEditor[]
当前可见的 笔记本编辑器 或一个空数组。
visibleTextEditors: readonly TextEditor[]
当前可见的编辑器或一个空数组。
事件
onDidChangeActiveColorTheme: Event<ColorTheme>
当活动颜色主题更改或发生更改时触发的 事件。
onDidChangeActiveNotebookEditor: Event<NotebookEditor | undefined>
onDidChangeActiveTerminal: Event<Terminal | undefined>
onDidChangeActiveTextEditor: Event<TextEditor | undefined>
onDidChangeNotebookEditorSelection: Event<NotebookEditorSelectionChangeEvent>
onDidChangeNotebookEditorVisibleRanges: Event<NotebookEditorVisibleRangesChangeEvent>
当 笔记本编辑器可见范围 更改时触发的 事件。
onDidChangeTerminalShellIntegration: Event<TerminalShellIntegrationChangeEvent>
当终端中的 Shell 集成激活或其属性之一发生更改时触发。
onDidChangeTerminalState: Event<Terminal>
onDidChangeTextEditorOptions: Event<TextEditorOptionsChangeEvent>
当编辑器的选项更改时触发的 事件。
onDidChangeTextEditorSelection: Event<TextEditorSelectionChangeEvent>
当编辑器中的选择更改时触发的 事件。
onDidChangeTextEditorViewColumn: Event<TextEditorViewColumnChangeEvent>
当编辑器的视图列更改时触发的 事件。
onDidChangeTextEditorVisibleRanges: Event<TextEditorVisibleRangesChangeEvent>
当编辑器的可见范围更改时触发的 事件。
onDidChangeVisibleNotebookEditors: Event<readonly NotebookEditor[]>
onDidChangeVisibleTextEditors: Event<readonly TextEditor[]>
onDidChangeWindowState: Event<WindowState>
当当前窗口的焦点或活动状态更改时触发的 事件。事件的值表示窗口是否具有焦点。
onDidCloseTerminal: Event<Terminal>
当终端被释放时触发的 事件。
onDidEndTerminalShellExecution: Event<TerminalShellExecutionEndEvent>
当终端命令结束时,将触发此事件。仅当为终端激活 Shell 集成 时,此事件才会触发。
onDidOpenTerminal: Event<Terminal>
当终端已创建时触发的 事件,无论是通过 createTerminal API 还是命令。
onDidStartTerminalShellExecution: Event<TerminalShellExecutionStartEvent>
当终端命令启动时,将触发此事件。仅当为终端激活 Shell 集成 时,此事件才会触发。
函数
createInputBox(): InputBox
创建一个 InputBox,让用户输入一些文本输入。
请注意,在许多情况下,更方便的 window.showInputBox 更易于使用。当 window.showInputBox 不提供所需的灵活性时,应使用 window.createInputBox。
createOutputChannel(name: string, languageId?: string): OutputChannel
使用给定的名称和语言 ID 创建一个新的 输出通道。如果未提供语言 ID,则使用 Log 作为默认语言 ID。
你可以从 可见编辑器 或 活动编辑器 访问可见或活动的输出通道作为 文本文件,并使用语言 ID 来贡献语言功能,例如语法着色、代码镜头等。
参数 | 描述 |
---|---|
name: string | 用户可读的字符串,将用于表示 UI 中的通道。 |
languageId?: string | 与通道关联的语言的标识符。 |
返回值 | 描述 |
OutputChannel | 一个新的输出通道。 |
createOutputChannel(name: string, options: {log: true}): LogOutputChannel
使用给定的名称创建一个新的 日志输出通道。
参数 | 描述 |
---|---|
name: string | 用户可读的字符串,将用于表示 UI 中的通道。 |
options: {log: true} | 日志输出通道的选项。 |
返回值 | 描述 |
LogOutputChannel | 一个新的日志输出通道。 |
createQuickPick<T extends QuickPickItem>(): QuickPick<T>
创建一个 QuickPick,让用户从类型 T 的项目列表中选择一个项目。
请注意,在许多情况下,更方便的 window.showQuickPick 更易于使用。当 window.showQuickPick 不提供所需的灵活性时,应使用 window.createQuickPick。
createStatusBarItem(id: string, alignment?: StatusBarAlignment, priority?: number): StatusBarItem
创建一个状态栏 项目。
参数 | 描述 |
---|---|
id: string | 项目的标识符。在扩展中必须是唯一的。 |
alignment?: StatusBarAlignment | 项目的对齐方式。 |
priority?: number | 项目的优先级。值越高表示项目应更靠左显示。 |
返回值 | 描述 |
StatusBarItem | 一个新的状态栏项目。 |
createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem
创建一个状态栏 项目。
另请参阅 createStatusBarItem,了解如何创建带有标识符的状态栏项目。
参数 | 描述 |
---|---|
alignment?: StatusBarAlignment | 项目的对齐方式。 |
priority?: number | 项目的优先级。值越高表示项目应更靠左显示。 |
返回值 | 描述 |
StatusBarItem | 一个新的状态栏项目。 |
createTerminal(name?: string, shellPath?: string, shellArgs?: string | readonly string[]): Terminal
创建一个带有后备 Shell 进程的 Terminal。如果工作区目录存在,则终端的 cwd 将是工作区目录。
- 抛出异常 - 当在无法启动新进程的环境中运行时。
createTerminal(options: TerminalOptions): Terminal
创建一个带有后备 Shell 进程的 Terminal。
- 抛出异常 - 当在无法启动新进程的环境中运行时。
参数 | 描述 |
---|---|
options: TerminalOptions | 一个 TerminalOptions 对象,描述新终端的特性。 |
返回值 | 描述 |
Terminal | 一个新的 Terminal。 |
createTerminal(options: ExtensionTerminalOptions): Terminal
创建一个 Terminal,其中扩展控制其输入和输出。
参数 | 描述 |
---|---|
options: ExtensionTerminalOptions | 一个 ExtensionTerminalOptions 对象,描述新终端的特性。 |
返回值 | 描述 |
Terminal | 一个新的 Terminal。 |
createTextEditorDecorationType(options: DecorationRenderOptions): TextEditorDecorationType
创建一个 TextEditorDecorationType,可用于向文本编辑器添加装饰。
参数 | 描述 |
---|---|
options: DecorationRenderOptions | 装饰类型的渲染选项。 |
返回值 | 描述 |
TextEditorDecorationType | 一个新的装饰类型实例。 |
createTreeView<T>(viewId: string, options: TreeViewOptions<T>): TreeView<T>
为使用扩展点 views
贡献的视图创建一个 TreeView。
参数 | 描述 |
---|---|
viewId: string | 使用扩展点 |
options: TreeViewOptions<T> | 用于创建 TreeView 的选项 |
返回值 | 描述 |
TreeView<T> | 一个 TreeView。 |
createWebviewPanel(viewType: string, title: string, showOptions: ViewColumn | {preserveFocus: boolean, viewColumn: ViewColumn}, options?: WebviewPanelOptions & WebviewOptions): WebviewPanel
创建并显示一个新的 Webview 面板。
参数 | 描述 |
---|---|
viewType: string | 标识 Webview 面板的类型。 |
title: string | 面板的标题。 |
showOptions: ViewColumn | {preserveFocus: boolean, viewColumn: ViewColumn} | 在编辑器中显示 Webview 的位置。如果设置了 preserveFocus,则新的 Webview 将不会获取焦点。 |
options?: WebviewPanelOptions & WebviewOptions | 新面板的设置。 |
返回值 | 描述 |
WebviewPanel | 新的 Webview 面板。 |
registerCustomEditorProvider(viewType: string, provider: CustomTextEditorProvider | CustomReadonlyEditorProvider<CustomDocument> | CustomEditorProvider<CustomDocument>, options?: {supportsMultipleEditorsPerDocument: boolean, webviewOptions: WebviewPanelOptions}): Disposable
为 customEditors
扩展点贡献的 viewType
注册自定义编辑器提供程序。
当自定义编辑器打开时,将触发 onCustomEditor:viewType
激活事件。你的扩展必须注册 CustomTextEditorProvider、CustomReadonlyEditorProvider、CustomEditorProvider 作为激活的一部分用于 viewType
。
参数 | 描述 |
---|---|
viewType: string | 自定义编辑器提供程序的唯一标识符。这应该与来自 |
provider: CustomTextEditorProvider | CustomReadonlyEditorProvider<CustomDocument> | CustomEditorProvider<CustomDocument> | 解析自定义编辑器的提供程序。 |
options?: {supportsMultipleEditorsPerDocument: boolean, webviewOptions: WebviewPanelOptions} | 提供程序的选项。 |
返回值 | 描述 |
Disposable | 取消注册提供程序的 Disposable。 |
registerFileDecorationProvider(provider: FileDecorationProvider): Disposable
注册文件装饰提供程序。
参数 | 描述 |
---|---|
provider: FileDecorationProvider | |
返回值 | 描述 |
Disposable | 一个取消注册提供程序的 Disposable。 |
registerTerminalLinkProvider(provider: TerminalLinkProvider<TerminalLink>): Disposable
注册一个提供程序,该提供程序启用终端内链接的检测和处理。
参数 | 描述 |
---|---|
provider: TerminalLinkProvider<TerminalLink> | 提供终端链接的提供程序。 |
返回值 | 描述 |
Disposable | 取消注册提供程序的 Disposable。 |
registerTerminalProfileProvider(id: string, provider: TerminalProfileProvider): Disposable
为贡献的终端配置文件注册一个提供程序。
参数 | 描述 |
---|---|
id: string | 贡献的终端配置文件的 ID。 |
provider: TerminalProfileProvider | 终端配置文件提供程序。 |
返回值 | 描述 |
Disposable | 一个取消注册提供程序的 disposable。 |
registerTreeDataProvider<T>(viewId: string, treeDataProvider: TreeDataProvider<T>): Disposable
为使用扩展点 views
贡献的视图注册一个 TreeDataProvider。这将允许你向 TreeView 贡献数据,并在数据更改时更新。
注意: 要访问 TreeView 并对其执行操作,请使用 createTreeView。
参数 | 描述 |
---|---|
viewId: string | 使用扩展点 |
treeDataProvider: TreeDataProvider<T> | 一个 TreeDataProvider,为视图提供树数据 |
返回值 | 描述 |
Disposable | 一个取消注册 TreeDataProvider 的 disposable。 |
registerUriHandler(handler: UriHandler): Disposable
注册一个能够处理系统范围 uris 的 uri 处理程序。如果打开了多个窗口,则最顶层的窗口将处理 uri。uri 处理程序的作用域限定为它所贡献的扩展;它将只能处理定向到扩展本身的 uri。uri 必须遵守以下规则
- uri 方案必须是
vscode.env.uriScheme
; - uri 授权机构必须是扩展 ID(例如
my.extension
); - uri 路径、查询和片段部分是任意的。
例如,如果 my.extension
扩展注册了 uri 处理程序,则它将仅被允许处理带有前缀 product-name://my.extension
的 uri。
一个扩展在其整个激活生命周期中只能注册一个 uri 处理程序。
- 注意: 存在一个激活事件
onUri
,当定向到当前扩展的 uri 即将被处理时触发。
参数 | 描述 |
---|---|
handler: UriHandler | 要为此扩展注册的 uri 处理程序。 |
返回值 | 描述 |
Disposable | 一个 disposable,用于注销处理程序。 |
registerWebviewPanelSerializer(viewType: string, serializer: WebviewPanelSerializer<unknown>): Disposable
注册一个 webview 面板序列化程序。
支持恢复的扩展应具有 "onWebviewPanel:viewType"
激活事件,并确保在激活期间调用 registerWebviewPanelSerializer
。
对于给定的 viewType
,一次只能注册一个序列化程序。
参数 | 描述 |
---|---|
viewType: string | 可以序列化的 webview 面板的类型。 |
serializer: WebviewPanelSerializer<unknown> | Webview 序列化程序。 |
返回值 | 描述 |
Disposable | 一个 disposable,用于注销序列化程序。 |
registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: {webviewOptions: {retainContextWhenHidden: boolean}}): Disposable
为 webview 视图注册一个新的提供程序。
参数 | 描述 |
---|---|
viewId: string | 视图的唯一 ID。这应与 package.json 中 |
provider: WebviewViewProvider | webview 视图的提供程序。 |
options?: {webviewOptions: {retainContextWhenHidden: boolean}} | |
返回值 | 描述 |
Disposable | 取消注册提供程序的 Disposable。 |
setStatusBarMessage(text: string, hideAfterTimeout: number): Disposable
在状态栏中设置一条消息。这是更强大的状态栏 items 的简写形式。
参数 | 描述 |
---|---|
text: string | 要显示的消息,支持状态栏 items 中的图标替换。 |
hideAfterTimeout: number | 消息将被释放的超时时间(以毫秒为单位)。 |
返回值 | 描述 |
Disposable | 一个 disposable,用于隐藏状态栏消息。 |
setStatusBarMessage(text: string, hideWhenDone: Thenable<any>): Disposable
在状态栏中设置一条消息。这是更强大的状态栏 items 的简写形式。
参数 | 描述 |
---|---|
text: string | 要显示的消息,支持状态栏 items 中的图标替换。 |
hideWhenDone: Thenable<any> | Thenable,当完成(resolve 或 reject)时,消息将被释放。 |
返回值 | 描述 |
Disposable | 一个 disposable,用于隐藏状态栏消息。 |
setStatusBarMessage(text: string): Disposable
在状态栏中设置一条消息。这是更强大的状态栏 items 的简写形式。
注意 状态栏消息会堆叠,并且在不再使用时必须释放它们。
参数 | 描述 |
---|---|
text: string | 要显示的消息,支持状态栏 items 中的图标替换。 |
返回值 | 描述 |
Disposable | 一个 disposable,用于隐藏状态栏消息。 |
showErrorMessage<T extends string>(message: string, ...items: T[]): Thenable<T | undefined>
显示一条错误消息。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showErrorMessage<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
显示一条错误消息。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
options: MessageOptions | 配置消息的行为。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showErrorMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>
显示一条错误消息。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showErrorMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
显示一条错误消息。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
options: MessageOptions | 配置消息的行为。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showInformationMessage<T extends string>(message: string, ...items: T[]): Thenable<T | undefined>
向用户显示一条信息消息。可以选择性地提供一个项目数组,这些项目将呈现为可单击的按钮。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showInformationMessage<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
向用户显示一条信息消息。可以选择性地提供一个项目数组,这些项目将呈现为可单击的按钮。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
options: MessageOptions | 配置消息的行为。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showInformationMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>
显示一条信息消息。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showInformationMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
显示一条信息消息。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
options: MessageOptions | 配置消息的行为。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showInputBox(options?: InputBoxOptions, token?: CancellationToken): Thenable<string | undefined>
打开一个输入框,以向用户请求输入。
如果输入框被取消(例如,按下 ESC 键),则返回值将为 undefined
。否则,返回值将是用户键入的字符串,如果用户未键入任何内容但通过单击“确定”关闭了输入框,则返回值将为空字符串。
参数 | 描述 |
---|---|
options?: InputBoxOptions | 配置输入框的行为。 |
token?: CancellationToken | 一个可用于发出取消信号的令牌。 |
返回值 | 描述 |
Thenable<string | undefined> | 一个 promise,它解析为用户提供的字符串,或者在取消的情况下解析为 |
showNotebookDocument(document: NotebookDocument, options?: NotebookDocumentShowOptions): Thenable<NotebookEditor>
在 notebook editor 中显示给定的 NotebookDocument。
参数 | 描述 |
---|---|
document: NotebookDocument | 要显示的文本文档。 |
options?: NotebookDocumentShowOptions | 编辑器选项,用于配置显示 notebook editor 的行为。 |
返回值 | 描述 |
Thenable<NotebookEditor> | 一个 promise,它解析为一个 notebook editor。 |
showOpenDialog(options?: OpenDialogOptions): Thenable<Uri[] | undefined>
向用户显示一个文件打开对话框,允许选择要打开的文件。
参数 | 描述 |
---|---|
options?: OpenDialogOptions | 控制对话框的选项。 |
返回值 | 描述 |
Thenable<Uri[] | undefined> | 一个 promise,它解析为选定的资源,或者 |
showQuickPick(items: readonly string[] | Thenable<readonly string[]>, options: QuickPickOptions & {canPickMany: true}, token?: CancellationToken): Thenable<string[] | undefined>
显示一个允许多项选择的选择列表。
参数 | 描述 |
---|---|
items: readonly string[] | Thenable<readonly string[]> | 一个字符串数组,或者一个解析为字符串数组的 promise。 |
options: QuickPickOptions & {canPickMany: true} | 配置选择列表的行为。 |
token?: CancellationToken | 一个可用于发出取消信号的令牌。 |
返回值 | 描述 |
Thenable<string[] | undefined> | 一个 promise,它解析为选定的项目,或者 |
showQuickPick(items: readonly string[] | Thenable<readonly string[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<string | undefined>
显示一个选择列表。
参数 | 描述 |
---|---|
items: readonly string[] | Thenable<readonly string[]> | 一个字符串数组,或者一个解析为字符串数组的 promise。 |
options?: QuickPickOptions | 配置选择列表的行为。 |
token?: CancellationToken | 一个可用于发出取消信号的令牌。 |
返回值 | 描述 |
Thenable<string | undefined> | 一个 promise,它解析为选择结果,或者 |
showQuickPick<T extends QuickPickItem>(items: readonly T[] | Thenable<readonly T[]>, options: QuickPickOptions & {canPickMany: true}, token?: CancellationToken): Thenable<T[] | undefined>
显示一个允许多项选择的选择列表。
参数 | 描述 |
---|---|
items: readonly T[] | Thenable<readonly T[]> | 一个项目数组,或者一个解析为项目数组的 promise。 |
options: QuickPickOptions & {canPickMany: true} | 配置选择列表的行为。 |
token?: CancellationToken | 一个可用于发出取消信号的令牌。 |
返回值 | 描述 |
Thenable<T[] | undefined> | 一个 promise,它解析为选定的项目,或者 |
showQuickPick<T extends QuickPickItem>(items: readonly T[] | Thenable<readonly T[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<T | undefined>
显示一个选择列表。
参数 | 描述 |
---|---|
items: readonly T[] | Thenable<readonly T[]> | 一个项目数组,或者一个解析为项目数组的 promise。 |
options?: QuickPickOptions | 配置选择列表的行为。 |
token?: CancellationToken | 一个可用于发出取消信号的令牌。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 promise,它解析为选定的项目,或者 |
showSaveDialog(options?: SaveDialogOptions): Thenable<Uri | undefined>
向用户显示一个文件保存对话框,允许选择要保存的文件。
参数 | 描述 |
---|---|
options?: SaveDialogOptions | 控制对话框的选项。 |
返回值 | 描述 |
Thenable<Uri | undefined> | 一个 promise,它解析为选定的资源,或者 |
showTextDocument(document: TextDocument, column?: ViewColumn, preserveFocus?: boolean): Thenable<TextEditor>
在文本编辑器中显示给定的文档。可以提供 column 来控制编辑器的显示位置。可能会更改 active editor。
参数 | 描述 |
---|---|
document: TextDocument | 要显示的文本文档。 |
column?: ViewColumn | 应在其中显示 editor 的视图列。默认值为 active。不存在的列将根据需要创建,最多为 ViewColumn.Nine。使用 ViewColumn.Beside 将编辑器在当前活动编辑器的侧面打开。 |
preserveFocus?: boolean | 当为 |
返回值 | 描述 |
Thenable<TextEditor> | 一个 promise,它解析为一个 editor。 |
showTextDocument(document: TextDocument, options?: TextDocumentShowOptions): Thenable<TextEditor>
在文本编辑器中显示给定的文档。可以提供 Options 来控制编辑器的显示选项。可能会更改 active editor。
参数 | 描述 |
---|---|
document: TextDocument | 要显示的文本文档。 |
options?: TextDocumentShowOptions | |
返回值 | 描述 |
Thenable<TextEditor> | 一个 promise,它解析为一个 editor。 |
showTextDocument(uri: Uri, options?: TextDocumentShowOptions): Thenable<TextEditor>
openTextDocument(uri).then(document => showTextDocument(document, options))
的简写形式。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
options?: TextDocumentShowOptions | |
返回值 | 描述 |
Thenable<TextEditor> | 一个 promise,它解析为一个 editor。 |
showWarningMessage<T extends string>(message: string, ...items: T[]): Thenable<T | undefined>
显示一条警告消息。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showWarningMessage<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
显示一条警告消息。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
options: MessageOptions | 配置消息的行为。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showWarningMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>
显示一条警告消息。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showWarningMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
显示一条警告消息。
参数 | 描述 |
---|---|
message: string | 要显示的消息。 |
options: MessageOptions | 配置消息的行为。 |
...items: T[] | 一组将在消息中呈现为操作项的项目。 |
返回值 | 描述 |
Thenable<T | undefined> | 一个 thenable,它解析为选定的项目,或者在被关闭时解析为 |
showWorkspaceFolderPick(options?: WorkspaceFolderPickOptions): Thenable<WorkspaceFolder | undefined>
显示一个 workspace folders 的选择列表以供选择。如果未打开任何文件夹,则返回 undefined
。
参数 | 描述 |
---|---|
options?: WorkspaceFolderPickOptions | 配置工作区文件夹列表的行为。 |
返回值 | 描述 |
Thenable<WorkspaceFolder | undefined> | 一个 promise,它解析为工作区文件夹,或者 |
withProgress<R>(options: ProgressOptions, task: (progress: Progress<{increment: number, message: string}>, token: CancellationToken) => Thenable<R>): Thenable<R>
在编辑器中显示进度。在运行给定的回调函数期间以及在其返回的 promise 未被 resolve 或 reject 时,会显示进度。ProgressOptions 定义了应显示进度的位置(和其他详细信息)。
参数 | 描述 |
---|---|
options: ProgressOptions | 一个 ProgressOptions 对象,描述用于显示进度的选项,例如其位置 |
task: (progress: Progress<{increment: number, message: string}>, token: CancellationToken) => Thenable<R> | 一个返回 promise 的回调函数。可以使用提供的 Progress 对象报告进度状态。 要报告离散进度,请使用 要监视操作是否已被用户取消,请使用提供的 CancellationToken。请注意,目前只有 |
返回值 | 描述 |
Thenable<R> | task 回调函数返回的 thenable。 |
withScmProgress<R>(task: (progress: Progress<number>) => Thenable<R>): Thenable<R>
在运行给定回调函数期间以及在其返回的 promise 未被 resolve 或 reject 时,在源代码管理视图中显示进度。
- 已弃用 - 请改用
withProgress
。
工作区
用于处理当前工作区的命名空间。工作区是在编辑器窗口(实例)中打开的一个或多个文件夹的集合。
也可以在没有工作区的情况下打开编辑器。例如,当您通过从平台的文件菜单中选择文件来打开新的编辑器窗口时,您将不在工作区内。在这种模式下,编辑器的某些功能会减少,但您仍然可以打开和编辑文本文件。
有关工作区概念的更多信息,请参阅 https://vscode.js.cn/docs/editor/workspaces。
工作区为 listening 到 fs 事件和 finding 文件提供支持。两者都表现良好并在编辑器进程外部运行,因此应始终使用它们而不是 nodejs 等效项。
变量
fs: FileSystem
一个 file system 实例,允许与本地和远程文件进行交互,例如 vscode.workspace.fs.readDirectory(someUri)
允许检索目录的所有条目,或者 vscode.workspace.fs.stat(anotherUri)
返回文件的元数据。
当为 true 时,用户已显式信任工作区的内容。
工作区的名称。当未打开任何工作区时为 undefined
。
有关工作区概念的更多信息,请参阅 https://vscode.js.cn/docs/editor/workspaces。
notebookDocuments: readonly NotebookDocument[]
编辑器当前已知的所有 notebook 文档。
workspaceFolders 的第一个条目的 uri,类型为 string
。如果没有第一个条目,则为 undefined
。
有关工作区的更多信息,请参阅 https://vscode.js.cn/docs/editor/workspaces。
- 已弃用 - 请改用 workspaceFolders。
textDocuments: readonly TextDocument[]
编辑器当前已知的所有文本文档。
workspaceFile: Uri | undefined
工作区文件的位置,例如
file:///Users/name/Development/myProject.code-workspace
或
untitled:1555503116870
对于未命名且尚未保存的工作区。
根据打开的工作区,该值将为
undefined
当未打开任何工作区时- 否则为工作区文件的路径,类型为
Uri
。如果工作区未命名,则返回的 URI 将使用untitled:
协议
该位置可以例如与 vscode.openFolder
命令一起使用,以便在工作区关闭后重新打开。
示例
vscode.commands.executeCommand('vscode.openFolder', uriOfWorkspace);
有关工作区概念的更多信息,请参阅 https://vscode.js.cn/docs/editor/workspaces。
注意: 不建议使用 workspace.workspaceFile
将配置数据写入文件。您可以为此使用 workspace.getConfiguration().update()
,它在打开单个文件夹以及未命名或已保存的工作区时均可工作。
workspaceFolders: readonly WorkspaceFolder[] | undefined
编辑器中打开的工作区文件夹列表 (0-N)。当未打开任何工作区时为 undefined
。
有关工作区的更多信息,请参阅 https://vscode.js.cn/docs/editor/workspaces。
事件
onDidChangeConfiguration: Event<ConfigurationChangeEvent>
当 配置 更改时发出的事件。
onDidChangeNotebookDocument: Event<NotebookDocumentChangeEvent>
当 笔记本 发生更改时发出的事件。
onDidChangeTextDocument: Event<TextDocumentChangeEvent>
onDidChangeWorkspaceFolders: Event<WorkspaceFoldersChangeEvent>
当添加或删除工作区文件夹时发出的事件。
注意: 如果添加、删除或更改第一个工作区文件夹,则不会触发此事件,因为在这种情况下,当前正在执行的扩展(包括侦听此事件的扩展)将被终止并重新启动,以便(已弃用的)rootPath
属性更新为指向第一个工作区文件夹。
onDidCloseNotebookDocument: Event<NotebookDocument>
onDidCloseTextDocument: Event<TextDocument>
当 文本文件 被释放或文本文件的语言 ID 已更改时发出的事件。
注意 1: 不保证在编辑器选项卡关闭时会触发此事件,请使用 onDidChangeVisibleTextEditors 事件来了解编辑器何时更改。
注意 2: 文档可以打开但未在编辑器中显示,这意味着此事件可能会为未在编辑器中显示的文档触发。
onDidCreateFiles: Event<FileCreateEvent>
当文件已创建时发出的事件。
注意: 此事件由用户手势触发,例如从资源管理器创建文件,或从 workspace.applyEdit API 触发,但当磁盘上的文件更改时,例如由另一个应用程序触发,或使用 workspace.fs API 时,不会 触发此事件。
onDidDeleteFiles: Event<FileDeleteEvent>
当文件已删除时发出的事件。
注意 1: 此事件由用户手势触发,例如从资源管理器删除文件,或从 workspace.applyEdit API 触发,但当磁盘上的文件更改时,例如由另一个应用程序触发,或使用 workspace.fs API 时,不会 触发此事件。
注意 2: 当删除包含子项的文件夹时,仅触发一个事件。
onDidGrantWorkspaceTrust: Event<void>
当当前工作区已被信任时触发的事件。
onDidOpenNotebookDocument: Event<NotebookDocument>
当 笔记本 打开时发出的事件。
onDidOpenTextDocument: Event<TextDocument>
onDidRenameFiles: Event<FileRenameEvent>
当文件已重命名时发出的事件。
注意 1: 此事件由用户手势触发,例如从资源管理器重命名文件,以及从 workspace.applyEdit API 触发,但当磁盘上的文件更改时,例如由另一个应用程序触发,或使用 workspace.fs API 时,不会 触发此事件。
注意 2: 当重命名包含子项的文件夹时,仅触发一个事件。
onDidSaveNotebookDocument: Event<NotebookDocument>
当 笔记本 保存时发出的事件。
onDidSaveTextDocument: Event<TextDocument>
当 文本文件 保存到磁盘时发出的事件。
onWillCreateFiles: Event<FileWillCreateEvent>
当文件正在创建时发出的事件。
注意 1: 此事件由用户手势触发,例如从资源管理器创建文件,或从 workspace.applyEdit API 触发。当磁盘上的文件更改时,例如由另一个应用程序触发,或使用 workspace.fs API 时,不会 触发此事件。
注意 2: 当触发此事件时,无法应用对正在创建的文件的编辑。
onWillDeleteFiles: Event<FileWillDeleteEvent>
当文件正在删除时发出的事件。
注意 1: 此事件由用户手势触发,例如从资源管理器删除文件,或从 workspace.applyEdit API 触发,但当磁盘上的文件更改时,例如由另一个应用程序触发,或使用 workspace.fs API 时,不会 触发此事件。
注意 2: 当删除包含子项的文件夹时,仅触发一个事件。
onWillRenameFiles: Event<FileWillRenameEvent>
当文件正在重命名时发出的事件。
注意 1: 此事件由用户手势触发,例如从资源管理器重命名文件,以及从 workspace.applyEdit API 触发,但当磁盘上的文件更改时,例如由另一个应用程序触发,或使用 workspace.fs API 时,不会 触发此事件。
注意 2: 当重命名包含子项的文件夹时,仅触发一个事件。
onWillSaveNotebookDocument: Event<NotebookDocumentWillSaveEvent>
onWillSaveTextDocument: Event<TextDocumentWillSaveEvent>
函数
applyEdit(edit: WorkspaceEdit, metadata?: WorkspaceEditMetadata): Thenable<boolean>
对一个或多个资源进行更改,或根据给定的 工作区编辑 定义创建、删除和重命名资源。
工作区编辑的所有更改都按照添加的顺序应用。如果在同一位置进行多次文本插入,则这些字符串将按照“插入”的顺序出现在结果文本中,除非它们与资源编辑交错。无效的序列(如“删除文件 a”->“在文件 a 中插入文本”)会导致操作失败。
当应用仅包含文本编辑的工作区编辑时,使用“全有或全无”策略。包含资源创建或删除的工作区编辑会中止操作,例如,当单个编辑失败时,将不会尝试连续编辑。
参数 | 描述 |
---|---|
edit: WorkspaceEdit | 工作区编辑。 |
metadata?: WorkspaceEditMetadata | 编辑的可选 元数据。 |
返回值 | 描述 |
Thenable<boolean> | 一个 thenable,当编辑可以应用时解析。 |
asRelativePath(pathOrUri: string | Uri, includeWorkspaceFolder?: boolean): string
返回相对于工作区文件夹或多个文件夹的路径。
当没有 工作区文件夹 或路径不包含在其中时,将返回输入。
createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher
创建一个文件系统监视器,该监视器根据提供的参数在文件事件(创建、更改、删除)时收到通知。
默认情况下,将递归监视所有打开的 工作区文件夹 以进行文件更改。
可以通过提供带有要监视的 base
路径的 RelativePattern 来为文件监视添加其他路径。如果路径是文件夹且 pattern
很复杂(例如,包含 **
或路径段),则将递归监视它,否则将非递归监视(即,仅报告对路径第一级的更改)。
注意,文件系统中不存在的路径将延迟监视,直到创建,然后根据提供的参数进行监视。如果监视的路径被删除,则监视器将暂停,并且在路径再次创建之前不会报告任何事件。
如果可能,请尽量减少递归监视器的使用,因为递归文件监视会消耗大量资源。
提供 string
作为 globPattern
充当在所有打开的工作区文件夹中监视文件事件的便捷方法。它不能用于为文件监视添加更多文件夹,也不会报告来自不属于打开的工作区文件夹的文件夹的任何文件事件。
可选地,可以提供忽略某些类型事件的标志。
要停止侦听事件,必须释放监视器。
注意,来自递归文件监视器的文件事件可能会根据用户配置排除。设置 files.watcherExclude
有助于减少来自已知会一次产生大量文件更改的文件夹(例如 .git
文件夹)的文件事件开销。因此,强烈建议使用不需要递归监视器的简单模式进行监视,在这种情况下,排除设置将被忽略,您可以完全控制事件。
注意,除非要监视的路径本身是符号链接,否则不会自动跟踪符号链接以进行文件监视。
注意,在不区分大小写的平台(通常是 macOS 和 Windows,但不是 Linux)上,报告为已更改的文件路径可能具有与磁盘上实际大小写不同的大小写。我们允许用户使用任何所需路径大小写打开工作区文件夹,并尝试保留它。这意味着
- 如果路径在任何工作区文件夹内,则路径的大小写将与工作区文件夹的大小写匹配,直到路径的该部分,并与子项的磁盘上的大小写匹配
- 如果路径在任何工作区文件夹之外,则大小写将与为监视提供的路径的大小写匹配。以相同的方式,符号链接将被保留,即,文件事件将报告符号链接的路径,因为它已提供用于监视,而不是目标。
示例
文件监视器的基本结构如下所示
const watcher = vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(<folder>, <pattern>));
watcher.onDidChange(uri => { ... }); // listen to files being changed
watcher.onDidCreate(uri => { ... }); // listen to files/folders being created
watcher.onDidDelete(uri => { ... }); // listen to files/folders getting deleted
watcher.dispose(); // dispose after usage
工作区文件监视
如果您只关心特定工作区文件夹中的文件事件
vscode.workspace.createFileSystemWatcher(
new vscode.RelativePattern(vscode.workspace.workspaceFolders[0], '**/*.js')
);
如果您想监视所有打开的工作区文件夹中的文件事件
vscode.workspace.createFileSystemWatcher('**/*.js');
注意: 如果未打开任何工作区(空窗口),则工作区文件夹数组可以为空。
工作区外文件监视
要监视工作区外部文件夹中 *.js 文件的更改(非递归),请传入指向此类文件夹的 Uri
vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.Uri.file(<path to folder outside workspace>), '*.js'));
并使用复杂的 glob 模式进行递归监视
vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.Uri.file(<path to folder outside workspace>), '**/*.js'));
以下是监视活动编辑器以进行文件更改的示例
vscode.workspace.createFileSystemWatcher(
new vscode.RelativePattern(vscode.window.activeTextEditor.document.uri, '*')
);
参数 | 描述 |
---|---|
globPattern: GlobPattern | 一个 glob 模式,用于控制监视器应报告哪些文件事件。 |
ignoreCreateEvents?: boolean | 忽略文件何时创建。 |
ignoreChangeEvents?: boolean | 忽略文件何时更改。 |
ignoreDeleteEvents?: boolean | 忽略文件何时删除。 |
返回值 | 描述 |
FileSystemWatcher | 新的文件系统监视器实例。不再需要时必须释放。 |
findFiles(include: GlobPattern, exclude?: GlobPattern, maxResults?: number, token?: CancellationToken): Thenable<Uri[]>
参数 | 描述 |
---|---|
include: GlobPattern | |
exclude?: GlobPattern | 一个 glob 模式,用于定义要排除的文件和文件夹。glob 模式将与相对于其工作区的结果匹配的文件路径进行匹配。当为 |
maxResults?: number | 结果的上限。 |
token?: CancellationToken | 一个令牌,可用于向底层搜索引擎发出取消信号。 |
返回值 | 描述 |
Thenable<Uri[]> | 一个 thenable,它解析为资源标识符数组。如果未打开任何 工作区文件夹,则不会返回任何结果。 |
getConfiguration(section?: string, scope?: ConfigurationScope): WorkspaceConfiguration
获取工作区配置对象。
当提供节标识符时,仅返回配置的那部分。节标识符中的点被解释为子访问,例如 { myExt: { setting: { doIt: true }}}
和 getConfiguration('myExt.setting').get('doIt') === true
。
当提供范围时,将返回限定于该范围的配置。范围可以是资源或语言标识符或两者兼而有之。
参数 | 描述 |
---|---|
section?: string | 一个点分隔的标识符。 |
scope?: ConfigurationScope | 请求配置的范围。 |
返回值 | 描述 |
WorkspaceConfiguration | 完整配置或子集。 |
getWorkspaceFolder(uri: Uri): WorkspaceFolder | undefined
返回包含给定 URI 的 工作区文件夹。
- 当给定的 URI 与任何工作区文件夹都不匹配时,返回
undefined
- 当给定的 URI 本身是一个工作区文件夹时,返回输入
参数 | 描述 |
---|---|
uri: Uri | 一个 URI。 |
返回值 | 描述 |
WorkspaceFolder | undefined | 一个工作区文件夹或 |
openNotebookDocument(uri: Uri): Thenable<NotebookDocument>
打开笔记本。如果此笔记本已 加载,将提前返回。否则,将加载笔记本并触发 onDidOpenNotebookDocument 事件。
注意,返回的笔记本的生命周期由编辑器而不是扩展所有。这意味着 onDidCloseNotebookDocument 事件可能在之后任何时间发生。
注意,打开笔记本不会显示笔记本编辑器。此函数仅返回一个笔记本文档,该文档可以在笔记本编辑器中显示,但也可以用于其他用途。
参数 | 描述 |
---|---|
uri: Uri | 要打开的资源。 |
返回值 | 描述 |
Thenable<NotebookDocument> | 一个 Promise,它解析为一个 笔记本 |
openNotebookDocument(notebookType: string, content?: NotebookData): Thenable<NotebookDocument>
打开一个未命名的笔记本。当要保存文档时,编辑器将提示用户输入文件路径。
参数 | 描述 |
---|---|
notebookType: string | 应使用的笔记本类型。 |
content?: NotebookData | 笔记本的初始内容。 |
返回值 | 描述 |
Thenable<NotebookDocument> | 一个 Promise,它解析为一个 笔记本。 |
openTextDocument(uri: Uri): Thenable<TextDocument>
打开文档。如果此文档已打开,将提前返回。否则,将加载文档并触发 didOpen 事件。
file
协议:打开磁盘上的文件 (openTextDocument(Uri.file(path))
)。如果文件不存在或无法加载,则将被拒绝。untitled
协议:打开一个空白的未命名文件,并关联路径 (openTextDocument(Uri.file(path).with({ scheme: 'untitled' }))
)。语言将从文件名派生。- 对于所有其他协议,将咨询贡献的 文本文件内容提供程序 和 文件系统提供程序。
注意,返回的文档的生命周期由编辑器而不是扩展所有。这意味着 onDidClose 事件可能在打开后任何时间发生。
参数 | 描述 |
---|---|
uri: Uri | 标识要打开的资源。 |
返回值 | 描述 |
Thenable<TextDocument> | 一个 Promise,它解析为一个 文档。 |
openTextDocument(path: string): Thenable<TextDocument>
openTextDocument(Uri.file(path))
的简写形式。
参数 | 描述 |
---|---|
path: string | 磁盘上文件的路径。 |
返回值 | 描述 |
Thenable<TextDocument> | 一个 Promise,它解析为一个 文档。 |
openTextDocument(options?: {content: string, language: string}): Thenable<TextDocument>
打开一个未命名的文本文件。当要保存文档时,编辑器将提示用户输入文件路径。options
参数允许指定文档的语言和/或内容。
参数 | 描述 |
---|---|
options?: {content: string, language: string} | 控制文档创建方式的选项。 |
返回值 | 描述 |
Thenable<TextDocument> | 一个 Promise,它解析为一个 文档。 |
registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options?: {isCaseSensitive: boolean, isReadonly: boolean | MarkdownString}): Disposable
为给定的方案注册文件系统提供程序,例如 ftp
。
每个方案只能有一个提供程序,当方案已被另一个提供程序声明或方案被保留时,将抛出错误。
参数 | 描述 |
---|---|
scheme: string | 提供程序注册的 uri-scheme。 |
provider: FileSystemProvider | 文件系统提供程序。 |
options?: {isCaseSensitive: boolean, isReadonly: boolean | MarkdownString} | 关于提供程序的不可变元数据。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions): Disposable
注册一个 notebook serializer。
笔记本序列化器必须通过 notebooks
扩展点进行贡献。当打开笔记本文件时,编辑器将发送 onNotebook:<notebookType>
激活事件,扩展必须返回注册它们的序列化器。
参数 | 描述 |
---|---|
notebookType: string | 一个笔记本。 |
serializer: NotebookSerializer | 一个笔记本序列化器。 |
options?: NotebookDocumentContentOptions | 定义应持久化笔记本的哪些部分的可选上下文选项 |
返回值 | 描述 |
Disposable | 一个 Disposable,当被释放时,它将注销此序列化器。 |
registerTaskProvider(type: string, provider: TaskProvider<Task>): Disposable
注册一个任务提供程序。
- 已弃用 - 请改用
tasks
命名空间上的相应函数
参数 | 描述 |
---|---|
type: string | 此提供程序注册的任务类型。 |
provider: TaskProvider<Task> | 一个任务提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
registerTextDocumentContentProvider(scheme: string, provider: TextDocumentContentProvider): Disposable
注册一个文本文件内容提供程序。
每个方案只能注册一个提供程序。
参数 | 描述 |
---|---|
scheme: string | 要注册的 uri-scheme。 |
provider: TextDocumentContentProvider | 一个内容提供程序。 |
返回值 | 描述 |
Disposable | 一个 Disposable,在被释放时取消注册此提供程序。 |
save(uri: Uri): Thenable<Uri | undefined>
保存由给定资源标识的编辑器,并返回结果资源;如果保存不成功或未找到具有给定资源的编辑器,则返回 undefined
。
注意:必须打开具有所提供资源的编辑器才能保存。
saveAll(includeUntitled?: boolean): Thenable<boolean>
保存所有未保存的文件。
参数 | 描述 |
---|---|
includeUntitled?: boolean | 同时保存在此会话期间创建的文件。 |
返回值 | 描述 |
Thenable<boolean> | 一个 thenable,在文件已保存时解析。对于任何保存失败的文件,将返回 |
saveAs(uri: Uri): Thenable<Uri | undefined>
将由给定资源标识的编辑器另存为用户提供的新文件名,并返回结果资源;如果保存不成功或已取消,或者未找到具有给定资源的编辑器,则返回 undefined
。
注意:必须打开具有所提供资源的编辑器才能另存为。
updateWorkspaceFolders(start: number, deleteCount: number, ...workspaceFoldersToAdd: Array<{name: string, uri: Uri}>): boolean
此方法通过在 vscode.workspace.workspaceFolders
数组中从索引 start
开始的可选 workspaceFoldersToAdd
集合替换 deleteCount
个工作区文件夹。这种“拼接”行为可用于在单个操作中添加、删除和更改工作区文件夹。
注意:在某些情况下,调用此方法可能会导致当前正在执行的扩展(包括调用此方法的扩展)终止并重新启动。例如,当添加、删除或更改第一个工作区文件夹时,(已弃用的)rootPath
属性会更新以指向第一个工作区文件夹。另一种情况是从空工作区或单文件夹工作区过渡到多文件夹工作区(另请参阅:https://vscode.js.cn/docs/editor/workspaces)。
使用 onDidChangeWorkspaceFolders() 事件在工作区文件夹更新时收到通知。
示例:在工作区文件夹末尾添加新的工作区文件夹
workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, { uri: ...});
示例:删除第一个工作区文件夹
workspace.updateWorkspaceFolders(0, 1);
示例:用新的工作区文件夹替换现有的工作区文件夹
workspace.updateWorkspaceFolders(0, 1, { uri: ...});
删除现有工作区文件夹并使用不同的名称再次添加它是有效的,以重命名该文件夹。
注意:多次调用 updateWorkspaceFolders() 而不等待 onDidChangeWorkspaceFolders() 触发是无效的。
AccessibilityInformation
辅助功能信息,用于控制屏幕阅读器行为。
属性
项目获得焦点后,屏幕阅读器要朗读的标签。
定义屏幕阅读器如何与其交互的小部件角色。角色应在特殊情况下设置,例如,当类似树的元素表现得像复选框时。如果未指定角色,编辑器将自动选择适当的角色。有关 aria 角色的更多信息,请参见此处 https://w3c.github.io/aria/#widget_roles
AuthenticationForceNewSessionOptions
使用标志 forceNewSession
调用 authentication.getSession 时要使用的可选选项。
- 已弃用 - 请改用 AuthenticationGetSessionPresentationOptions。
AuthenticationForceNewSessionOptions: AuthenticationGetSessionPresentationOptions
AuthenticationGetSessionOptions
从 AuthenticationProvider 获取 AuthenticationSession 时要使用的选项。
属性
account?: AuthenticationSessionAccountInformation
您想要为其获取会话的帐户。这会传递到身份验证提供程序,用于创建正确的会话。
clearSessionPreference?: boolean
是否应清除现有的会话首选项。
对于支持同时登录多个帐户的身份验证提供程序,当调用 getSession 时,将提示用户选择要使用的帐户。此首选项会被记住,直到使用此标志调用 getSession。
注意:首选项是特定于扩展的。因此,如果一个扩展调用 getSession,它不会影响另一个扩展调用 getSession 的会话首选项。此外,首选项是为当前工作区和全局设置的。这意味着新工作区最初将使用“全局”值,然后当提供此标志时,可以为该工作区设置新值。这也意味着如果新工作区设置此标志,则预先存在的工作区不会丢失其首选项。
默认为 false。
createIfNone?: boolean | AuthenticationGetSessionPresentationOptions
如果没有匹配的会话,是否应执行登录。
如果为 true,则会显示一个模式对话框,询问用户是否登录。如果为 false,则会在帐户活动栏图标上显示一个编号徽章。扩展的条目将添加到菜单下以进行登录。这允许静默提示用户登录。
如果您提供选项,您还将看到对话框,但会提供额外的上下文。
如果存在匹配的会话,但扩展尚未被授予对其的访问权限,则将其设置为 true 也会导致立即显示模式对话框,而 false 会在帐户图标上添加一个编号徽章。
默认为 false。
注意:您不能将此选项与 silent 一起使用。
forceNewSession?: boolean | AuthenticationGetSessionPresentationOptions
即使已经有会话可用,我们是否应该尝试重新身份验证。
如果为 true,则会显示一个模式对话框,询问用户是否再次登录。这主要用于令牌需要重新生成,因为它已丢失某些授权的场景。
如果您提供选项,您还将看到对话框,但会提供额外的上下文。
如果没有现有会话,并且 forceNewSession 为 true,则其行为与 createIfNone 完全相同。
默认为 false。
我们是否应在“帐户”菜单中显示登录指示。
如果为 false,则将在“帐户”菜单上向用户显示一个徽章,其中包含扩展的登录选项。如果为 true,则不会显示任何指示。
默认为 false。
注意:您不能将此选项与任何其他提示用户的选项一起使用,例如 createIfNone。
AuthenticationGetSessionPresentationOptions
使用交互式选项 forceNewSession
和 createIfNone
调用 authentication.getSession 时要使用的可选选项。
属性
当我们要求重新身份验证时,将向用户显示的可选消息。提供关于您为何要求用户重新身份验证的额外上下文可以帮助提高他们接受的可能性。
AuthenticationProvider
用于对服务执行身份验证的提供程序。
事件
onDidChangeSessions: Event<AuthenticationProviderAuthenticationSessionsChangeEvent>
当会话数组发生更改或会话中的数据发生更改时触发的 Event。
方法
createSession(scopes: readonly string[], options: AuthenticationProviderSessionOptions): Thenable<AuthenticationSession>
提示用户登录。
如果登录成功,则应触发 onDidChangeSessions 事件。
如果登录失败,则应返回被拒绝的 Promise。
如果提供程序已指定它不支持多个帐户,则如果已经存在与这些范围匹配的会话,则永远不应调用此方法。
参数 | 描述 |
---|---|
scopes: readonly string[] | 新会话应使用创建的范围(权限)列表。 |
options: AuthenticationProviderSessionOptions | 用于创建会话的其他选项。 |
返回值 | 描述 |
Thenable<AuthenticationSession> | 解析为身份验证会话的 Promise。 |
getSessions(scopes: readonly string[], options: AuthenticationProviderSessionOptions): Thenable<AuthenticationSession[]>
获取会话列表。
参数 | 描述 |
---|---|
scopes: readonly string[] | 范围的可选列表。如果提供,则返回的会话应与这些权限匹配,否则应返回所有会话。 |
options: AuthenticationProviderSessionOptions | 用于获取会话的其他选项。 |
返回值 | 描述 |
Thenable<AuthenticationSession[]> | 解析为身份验证会话数组的 Promise。 |
removeSession(sessionId: string): Thenable<void>
删除与会话 ID 对应的会话。
如果删除成功,则应触发 onDidChangeSessions 事件。
如果无法删除会话,则提供程序应拒绝并显示错误消息。
参数 | 描述 |
---|---|
sessionId: string | 要删除的会话的 ID。 |
返回值 | 描述 |
Thenable<void> |
AuthenticationProviderAuthenticationSessionsChangeEvent
当 AuthenticationSession 被添加、删除或更改时触发的 Event。
属性
added: readonly AuthenticationSession[]
changed: readonly AuthenticationSession[]
AuthenticationProvider 的已更改的 AuthenticationSession。当会话的数据(不包括 ID)更新时,会话会更改。例如,会话刷新会导致为会话设置新的访问令牌。
removed: readonly AuthenticationSession[]
AuthenticationProviderInformation
关于 AuthenticationProvider 的基本信息
属性
身份验证提供程序的唯一标识符。
身份验证提供程序的人类可读名称。
AuthenticationProviderOptions
用于创建 AuthenticationProvider 的选项。
属性
supportsMultipleAccounts?: boolean
是否可以使用此提供程序同时登录到多个帐户。如果未指定,则默认为 false。
AuthenticationProviderSessionOptions
属性
account?: AuthenticationSessionAccountInformation
正在询问的帐户。如果传入此项,则提供程序应尝试仅返回与此帐户相关的会话。
AuthenticationSession
表示当前登录用户的会话。
属性
访问令牌。
account: AuthenticationSessionAccountInformation
与会话关联的帐户。
身份验证会话的标识符。
会话访问令牌授予的权限。可用范围由 AuthenticationProvider 定义。
AuthenticationSessionAccountInformation
与 AuthenticationSession 关联的帐户的信息。
属性
帐户的唯一标识符。
帐户的人类可读名称。
AuthenticationSessionsChangeEvent
当 AuthenticationSession 被添加、删除或更改时触发的 Event。
属性
provider: AuthenticationProviderInformation
AuthenticationProvider,其会话已更改。
AutoClosingPair
描述字符串对,其中在键入开始字符串时将自动插入结束字符串。
属性
键入开始字符串时将自动插入的结束字符串。
notIn?: SyntaxTokenType[]
不应自动关闭该对的一组令牌。
将触发自动插入结束字符串的字符串。
BranchCoverage
包含 StatementCoverage 的分支的覆盖率信息。
构造函数
new BranchCoverage(executed: number | boolean, location?: Range | Position, label?: string): BranchCoverage
参数 | 描述 |
---|---|
executed: number | boolean | 此分支的执行次数,或者一个布尔值,指示如果确切计数未知,是否执行了此分支。如果为零或 false,则该分支将被标记为未覆盖。 |
location?: Range | Position | 分支位置。 |
label?: string | |
返回值 | 描述 |
BranchCoverage |
属性
此分支的执行次数,或者一个布尔值,指示如果确切计数未知,是否执行了此分支。如果为零或 false,则该分支将被标记为未覆盖。
分支的标签,例如,在“未采用 ${label} 分支”的上下文中使用。
分支位置。
Breakpoint
所有断点类型的基类。
构造函数
new Breakpoint(enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): Breakpoint
创建一个新的断点
参数 | 描述 |
---|---|
enabled?: boolean | 是否启用断点。 |
condition?: string | 条件断点的表达式 |
hitCondition?: string | 控制忽略断点命中次数的表达式 |
logMessage?: string | 命中断点时要显示的日志消息 |
返回值 | 描述 |
断点 |
属性
条件断点的可选表达式。
是否启用断点。
一个可选表达式,用于控制忽略断点的命中次数。
断点的唯一 ID。
命中此断点时要记录的可选消息。{} 中的嵌入式表达式由调试适配器内插。
BreakpointsChangeEvent
一个事件,描述 breakpoints 集合的更改。
属性
added: readonly Breakpoint[]
添加的断点。
changed: readonly Breakpoint[]
更改的断点。
removed: readonly Breakpoint[]
删除的断点。
CallHierarchyIncomingCall
表示传入调用,例如方法或构造函数的调用方。
构造函数
new CallHierarchyIncomingCall(item: CallHierarchyItem, fromRanges: Range[]): CallHierarchyIncomingCall
创建一个新的调用对象。
参数 | 描述 |
---|---|
item: CallHierarchyItem | 发出调用的项。 |
fromRanges: Range[] | 调用出现的范围。 |
返回值 | 描述 |
CallHierarchyIncomingCall |
属性
from: CallHierarchyItem
发出调用的项。
fromRanges: Range[]
调用出现的范围。这相对于由 this.from 表示的调用方。
CallHierarchyItem
表示诸如函数或构造函数之类的编程构造,在调用层次结构的上下文中。
构造函数
new CallHierarchyItem(kind: SymbolKind, name: string, detail: string, uri: Uri, range: Range, selectionRange: Range): CallHierarchyItem
创建一个新的调用层级项。
参数 | 描述 |
---|---|
kind: SymbolKind | |
name: string | |
detail: string | |
uri: Uri | |
range: Range | |
selectionRange: Range | |
返回值 | 描述 |
CallHierarchyItem |
属性
此项的更多详细信息,例如函数的签名。
kind: SymbolKind
此项的种类。
此项的名称。
range: Range
包含此符号的范围,不包括前导/尾随空格,但包括所有其他内容,例如注释和代码。
selectionRange: Range
当选择和显示此符号时应被选中和显示的范围,例如函数的名称。必须包含在 range 中。
tags?: readonly SymbolTag[]
此项的标签。
uri: Uri
此项的资源标识符。
CallHierarchyOutgoingCall
表示一个传出的调用,例如从方法调用 getter 或从构造函数调用方法等。
构造函数
new CallHierarchyOutgoingCall(item: CallHierarchyItem, fromRanges: Range[]): CallHierarchyOutgoingCall
创建一个新的调用对象。
参数 | 描述 |
---|---|
item: CallHierarchyItem | 被调用的项 |
fromRanges: Range[] | 调用出现的范围。 |
返回值 | 描述 |
CallHierarchyOutgoingCall |
属性
fromRanges: Range[]
调用此项的范围。这是相对于调用者的范围,例如传递给 provideCallHierarchyOutgoingCalls 的项,而不是 this.to。
被调用的项。
CallHierarchyProvider
调用层级提供程序接口描述了扩展和调用层级功能之间的契约,该功能允许浏览函数、方法、构造函数等的调用和调用者。
方法
prepareCallHierarchy(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<CallHierarchyItem | CallHierarchyItem[]>
通过返回给定文档和位置表示的项来引导调用层级。此项将用作调用图的入口点。当给定位置没有项时,提供程序应返回 undefined
或 null
。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<CallHierarchyItem | CallHierarchyItem[]> | 一个或多个调用层级项,或解析为此项的可 thenable 对象。缺少结果可以通过返回 |
provideCallHierarchyIncomingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult<CallHierarchyIncomingCall[]>
为项提供所有传入调用,例如方法的所有调用者。在图论术语中,这描述了调用图内的有向和带注释的边,例如,给定项是起始节点,结果是可以到达的节点。
参数 | 描述 |
---|---|
item: CallHierarchyItem | 应为其计算传入调用的层级项。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<CallHierarchyIncomingCall[]> | 一组传入调用或解析为此项的可 thenable 对象。缺少结果可以通过返回 |
provideCallHierarchyOutgoingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult<CallHierarchyOutgoingCall[]>
为项提供所有传出调用,例如从给定项调用函数、方法或构造函数的调用。在图论术语中,这描述了调用图内的有向和带注释的边,例如,给定项是起始节点,结果是可以到达的节点。
参数 | 描述 |
---|---|
item: CallHierarchyItem | 应为其计算传出调用的层级项。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<CallHierarchyOutgoingCall[]> | 一组传出调用或解析为此项的可 thenable 对象。缺少结果可以通过返回 |
CancellationError
一种错误类型,应用于指示操作已取消。
此类型可用于响应 取消令牌 被取消,或者当操作被该操作的执行者取消时。
构造函数
new CancellationError(): CancellationError
创建一个新的取消错误。
参数 | 描述 |
---|---|
返回值 | 描述 |
CancellationError |
CancellationToken
取消令牌被传递给异步或长时间运行的操作,以请求取消,例如取消完成项的请求,因为用户继续输入。
要获取 CancellationToken
的实例,请使用 CancellationTokenSource。
属性
isCancellationRequested: boolean
当令牌已被取消时为 true
,否则为 false
。
onCancellationRequested: Event<any>
取消时触发的 事件。
CancellationTokenSource
取消源创建并控制 取消令牌。
构造函数
new CancellationTokenSource(): CancellationTokenSource
参数 | 描述 |
---|---|
返回值 | 描述 |
CancellationTokenSource |
属性
token: CancellationToken
此源的取消令牌。
方法
在令牌上发出取消信号。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
处置对象并释放资源。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
CharacterPair
包含两个字符的元组,例如一对开括号和闭括号。
CharacterPair: [string, string]
ChatContext
传递给参与者的额外上下文。
属性
history: ReadonlyArray<ChatRequestTurn | ChatResponseTurn>
到目前为止,当前聊天会话中的所有聊天消息。目前,仅包含当前参与者的聊天消息。
ChatErrorDetails
表示来自聊天请求的错误结果。
属性
向用户显示的一条错误消息。
如果设置为 true,则部分响应将被模糊处理。
ChatFollowup
参与者建议的后续问题。
属性
默认情况下,后续操作将转到同一参与者/命令。但此属性可以设置为调用不同的命令。
向用户显示的标题。如果未指定,则默认情况下将显示提示。
默认情况下,后续操作将转到同一参与者/命令。但此属性可以设置为通过 ID 调用不同的参与者。后续操作只能调用由同一扩展贡献的参与者。
要发送到聊天的消息。
ChatFollowupProvider
在每次请求后调用一次,以获取建议的后续问题以向用户显示。用户可以单击后续问题以将其发送到聊天。
方法
provideFollowups(result: ChatResult, context: ChatContext, token: CancellationToken): ProviderResult<ChatFollowup[]>
为给定结果提供后续问题。
参数 | 描述 |
---|---|
result: ChatResult | 此对象具有与参与者回调返回的结果相同的属性,包括 |
context: ChatContext | 传递给参与者的额外上下文。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<ChatFollowup[]> |
ChatLanguageModelToolReference
对用户手动附加到其请求的工具的引用,可以使用内联 #
语法,也可以通过回形针按钮作为附件。
属性
工具名称。引用 lm.tools 中列出的工具。
range?: [start: number, end: number]
prompt 中引用的起始索引和结束索引。当未定义时,引用不是提示文本的一部分。
注意,索引考虑了前导 #
字符,这意味着它们可以用于按原样修改提示。
ChatParticipant
聊天参与者可以在聊天会话中由用户使用 前缀调用。当被调用时,它会处理聊天请求,并负责向用户提供响应。ChatParticipant 是使用 chat.createChatParticipant 创建的。
事件
onDidReceiveFeedback: Event<ChatResultFeedback>
每当收到结果的反馈时(例如,当用户对结果进行向上或向下投票时)触发的事件。
传递的 result 保证具有与先前从此聊天参与者的处理程序返回的结果相同的属性。
属性
followupProvider?: ChatFollowupProvider
此提供程序将在每次请求后调用一次,以检索建议的后续问题。
iconPath?: IconPath
UI 中显示的参与者的图标。
此参与者的唯一 ID。
requestHandler: ChatRequestHandler
此参与者的请求处理程序。
方法
处置此参与者并释放资源。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
ChatParticipantToolToken
在处理聊天请求的上下文中调用工具时,可以传递给 lm.invokeTool 的令牌。
ChatParticipantToolToken: never
ChatPromptReference
对用户添加到其聊天请求的值的引用。
属性
此类引用的唯一标识符。
此值的描述,可用于 LLM 提示。
range?: [start: number, end: number]
prompt 中引用的起始索引和结束索引。当未定义时,引用不是提示文本的一部分。
注意,索引考虑了前导 #
字符,这意味着它们可以用于按原样修改提示。
此引用的值。今天使用了 string | Uri | Location
类型,但这在将来可能会扩展。
ChatRequest
对聊天参与者的请求。
属性
为此请求选择的 [ChatCommand 命令](#ChatCommand 命令) 的名称。
model: LanguageModelChat
这是当前在 UI 中选择的模型。扩展可以使用此模型,也可以使用 chat.selectChatModels 来选择另一个模型。不要在此请求的生命周期之外保留此模型。
用户输入的提示。
有关此请求中使用的引用的信息存储在 ChatRequest.references 中。
注意,参与者的 [ChatParticipant.name name](#ChatParticipant.name name) 和 [ChatCommand.name command](#ChatCommand.name command) 不属于提示的一部分。
references: readonly ChatPromptReference[]
提示中引用的引用列表及其值。
注意,提示包含按原样编写的引用,并且由参与者进一步修改提示,例如通过内联引用值或创建指向包含已解析值的标题的链接。引用在提示中按其范围反向排序。这意味着提示中的最后一个引用是此列表中的第一个。这简化了提示的字符串操作。
在处理聊天请求的上下文中调用工具时,可以传递给 lm.invokeTool 的令牌。这会将工具调用与聊天会话关联起来。
toolReferences: readonly ChatLanguageModelToolReference[]
用户附加到其请求的工具列表。
当存在工具引用时,聊天参与者应使用 LanguageModelChatToolMode.Required 发出聊天请求,以强制语言模型为工具生成输入。然后,参与者可以使用 lm.invokeTool 来使用该工具,并将结果附加到其用户提示的请求中。该工具可以为用户的请求贡献有用的额外上下文。
ChatRequestHandler
ChatRequestHandler: (request: ChatRequest, context: ChatContext, response: ChatResponseStream, token: CancellationToken) => ProviderResult<ChatResult | void>
ChatRequestTurn
表示聊天历史记录中的用户请求。
属性
为此请求选择的 [ChatCommand 命令](#ChatCommand 命令) 的名称。
此请求定向到的聊天参与者的 ID。
用户输入的提示。
有关此请求中使用的引用的信息存储在 ChatRequestTurn.references 中。
注意,参与者的 [ChatParticipant.name name](#ChatParticipant.name name) 和 [ChatCommand.name command](#ChatCommand.name command) 不属于提示的一部分。
references: ChatPromptReference[]
此消息中使用的引用。
toolReferences: readonly ChatLanguageModelToolReference[]
附加到此请求的工具列表。
ChatResponseAnchorPart
表示聊天响应的一部分,该部分是锚点,呈现为指向目标的链接。
构造函数
new ChatResponseAnchorPart(value: Uri | Location, title?: string): ChatResponseAnchorPart
创建一个新的 ChatResponseAnchorPart。
参数 | 描述 |
---|---|
value: Uri | Location | 一个 uri 或位置。 |
title?: string | 一个可选的标题,与值一起呈现。 |
返回值 | 描述 |
ChatResponseAnchorPart |
属性
一个可选的标题,与值一起呈现。
此锚点的目标。
ChatResponseCommandButtonPart
表示聊天响应的一部分,该部分是执行命令的按钮。
构造函数
new ChatResponseCommandButtonPart(value: Command): ChatResponseCommandButtonPart
创建一个新的 ChatResponseCommandButtonPart。
参数 | 描述 |
---|---|
value: Command | 单击按钮时将执行的命令。 |
返回值 | 描述 |
ChatResponseCommandButtonPart |
属性
value: Command
单击按钮时将执行的命令。
ChatResponseFileTree
表示聊天响应中的文件树结构。
属性
children?: ChatResponseFileTree[]
如果当前文件树是目录,则为子文件树的数组。
文件或目录的名称。
ChatResponseFileTreePart
表示聊天响应的一部分,该部分是文件树。
构造函数
new ChatResponseFileTreePart(value: ChatResponseFileTree[], baseUri: Uri): ChatResponseFileTreePart
创建一个新的 ChatResponseFileTreePart。
参数 | 描述 |
---|---|
value: ChatResponseFileTree[] | 文件树数据。 |
baseUri: Uri | 此文件树相对于的基准 uri。 |
返回值 | 描述 |
ChatResponseFileTreePart |
属性
baseUri: Uri
此文件树相对于的基准 uri
value: ChatResponseFileTree[]
文件树数据。
ChatResponseMarkdownPart
表示聊天响应的一部分,该部分格式为 Markdown。
构造函数
new ChatResponseMarkdownPart(value: string | MarkdownString): ChatResponseMarkdownPart
创建新的 ChatResponseMarkdownPart。
参数 | 描述 |
---|---|
value: string | MarkdownString | 一个 Markdown 字符串或应被解释为 markdown 的字符串。不支MarkdownString.isTrusted 的布尔形式。 |
返回值 | 描述 |
ChatResponseMarkdownPart |
属性
value: MarkdownString
一个 Markdown 字符串或应被解释为 markdown 的字符串。
ChatResponsePart
表示不同的聊天响应类型。
ChatResponsePart: ChatResponseMarkdownPart | ChatResponseFileTreePart | ChatResponseAnchorPart | ChatResponseProgressPart | ChatResponseReferencePart | ChatResponseCommandButtonPart
ChatResponseProgressPart
表示聊天响应中作为进度消息的部分。
构造函数
new ChatResponseProgressPart(value: string): ChatResponseProgressPart
创建新的 ChatResponseProgressPart。
参数 | 描述 |
---|---|
value: string | 一条进度消息 |
返回值 | 描述 |
ChatResponseProgressPart |
属性
进度消息
ChatResponseReferencePart
表示聊天响应中作为引用的部分,与内容分开呈现。
构造函数
new ChatResponseReferencePart(value: Uri | Location, iconPath?: IconPath): ChatResponseReferencePart
创建新的 ChatResponseReferencePart。
参数 | 描述 |
---|---|
value: Uri | Location | 一个 uri 或 location |
iconPath?: IconPath | UI 中显示的引用图标 |
返回值 | 描述 |
ChatResponseReferencePart |
属性
iconPath?: IconPath
引用的图标。
引用目标。
ChatResponseStream
ChatResponseStream 是参与者能够将内容返回到聊天视图的方式。它提供了几种用于流式传输不同类型内容的方法,这些内容将在聊天视图中以适当的方式呈现。参与者可以使用辅助方法来处理他们想要返回的内容类型,或者实例化一个 ChatResponsePart 并使用通用的 ChatResponseStream.push 方法来返回它。
方法
anchor(value: Uri | Location, title?: string): void
将锚点部分推送到此流。push(new ChatResponseAnchorPart(value, title))
的简写。锚点是对某种类型资源的内联引用。
button(command: Command): void
将命令按钮部分推送到此流。push(new ChatResponseCommandButtonPart(value, title))
的简写。
参数 | 描述 |
---|---|
command: Command | 单击按钮时将执行的命令。 |
返回值 | 描述 |
void |
filetree(value: ChatResponseFileTree[], baseUri: Uri): void
将文件树部分推送到此流。push(new ChatResponseFileTreePart(value))
的简写。
参数 | 描述 |
---|---|
value: ChatResponseFileTree[] | 文件树数据。 |
baseUri: Uri | 此文件树相对于的基准 uri。 |
返回值 | 描述 |
void |
markdown(value: string | MarkdownString): void
将 markdown 部分推送到此流。push(new ChatResponseMarkdownPart(value))
的简写。
参数 | 描述 |
---|---|
value: string | MarkdownString | 一个 Markdown 字符串或应被解释为 markdown 的字符串。不支MarkdownString.isTrusted 的布尔形式。 |
返回值 | 描述 |
void |
将进度部分推送到此流。push(new ChatResponseProgressPart(value))
的简写。
参数 | 描述 |
---|---|
value: string | 一条进度消息 |
返回值 | 描述 |
void |
push(part: ChatResponsePart): void
将一个部分推送到此流。
参数 | 描述 |
---|---|
part: ChatResponsePart | 响应部分,呈现的内容或元数据 |
返回值 | 描述 |
void |
reference(value: Uri | Location, iconPath?: IconPath): void
将引用推送到此流。push(new ChatResponseReferencePart(value))
的简写。
注意 引用不会与响应内联呈现。
ChatResponseTurn
表示聊天参与者在聊天历史记录中的响应。
属性
此响应来自的命令的名称。
此响应来自的聊天参与者的 ID。
response: ReadonlyArray<ChatResponseMarkdownPart | ChatResponseFileTreePart | ChatResponseAnchorPart | ChatResponseCommandButtonPart>
从聊天参与者收到的内容。仅表示代表实际内容(而非元数据)的流部分。
result: ChatResult
从聊天参与者收到的结果。
ChatResult
聊天请求的结果。
属性
errorDetails?: ChatErrorDetails
如果请求导致错误,则此属性定义错误详细信息。
此结果的任意元数据。可以是任何内容,但必须是可 JSON 字符串化的。
ChatResultFeedback
表示用户对结果的反馈。
属性
kind: ChatResultFeedbackKind
收到的反馈类型。
result: ChatResult
用户为其提供反馈的 ChatResult。此对象具有与参与者回调返回的结果相同的属性,包括 metadata
,但不是同一个实例。
ChatResultFeedbackKind
表示收到的用户反馈类型。
枚举成员
用户将结果标记为无用。
用户将结果标记为有用。
Clipboard
剪贴板提供对系统剪贴板的读写访问权限。
方法
将当前剪贴板内容读取为文本。
参数 | 描述 |
---|---|
返回值 | 描述 |
Thenable<string> | 一个 thenable,解析为字符串。 |
writeText(value: string): Thenable<void>
将文本写入剪贴板。
参数 | 描述 |
---|---|
value: string | |
返回值 | 描述 |
Thenable<void> | 一个 thenable,在写入发生时解析。 |
CodeAction
构造函数
new CodeAction(title: string, kind?: CodeActionKind): CodeAction
参数 | 描述 |
---|---|
title: string | 代码操作的标题。 |
kind?: CodeActionKind | 代码操作的种类。 |
返回值 | 描述 |
CodeAction |
属性
command?: Command
此代码操作执行的 Command。
如果此命令抛出异常,编辑器将在编辑器中当前光标位置向用户显示异常消息。
diagnostics?: Diagnostic[]
此代码操作解决的 Diagnostics。
标记代码操作当前无法应用。
禁用的代码操作不会在自动 lightbulb 代码操作菜单中显示。
当用户请求更特定类型的代码操作(例如重构)时,禁用的操作在代码操作菜单中显示为灰色。
如果用户有一个 keybinding,它自动应用代码操作,并且仅返回禁用的代码操作,则编辑器将在编辑器中向用户显示带有
reason
的错误消息。
参数 | 描述 |
---|---|
reason: string | 代码操作当前被禁用的原因的人类可读描述。 这在代码操作 UI 中显示。 |
edit?: WorkspaceEdit
此代码操作执行的 workspace edit。
将此标记为首选操作。首选操作由 auto fix
命令使用,并且可以通过键绑定定位。
如果快速修复正确解决了根本错误,则应将其标记为首选。如果重构是采取操作的最合理选择,则应将其标记为首选。
kind?: CodeActionKind
Kind 的代码操作。
用于过滤代码操作。
此代码操作的简短、人类可读的标题。
CodeActionContext
包含有关运行 code action 的上下文的其他诊断信息。
属性
diagnostics: readonly Diagnostic[]
诊断数组。
only: CodeActionKind
请求返回的操作种类。
不是此种类的操作在 lightbulb 显示之前会被过滤掉。
triggerKind: CodeActionTriggerKind
请求代码操作的原因。
CodeActionKind
代码操作的种类。
种类是由 .
分隔的标识符的层次结构列表,例如 "refactor.extract.function"
。
编辑器使用代码操作种类进行 UI 元素,例如重构上下文菜单。用户还可以使用特定种类和 editor.action.codeAction
命令触发代码操作。
静态
Empty: CodeActionKind
空种类。
Notebook: CodeActionKind
应用于整个笔记本范围的所有代码操作的基本种类。使用此项的 CodeActionKinds 应始终以 notebook.
开头。
这要求为此创建新的 CodeActions 并通过扩展贡献。预先存在的种类不能仅仅将新的 notebook.
前缀添加到它们,因为该功能对于完整的笔记本范围是唯一的。
笔记本 CodeActionKinds 可以初始化为以下任一种(都导致 notebook.source.xyz
)
const newKind = CodeActionKind.Notebook.append(CodeActionKind.Source.append('xyz').value)
const newKind = CodeActionKind.Notebook.append('source.xyz')
示例种类/操作
notebook.source.organizeImports
(可能会将所有导入移动到新的顶部单元格)notebook.source.normalizeVariableNames
(可能会将所有变量重命名为标准化的 casing 格式)
QuickFix: CodeActionKind
快速修复操作的基本种类:quickfix
。
快速修复操作解决代码中的问题,并在正常的代码操作上下文菜单中显示。
Refactor: CodeActionKind
重构操作的基本种类:refactor
重构操作在重构上下文菜单中显示。
RefactorExtract: CodeActionKind
重构提取操作的基本种类:refactor.extract
示例提取操作
- 提取方法
- 提取函数
- 提取变量
- 从类中提取接口
- ...
RefactorInline: CodeActionKind
重构内联操作的基本种类:refactor.inline
示例内联操作
- 内联函数
- 内联变量
- 内联常量
- ...
RefactorMove: CodeActionKind
重构移动操作的基本种类:refactor.move
示例移动操作
- 将函数移动到新文件
- 在类之间移动属性
- 将方法移动到基类
- ...
RefactorRewrite: CodeActionKind
重构重写操作的基本种类:refactor.rewrite
示例重写操作
- 将 JavaScript 函数转换为类
- 添加或删除参数
- 封装字段
- 使方法静态
- ...
Source: CodeActionKind
源操作的基本种类:source
源代码操作应用于整个文件。它们必须显式请求,并且不会在正常的 lightbulb 菜单中显示。源操作可以使用 editor.codeActionsOnSave
在保存时运行,并且也显示在 source
上下文菜单中。
SourceFixAll: CodeActionKind
自动修复源操作的基本种类:source.fixAll
。
修复所有操作会自动修复具有明确修复且不需要用户输入的错误。它们不应抑制错误或执行不安全的修复,例如生成新的类型或类。
SourceOrganizeImports: CodeActionKind
组织导入源操作的基本种类:source.organizeImports
。
构造函数
new CodeActionKind(value: string): CodeActionKind
私有构造函数,使用静态 CodeActionKind.XYZ
从现有的代码操作种类派生。
参数 | 描述 |
---|---|
value: string | 种类的取值,例如 |
返回值 | 描述 |
CodeActionKind |
属性
种类的字符串值,例如 "refactor.extract.function"
。
方法
append(parts: string): CodeActionKind
通过将更具体的选择器附加到当前种类来创建新种类。
不修改当前种类。
参数 | 描述 |
---|---|
parts: string | |
返回值 | 描述 |
CodeActionKind |
contains(other: CodeActionKind): boolean
检查 other
是否是此 CodeActionKind
的子种类。
例如,种类 "refactor.extract"
包含 "refactor.extract"
和 "refactor.extract.function"
,但不包含 "unicorn.refactor.extract"
或 "refactor.extractAll"
或 refactor
。
参数 | 描述 |
---|---|
other: CodeActionKind | 要检查的种类。 |
返回值 | 描述 |
boolean |
intersects(other: CodeActionKind): boolean
检查此代码操作种类是否与 other
相交。
例如,种类 "refactor.extract"
与 refactor
、"refactor.extract"
和 "refactor.extract.function"
相交,但不与 "unicorn.refactor.extract"
或 "refactor.extractAll"
相交。
参数 | 描述 |
---|---|
other: CodeActionKind | 要检查的种类。 |
返回值 | 描述 |
boolean |
CodeActionProvider<T>
为代码提供上下文操作。代码操作通常修复问题或美化/重构代码。
代码操作以几种不同的方式呈现给用户
方法
provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken): ProviderResult<Array<Command | T>>
获取文档中给定范围的代码操作。
仅返回与请求范围的用户相关的代码操作。还要记住返回的代码操作将如何在 UI 中显示。例如,lightbulb 小部件和 Refactor
命令将返回的代码操作显示为列表,因此不要返回大量会使用户不知所措的代码操作。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
range: Range | Selection | 调用命令的选择器或范围。如果操作是在当前活动的编辑器中请求的,则这将始终是 selection。 |
context: CodeActionContext | 提供有关正在请求哪些代码操作的附加信息。您可以使用它来查看编辑器正在请求的特定类型的代码操作,以便返回更相关的操作,并避免返回编辑器将丢弃的不相关的代码操作。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<Array<Command | T>> | 代码操作数组,例如快速修复或重构。缺少结果可以通过返回 出于遗留原因,我们也支持返回 |
resolveCodeAction(codeAction: T, token: CancellationToken): ProviderResult<T>
给定一个代码操作,填写其 edit 属性。对所有其他属性(如标题)的更改将被忽略。具有编辑的代码操作将不会被解析。
注意 返回命令而不是代码操作的代码操作提供程序无法成功实现此函数。返回命令已被弃用,而应返回代码操作。
参数 | 描述 |
---|---|
codeAction: T | 一个代码操作。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T> | 已解析的代码操作或 thenable,它解析为此类操作。返回给定的 |
CodeActionProviderMetadata
关于 CodeActionProvider 提供的代码操作类型的元数据。
属性
documentation?: ReadonlyArray<{command: Command, kind: CodeActionKind}>
一类代码操作的静态文档。
如果满足以下任一条件,则提供程序的文档将显示在代码操作菜单中
编辑器请求
kind
的代码操作。在这种情况下,编辑器将显示与请求的代码操作种类最匹配的文档。例如,如果提供程序同时具有Refactor
和RefactorExtract
的文档,则当用户请求RefactorExtract
的代码操作时,编辑器将使用RefactorExtract
的文档,而不是Refactor
的文档。提供程序返回任何
kind
的代码操作。
每个提供程序最多显示一个文档条目。
providedCodeActionKinds?: readonly CodeActionKind[]
CodeActionProvider 可能返回的 CodeActionKinds 列表。
此列表用于确定是否应调用给定的 CodeActionProvider
。为避免不必要的计算,每个 CodeActionProvider
都应列出使用的 providedCodeActionKinds
。种类列表可以是通用的,例如 [CodeActionKind.Refactor]
,也可以列出提供的每种种类,例如 [CodeActionKind.Refactor.Extract.append('function'), CodeActionKind.Refactor.Extract.append('constant'), ...]
。
CodeActionTriggerKind
请求代码操作的原因。
枚举成员
代码操作是由用户或扩展显式请求的。
代码操作是自动请求的。
这通常在文件中当前选择更改时发生,但也可能在文件内容更改时触发。
CodeLens
构造函数
new CodeLens(range: Range, command?: Command): CodeLens
属性
command?: Command
此代码镜头所代表的命令。
当存在关联命令时为 true
。
range: Range
此代码镜头有效的范围。应仅跨越单行。
CodeLensProvider<T>
代码镜头提供程序向源代码文本添加 commands。命令将显示为源代码文本之间的专用水平线。
事件
onDidChangeCodeLenses?: Event<void>
一个可选事件,用于发出此提供程序的代码镜头已更改的信号。
方法
provideCodeLenses(document: TextDocument, token: CancellationToken): ProviderResult<T[]>
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T[]> | 代码镜头的数组或可解析为此数组的 thenable 对象。缺少结果可以通过返回 |
resolveCodeLens(codeLens: T, token: CancellationToken): ProviderResult<T>
对于每个可见的代码镜头,通常在滚动和调用 compute-lenses 后,将调用此函数。
参数 | 描述 |
---|---|
codeLens: T | 必须解析的代码镜头。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T> | 给定的、已解析的代码镜头或可解析为此代码镜头的 thenable 对象。 |
Color
表示 RGBA 空间中的颜色。
构造函数
new Color(red: number, green: number, blue: number, alpha: number): Color
创建新的颜色实例。
参数 | 描述 |
---|---|
red: number | 红色分量。 |
green: number | 绿色分量。 |
blue: number | 蓝色分量。 |
alpha: number | Alpha 分量。 |
返回值 | 描述 |
Color |
属性
此颜色的 alpha 分量,范围为 [0-1]
。
此颜色的蓝色分量,范围为 [0-1]
。
此颜色的绿色分量,范围为 [0-1]
。
此颜色的红色分量,范围为 [0-1]
。
ColorInformation
表示文档中的颜色范围。
构造函数
new ColorInformation(range: Range, color: Color): ColorInformation
创建新的颜色范围。
参数 | 描述 |
---|---|
range: Range | 颜色出现的范围。不能为空。 |
color: Color | 颜色的值。 |
返回值 | 描述 |
ColorInformation |
属性
color: Color
此颜色范围的实际颜色值。
range: Range
颜色在文档中出现的范围。
ColorPresentation
颜色表示对象描述了 Color 应如何表示为文本,以及从源代码引用它所需的编辑。
对于某些语言,一种颜色可以有多种表示形式,例如,css 可以使用常量 Red
、十六进制值 #ff0000
或 rgba 和 hsla 形式来表示红色。在 csharp 中,其他表示形式适用,例如 System.Drawing.Color.Red
。
构造函数
new ColorPresentation(label: string): ColorPresentation
创建新的颜色表示。
参数 | 描述 |
---|---|
label: string | 此颜色表示的标签。 |
返回值 | 描述 |
ColorPresentation |
属性
additionalTextEdits?: TextEdit[]
选择此颜色表示时应用的附加 text edits 的可选数组。编辑不得与主 edit 或自身重叠。
此颜色表示的标签。它将显示在颜色选择器标题上。默认情况下,这也是选择此颜色表示时插入的文本。
textEdit?: TextEdit
ColorTheme
表示颜色主题。
属性
kind: ColorThemeKind
此颜色主题的种类:浅色、深色、高对比度深色和高对比度浅色。
ColorThemeKind
表示颜色主题种类。
枚举成员
浅色颜色主题。
深色颜色主题。
深色高对比度颜色主题。
浅色高对比度颜色主题。
Command
表示对命令的引用。提供一个标题,该标题将用于在 UI 中表示命令,并且可以选择提供一个参数数组,这些参数将在调用时传递给命令处理函数。
属性
命令处理程序应使用调用的参数。
实际命令处理程序的标识符。
命令的标题,例如 save
。
命令的工具提示,在 UI 中表示时。
Comment
注释显示在编辑器或“注释”面板中,具体取决于其提供方式。
属性
author: CommentAuthorInformation
注释的 作者信息
body: string | MarkdownString
人类可读的注释正文
注释的上下文值。这可以用于贡献注释特定的操作。例如,注释被赋予上下文值 editable
。当使用 menus
扩展点向 comments/comment/title
贡献操作时,您可以为 when
表达式中键 comment
指定上下文值,如 comment == editable
。
"contributes": {
"menus": {
"comments/comment/title": [
{
"command": "extension.deleteComment",
"when": "comment == editable"
}
]
}
}
这将仅为 contextValue
为 editable
的注释显示操作 extension.deleteComment
。
描述 Comment 的可选标签。如果存在,标签将呈现在 authorName 旁边。
mode: CommentMode
注释的 Comment mode
reactions?: CommentReaction[]
Comment 的可选反应
将在注释中显示的可选时间戳。日期将根据用户的区域设置和设置进行格式化。
CommentAuthorInformation
Comment 的作者信息
属性
iconPath?: Uri
作者的可选图标路径
注释作者的显示名称
CommentController
注释控制器能够为编辑器提供 comments 支持,并为用户提供与注释交互的各种方式。
属性
commentingRangeProvider?: CommentingRangeProvider
可选的注释范围提供程序。为任何给定的资源 uri 提供支持注释的 ranges 列表。
如果未提供,用户将无法留下任何注释。
此注释控制器的 ID。
此注释控制器的人类可读标签。
options?: CommentOptions
注释控制器选项
reactionHandler?: (comment: Comment, reaction: CommentReaction) => Thenable<void>
用于在 Comment 上创建和删除反应的可选反应处理程序。
参数 | 描述 |
---|---|
comment: Comment | |
reaction: CommentReaction | |
返回值 | 描述 |
Thenable<void> |
方法
createCommentThread(uri: Uri, range: Range, comments: readonly Comment[]): CommentThread
创建 comment thread。评论线程将在可见的文本编辑器(如果资源匹配)和“注释”面板中创建后显示。
参数 | 描述 |
---|---|
uri: Uri | 线程已在其上创建的文档的 uri。 |
range: Range | 评论线程在文档中位于的范围。 |
comments: readonly Comment[] | 线程的有序注释。 |
返回值 | 描述 |
CommentThread |
释放此注释控制器。
释放后,由此注释控制器创建的所有 comment threads 也将从编辑器和“注释”面板中删除。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
CommentingRangeProvider
CommentController 的注释范围提供程序。
方法
provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult<Range[] | CommentingRanges>
为给定文档提供允许创建新评论线程的范围列表,如果不支持则返回 null
参数 | 描述 |
---|---|
document: TextDocument | |
token: CancellationToken | |
返回值 | 描述 |
ProviderResult<T[] | CommentingRanges> |
CommentingRanges
CommentingRangeProvider 启用注释的范围。
属性
允许向文件添加注释,而无需特定范围。
ranges?: Range[]
允许创建新评论线程的范围。
CommentMode
Comment 的注释模式
枚举成员
显示注释编辑器
显示注释的预览
CommentOptions
表示 comment controller 的 options。
属性
一个可选字符串,在注释输入框获得焦点时显示为占位符。
一个可选字符串,在注释输入框折叠时显示。
CommentReaction
Comment 的反应
属性
注释的 author 是否对此反应做出反应
对此反应做出反应的用户数
iconPath: string | Uri
UI 中显示的反应图标。
反应的人类可读标签
CommentReply
在 comments/commentThread/context
中注册的操作的命令参数。
属性
注释编辑器中的值
thread: CommentThread
活动的 comment thread
CommentRule
描述语言的注释工作方式。
属性
blockComment?: CharacterPair
块注释字符对,如 /* block comment */
行注释标记,如 // this is a comment
CommentThread
comments 的集合,表示文档中特定范围内的对话。
属性
线程是否支持回复。默认为 true。
collapsibleState: CommentThreadCollapsibleState
打开文档时,线程应折叠还是展开。默认为“折叠”。
comments: readonly Comment[]
线程的有序注释。
评论线程的上下文值。这可以用于贡献线程特定的操作。例如,评论线程被赋予上下文值 editable
。当使用 menus
扩展点向 comments/commentThread/title
贡献操作时,您可以为 when
表达式中键 commentThread
指定上下文值,如 commentThread == editable
。
"contributes": {
"menus": {
"comments/commentThread/title": [
{
"command": "extension.deleteCommentThread",
"when": "commentThread == editable"
}
]
}
}
这将仅为 contextValue
为 editable
的评论线程显示操作 extension.deleteCommentThread
。
描述 Comment Thread 的可选人类可读标签
range: Range
评论线程在文档中位于的范围。线程图标将显示在范围的最后一行。设置为未定义时,注释将与文件关联,而不是与特定范围关联。
state?: CommentThreadState
评论线程的可选状态,可能会影响评论的显示方式。
uri: Uri
线程已在其上创建的文档的 uri。
方法
释放此评论线程。
释放后,当合适时,此评论线程将从可见编辑器和“注释”面板中删除。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
CommentThreadCollapsibleState
comment thread 的可折叠状态
枚举成员
确定项目是否折叠
确定项目是否展开
CommentThreadState
评论线程的状态。
枚举成员
未解决的线程状态
已解决的线程状态
CompletionContext
包含有关触发 completion provider 的上下文的附加信息。
属性
触发完成项提供程序的字符。
如果提供程序不是由字符触发的,则为 undefined
。
当触发完成提供程序时,触发字符已在文档中。
triggerKind: CompletionTriggerKind
完成项是如何被触发的。
CompletionItem
完成项表示建议用于完成正在键入的文本的文本片段。
仅从 标签 创建完成项就足够了。在这种情况下,完成项将使用给定的标签或 insertText 替换光标之前的 单词。否则,将使用给定的 edit。
当在编辑器中选择完成项时,其定义的或合成的文本编辑将应用于所有光标/选区,而 additionalTextEdits 将按原样应用。
另请参阅
构造函数
new CompletionItem(label: string | CompletionItemLabel, kind?: CompletionItemKind): CompletionItem
创建一个新的完成项。
完成项必须至少有一个 标签,该标签将用作插入文本以及排序和筛选。
参数 | 描述 |
---|---|
label: string | CompletionItemLabel | 完成项的标签。 |
kind?: CompletionItemKind | 完成项的 种类。 |
返回值 | 描述 |
CompletionItem |
属性
additionalTextEdits?: TextEdit[]
command?: Command
在插入此完成项之后执行的可选 Command。注意,对当前文档的额外修改应使用 additionalTextEdits 属性进行描述。
一组可选字符,当在此完成项处于活动状态时按下这些字符,将首先接受它,然后键入该字符。注意,所有提交字符的 length=1
,多余的字符将被忽略。
一个人类可读的字符串,其中包含关于此项的附加信息,例如类型或符号信息。
documentation?: string | MarkdownString
一个人类可读的字符串,表示文档注释。
insertText?: string | SnippetString
一个字符串或代码片段,在选择此完成项时应插入到文档中。当为 falsy
时,将使用 label。
保持 insertText 的空格不变。默认情况下,编辑器会调整新行的前导空格,使其与接受该项的行的缩进匹配 - 将此项设置为 true
将阻止这种情况发生。
kind?: CompletionItemKind
此完成项的种类。根据种类,编辑器会选择一个图标。
label: string | CompletionItemLabel
此完成项的标签。默认情况下,这也是选择此完成项时插入的文本。
显示时选择此项。注意,只能选择一个完成项,并且编辑器决定选择哪个项。规则是,那些匹配最佳的项中的第一个项被选中。
range?: Range | {inserting: Range, replacing: Range}
tags?: readonly CompletionItemTag[]
此完成项的标签。
textEdit?: TextEdit
- 已弃用 - 请改用
CompletionItem.insertText
和CompletionItem.range
。
一个 edit,在选择此完成项时应用于文档。当提供编辑时,将忽略 insertText 的值。
编辑的 Range 必须是单行,并且与请求完成项的行在同一行上。
CompletionItemKind
完成项种类。
枚举成员
Text
完成项种类。
Method
完成项种类。
Function
完成项种类。
Constructor
完成项种类。
Field
完成项种类。
Variable
完成项种类。
Class
完成项种类。
Interface
完成项种类。
Module
完成项种类。
Property
完成项种类。
Unit
完成项种类。
Value
完成项种类。
Enum
完成项种类。
Keyword
完成项种类。
Snippet
完成项种类。
Color
完成项种类。
File
完成项种类。
Reference
完成项种类。
Folder
完成项种类。
EnumMember
完成项种类。
Constant
完成项种类。
Struct
完成项种类。
Event
完成项种类。
Operator
完成项种类。
TypeParameter
完成项种类。
User
完成项种类。
Issue
完成项种类。
CompletionItemLabel
用于 完成项 的结构化标签。
属性
一个可选字符串,在 CompletionItemLabel.detail 之后以不太突出的方式呈现。应该用于完全限定名称或文件路径。
一个可选字符串,在 label 之后直接以不太突出的方式呈现,没有任何空格。应该用于函数签名或类型注释。
此完成项的标签。
默认情况下,这也是选择此完成项时插入的文本。
CompletionItemProvider<T>
完成项提供程序接口定义了扩展和 IntelliSense 之间的约定。
提供程序可以通过实现 resolveCompletionItem 函数来延迟 detail 和 documentation 属性的计算。但是,初始排序和筛选所需的属性,例如 sortText
、filterText
、insertText
和 range
,在解析期间不得更改。
当用户显式手势或 -取决于配置 - 隐式键入单词或触发字符时,会向提供程序请求完成项。
方法
provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken, context: CompletionContext): ProviderResult<CompletionList<T> | T[]>
为给定的位置和文档提供完成项。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
context: CompletionContext | 完成项是如何被触发的。 |
返回值 | 描述 |
ProviderResult<CompletionList<T> | T[]> | 完成项数组、完成列表 或解析为其中之一的可 thenable 对象。缺少结果可以通过返回 |
resolveCompletionItem(item: T, token: CancellationToken): ProviderResult<T>
给定一个完成项,填充更多数据,例如 文档注释 或 详细信息。
编辑器只会解析完成项一次。
注意,此函数在完成项已在 UI 中显示或已选择要插入的项时调用。因此,任何更改演示文稿(标签、排序、筛选等)或(主要)插入行为 (insertText) 的属性都不能更改。
此函数可能会填充 additionalTextEdits。但是,这意味着项可能在解析完成之前插入,在这种情况下,编辑器将尽最大努力仍然应用这些附加文本编辑。
参数 | 描述 |
---|---|
item: T | 当前在 UI 中处于活动状态的完成项。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T> | 已解析的完成项或解析为此项的可 thenable 对象。返回给定的 |
CompletionItemTag
完成项标签是对完成项的呈现进行微调的额外注释。
枚举成员
将完成项呈现为已过时,通常使用删除线。
CompletionList<T>
表示要在编辑器中呈现的 完成项 的集合。
构造函数
new CompletionList<T extends CompletionItem>(items?: T[], isIncomplete?: boolean): CompletionList<T>
创建一个新的完成列表。
参数 | 描述 |
---|---|
items?: T[] | 完成项。 |
isIncomplete?: boolean | 列表不完整。 |
返回值 | 描述 |
CompletionList<T> |
属性
此列表不完整。进一步键入应导致重新计算此列表。
完成项。
CompletionTriggerKind
完成项提供程序 的触发方式
枚举成员
正常触发完成。
由触发字符触发完成。
TriggerForIncompleteCompletions: 2
由于当前完成列表不完整而重新触发完成
ConfigurationChangeEvent
描述配置更改的事件
方法
affectsConfiguration(section: string, scope?: ConfigurationScope): boolean
检查给定的 section 是否已更改。如果提供了 scope,则检查给定 scope 下的资源的 section 是否已更改。
参数 | 描述 |
---|---|
section: string | 配置名称,支持点分隔名称。 |
scope?: ConfigurationScope | 要检查的 scope。 |
返回值 | 描述 |
boolean | 如果给定的 section 已更改,则返回 |
ConfigurationScope
配置 scope 可以是
- 表示资源的 Uri
- 表示打开的文本文档的 TextDocument
- 表示工作区文件夹的 WorkspaceFolder
- 包含以下内容的对象
uri
:文本文档的可选 UrilanguageId
:文本文档的语言标识符
ConfigurationScope: Uri | TextDocument | WorkspaceFolder | {languageId: string, uri: Uri}
ConfigurationTarget
配置目标
枚举成员
全局配置
工作区配置
工作区文件夹配置
CustomDocument
表示 CustomEditorProvider 使用的自定义文档。
自定义文档仅在给定的 CustomEditorProvider
中使用。CustomDocument
的生命周期由编辑器管理。当不再有对 CustomDocument
的引用时,它将被释放。
属性
uri: Uri
此文档关联的 uri。
方法
释放自定义文档。
当不再有对给定 CustomDocument
的引用时(例如,当与文档关联的所有编辑器都已关闭时),编辑器将调用此方法。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
CustomDocumentBackup
用于 CustomDocument 的备份。
属性
备份的唯一标识符。
从备份打开自定义编辑器时,此 ID 将传递回扩展中的 openCustomDocument
。
方法
删除当前备份。
当明确当前备份不再需要时(例如,当创建新备份或保存文件时),编辑器将调用此方法。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
CustomDocumentBackupContext
用于实现 CustomDocumentBackup 的附加信息。
属性
destination: Uri
建议的文件位置,用于写入新备份。
请注意,您的扩展可以自由忽略此建议,并使用自己的备份策略。
如果编辑器用于当前工作区中的资源,则 destination
将指向 ExtensionContext.storagePath
内的文件。destination
的父文件夹可能不存在,因此请确保在将备份写入此位置之前创建它。
CustomDocumentContentChangeEvent<T>
扩展触发的事件,用于向编辑器发出 CustomDocument 的内容已更改的信号。
属性
更改所针对的文档。
CustomDocumentEditEvent<T>
扩展触发的事件,用于向编辑器发出 CustomDocument 上发生了编辑的信号。
属性
编辑所针对的文档。
描述编辑的显示名称。
这将在撤消/重做操作的 UI 中向用户显示。
方法
重做编辑操作。
当用户重做此编辑时,编辑器将调用此方法。要实现 redo
,您的扩展应将文档和编辑器恢复到编辑器通过 onDidChangeCustomDocument
将此编辑添加到其内部编辑堆栈后立即所处的状态。
参数 | 描述 |
---|---|
返回值 | 描述 |
void | Thenable<void> |
撤消编辑操作。
当用户撤消此编辑时,编辑器将调用此方法。要实现 undo
,您的扩展应将文档和编辑器恢复到编辑器通过 onDidChangeCustomDocument
将此编辑添加到其内部编辑堆栈之前立即所处的状态。
参数 | 描述 |
---|---|
返回值 | 描述 |
void | Thenable<void> |
CustomDocumentOpenContext
关于打开自定义文档的附加信息。
属性
用于从备份还原文档的备份 ID,如果没有备份,则为 undefined
。
如果提供了此 ID,您的扩展应从备份还原编辑器,而不是从用户的工作区读取文件。
untitledDocumentData: Uint8Array
如果 URI 是未命名文件,则将使用该文件的字节数据填充此项
如果提供了此项,您的扩展应使用此字节数据,而不是对传入的 URI 执行 fs API
CustomEditorProvider<T>
使用自定义文档模型的可编辑自定义编辑器的提供程序。
自定义编辑器使用 CustomDocument 作为其文档模型,而不是 TextDocument。这使扩展可以完全控制编辑、保存和备份等操作。
当处理二进制文件或更复杂的情况时,应使用此类型的自定义编辑器。对于简单的基于文本的文档,请改用 CustomTextEditorProvider。
事件
onDidChangeCustomDocument: Event<CustomDocumentEditEvent<T>> | Event<CustomDocumentContentChangeEvent<T>>
发出信号,指示自定义编辑器内部发生了编辑。
每当自定义编辑器中发生编辑时,您的扩展都必须触发此事件。编辑可以是任何内容,从更改某些文本,到裁剪图像,再到重新排序列表。您的扩展可以自由定义什么是编辑以及每个编辑上存储的数据。
触发 onDidChange
会导致编辑器被标记为脏状态。当用户保存或还原文件时,此状态将被清除。
支持撤消/重做的编辑器在每次发生编辑时都必须触发 CustomDocumentEditEvent
。这允许用户使用编辑器的标准键盘快捷键来撤消和重做编辑。如果用户撤消所有编辑到上次保存的状态,编辑器还将编辑器标记为不再是脏状态。
支持编辑但无法使用编辑器标准撤消/重做机制的编辑器必须触发 CustomDocumentContentChangeEvent
。用户清除不支持撤消/重做的编辑器的脏状态的唯一方法是 save
或 revert
文件。
编辑器应仅触发 CustomDocumentEditEvent
事件,或仅触发 CustomDocumentContentChangeEvent
事件。
方法
backupCustomDocument(document: T, context: CustomDocumentBackupContext, cancellation: CancellationToken): Thenable<CustomDocumentBackup>
备份脏自定义文档。
备份用于热退出和防止数据丢失。您的 backup
方法应持久化资源的当前状态,即应用编辑后的状态。最常见的做法是将资源保存到磁盘上的 ExtensionContext.storagePath
中。当编辑器重新加载并且您的自定义编辑器为资源打开时,您的扩展应首先检查是否存在该资源的任何备份。如果存在备份,您的扩展应从备份中加载文件内容,而不是从工作区中的资源加载。
backup
在用户停止编辑文档大约一秒钟后触发。如果用户快速编辑文档,则在编辑停止之前不会调用 backup
。
启用 auto save
时不会调用 backup
(因为自动保存已经持久化了资源)。
参数 | 描述 |
---|---|
document: T | 要备份的文档。 |
context: CustomDocumentBackupContext | 可用于备份文档的信息。 |
cancellation: CancellationToken | 指示当前备份的令牌,因为新的备份即将到来。如何响应取消操作取决于您的扩展。例如,如果您的扩展正在备份一个大型文件,并且该操作需要一段时间才能完成,则您的扩展可能会决定完成正在进行的备份,而不是取消它,以确保编辑器具有一些有效的备份。 |
返回值 | 描述 |
Thenable<CustomDocumentBackup> |
openCustomDocument(uri: Uri, openContext: CustomDocumentOpenContext, token: CancellationToken): T | Thenable<T>
为给定资源创建新文档。
首次为给定资源打开编辑器时,会调用 openCustomDocument
。然后,打开的文档将传递给 resolveCustomEditor
,以便可以向用户显示编辑器。
如果用户打开了其他编辑器,则已打开的 CustomDocument
将被重用。当给定资源的所有编辑器都关闭时,将释放 CustomDocument
。此时打开编辑器将触发对 openCustomDocument
的另一次调用。
参数 | 描述 |
---|---|
uri: Uri | 要打开的文档的 Uri。 |
openContext: CustomDocumentOpenContext | 关于打开自定义文档的附加信息。 |
token: CancellationToken | 指示不再需要结果的取消令牌。 |
返回值 | 描述 |
T | Thenable<T> | 自定义文档。 |
resolveCustomEditor(document: T, webviewPanel: WebviewPanel, token: CancellationToken): void | Thenable<void>
为给定资源解析自定义编辑器。
每当用户为此 CustomEditorProvider
打开新编辑器时,都会调用此方法。
参数 | 描述 |
---|---|
document: T | 正在解析的资源的文档。 |
webviewPanel: WebviewPanel | 用于显示此资源的编辑器 UI 的 webview 面板。 在解析期间,提供程序必须填写内容 webview 面板的初始 html,并挂钩其感兴趣的所有事件侦听器。提供程序还可以保留 |
token: CancellationToken | 指示不再需要结果的取消令牌。 |
返回值 | 描述 |
void | Thenable<void> | 可选的 Thenable,指示自定义编辑器已解析。 |
revertCustomDocument(document: T, cancellation: CancellationToken): Thenable<void>
将自定义文档恢复到其上次保存的状态。
当用户在自定义编辑器中触发 File: Revert File
时,编辑器会调用此方法。(请注意,这仅在使用编辑器的 File: Revert File
命令时使用,而不是在文件的 git revert
上使用)。
要实现 revert
,实现者必须确保 document
的所有编辑器实例(webview)都显示与保存状态相同的文档。这通常意味着从工作区重新加载文件。
参数 | 描述 |
---|---|
document: T | 要恢复的文档。 |
cancellation: CancellationToken | 指示不再需要恢复的令牌。 |
返回值 | 描述 |
Thenable<void> | 指示更改已完成的 Thenable。 |
saveCustomDocument(document: T, cancellation: CancellationToken): Thenable<void>
保存自定义文档。
当用户保存自定义编辑器时,编辑器会调用此方法。当用户在自定义编辑器处于活动状态时触发保存、通过诸如 save all
之类的命令或启用自动保存时,可能会发生这种情况。
要实现 save
,实现者必须持久化自定义编辑器。这通常意味着将自定义文档的文件数据写入磁盘。在 save
完成后,任何关联的编辑器实例将不再标记为脏。
参数 | 描述 |
---|---|
document: T | 要保存的文档。 |
cancellation: CancellationToken | 指示不再需要保存的令牌(例如,如果触发了另一个保存)。 |
返回值 | 描述 |
Thenable<void> | 指示保存已完成的 Thenable。 |
saveCustomDocumentAs(document: T, destination: Uri, cancellation: CancellationToken): Thenable<void>
将自定义文档保存到不同的位置。
当用户在自定义编辑器上触发“另存为”时,编辑器会调用此方法。实现者必须将自定义编辑器持久化到 destination
。
当用户接受另存为时,当前编辑器将被新保存文件的非脏编辑器替换。
参数 | 描述 |
---|---|
document: T | 要保存的文档。 |
destination: Uri | 要保存到的位置。 |
cancellation: CancellationToken | 指示不再需要保存的令牌。 |
返回值 | 描述 |
Thenable<void> | 指示保存已完成的 Thenable。 |
CustomExecution
用于将扩展回调作为任务执行的类。
构造函数
new CustomExecution(callback: (resolvedDefinition: TaskDefinition) => Thenable<Pseudoterminal>): CustomExecution
构造一个 CustomExecution 任务对象。当任务运行时,将执行回调,此时扩展应返回它将“在其中运行”的 Pseudoterminal。任务应等待直到调用 Pseudoterminal.open 后再执行进一步的操作。任务取消应使用 Pseudoterminal.close 处理。当任务完成时,触发 Pseudoterminal.onDidClose。
参数 | 描述 |
---|---|
callback: (resolvedDefinition: TaskDefinition) => Thenable<Pseudoterminal> | 用户启动任务时将调用的回调。任务定义中任何 ${} 样式的变量都将被解析,并作为 |
返回值 | 描述 |
CustomExecution |
CustomReadonlyEditorProvider<T>
使用自定义文档模型的只读自定义编辑器的提供程序。
自定义编辑器使用 CustomDocument 作为其文档模型,而不是 TextDocument。
当处理二进制文件或更复杂的情况时,应使用此类型的自定义编辑器。对于简单的基于文本的文档,请改用 CustomTextEditorProvider。
方法
openCustomDocument(uri: Uri, openContext: CustomDocumentOpenContext, token: CancellationToken): T | Thenable<T>
为给定资源创建新文档。
首次为给定资源打开编辑器时,会调用 openCustomDocument
。然后,打开的文档将传递给 resolveCustomEditor
,以便可以向用户显示编辑器。
如果用户打开了其他编辑器,则已打开的 CustomDocument
将被重用。当给定资源的所有编辑器都关闭时,将释放 CustomDocument
。此时打开编辑器将触发对 openCustomDocument
的另一次调用。
参数 | 描述 |
---|---|
uri: Uri | 要打开的文档的 Uri。 |
openContext: CustomDocumentOpenContext | 关于打开自定义文档的附加信息。 |
token: CancellationToken | 指示不再需要结果的取消令牌。 |
返回值 | 描述 |
T | Thenable<T> | 自定义文档。 |
resolveCustomEditor(document: T, webviewPanel: WebviewPanel, token: CancellationToken): void | Thenable<void>
为给定资源解析自定义编辑器。
每当用户为此 CustomEditorProvider
打开新编辑器时,都会调用此方法。
参数 | 描述 |
---|---|
document: T | 正在解析的资源的文档。 |
webviewPanel: WebviewPanel | 用于显示此资源的编辑器 UI 的 webview 面板。 在解析期间,提供程序必须填写内容 webview 面板的初始 html,并挂钩其感兴趣的所有事件侦听器。提供程序还可以保留 |
token: CancellationToken | 指示不再需要结果的取消令牌。 |
返回值 | 描述 |
void | Thenable<void> | 可选的 Thenable,指示自定义编辑器已解析。 |
CustomTextEditorProvider
基于文本的自定义编辑器的提供程序。
基于文本的自定义编辑器使用 TextDocument 作为其数据模型。这大大简化了自定义编辑器的实现,因为它允许编辑器处理许多常见操作,例如撤消和备份。提供程序负责同步 webview 和 TextDocument
之间的文本更改。
方法
resolveCustomTextEditor(document: TextDocument, webviewPanel: WebviewPanel, token: CancellationToken): void | Thenable<void>
为给定的文本资源解析自定义编辑器。
当用户首次为 CustomTextEditorProvider
打开资源,或者他们使用此 CustomTextEditorProvider
重新打开现有编辑器时,将调用此方法。
参数 | 描述 |
---|---|
document: TextDocument | 要解析的资源的文档。 |
webviewPanel: WebviewPanel | 用于显示此资源的编辑器 UI 的 webview 面板。 在解析期间,提供程序必须填写内容 webview 面板的初始 html,并挂钩其感兴趣的所有事件侦听器。提供程序还可以保留 |
token: CancellationToken | 指示不再需要结果的取消令牌。 |
返回值 | 描述 |
void | Thenable<void> | 指示自定义编辑器已解析的 Thenable。 |
DataTransfer
一个映射,包含对应的传输数据的 mime 类型的映射。
实现 handleDrag
的拖放控制器可以将其他 mime 类型添加到数据传输中。当拖动从同一拖放控制器中的元素发起时,这些额外的 mime 类型将仅包含在 handleDrop
中。
构造函数
new DataTransfer(): DataTransfer
参数 | 描述 |
---|---|
返回值 | 描述 |
DataTransfer |
方法
[iterator](): IterableIterator<[mimeType: string, item: DataTransferItem]>
获取一个新的迭代器,其中包含此数据传输中每个元素的 [mime, item]
对。
参数 | 描述 |
---|---|
返回值 | 描述 |
IterableIterator<[mimeType: string, item: DataTransferItem]> |
forEach(callbackfn: (item: DataTransferItem, mimeType: string, dataTransfer: DataTransfer) => void, thisArg?: any): void
允许迭代数据传输项。
参数 | 描述 |
---|---|
callbackfn: (item: DataTransferItem, mimeType: string, dataTransfer: DataTransfer) => void | 用于迭代数据传输项的回调。 |
thisArg?: any | 调用处理程序函数时使用的 |
返回值 | 描述 |
void |
get(mimeType: string): DataTransferItem
检索给定 mime 类型的数据传输项。
参数 | 描述 |
---|---|
mimeType: string | 要获取数据传输项的 mime 类型,例如 特殊的 mime 类型
|
返回值 | 描述 |
DataTransferItem |
set(mimeType: string, value: DataTransferItem): void
设置 mime 类型到数据传输项的映射。
参数 | 描述 |
---|---|
mimeType: string | 要为其设置数据的 mime 类型。Mime 类型以小写形式存储,查找不区分大小写。 |
value: DataTransferItem | 给定 mime 类型的数据传输项。 |
返回值 | 描述 |
void |
DataTransferFile
与 DataTransferItem 关联的文件。
此类型的实例只能由编辑器创建,而不能由扩展创建。
属性
文件的名称。
uri?: Uri
文件的完整文件路径。
在 web 上可能为 undefined
。
方法
文件的完整文件内容。
参数 | 描述 |
---|---|
返回值 | 描述 |
Thenable<Uint8Array> |
DataTransferItem
封装在拖放操作期间传输的数据。
构造函数
new DataTransferItem(value: any): DataTransferItem
参数 | 描述 |
---|---|
value: any | 在此项上存储的自定义数据。可以使用 DataTransferItem.value 检索。 |
返回值 | 描述 |
DataTransferItem |
属性
在此项上存储的自定义数据。
您可以使用 value
在操作之间共享数据。只要创建 DataTransferItem
的扩展在同一扩展主机中运行,就可以检索原始对象。
方法
asFile(): DataTransferFile
尝试获取与此数据传输项关联的 文件。
请注意,文件对象仅在拖放操作的范围内有效。
参数 | 描述 |
---|---|
返回值 | 描述 |
DataTransferFile | 数据传输的文件,如果该项不是文件或无法访问文件数据,则为 |
获取此项的字符串表示形式。
如果 DataTransferItem.value 是一个对象,则此方法返回 json 字符串化 DataTransferItem.value 值的的结果。
参数 | 描述 |
---|---|
返回值 | 描述 |
Thenable<string> |
DebugAdapter
如果实现了 DebugAdapter 接口,则可以将实现 Debug Adapter Protocol 的调试适配器注册到编辑器。
事件
onDidSendMessage: Event<DebugProtocolMessage>
调试适配器向编辑器发送 Debug Adapter Protocol 消息后触发的事件。消息可以是请求、响应或事件。
方法
释放此对象。
参数 | 描述 |
---|---|
返回值 | 描述 |
any |
handleMessage(message: DebugProtocolMessage): void
处理 Debug Adapter Protocol 消息。消息可以是请求、响应或事件。结果或错误通过 onSendMessage 事件返回。
参数 | 描述 |
---|---|
message: DebugProtocolMessage | Debug Adapter Protocol 消息 |
返回值 | 描述 |
void |
DebugAdapterDescriptor
表示调试适配器的不同类型
DebugAdapterDescriptor: DebugAdapterExecutable | DebugAdapterServer | DebugAdapterNamedPipeServer | DebugAdapterInlineImplementation
DebugAdapterDescriptorFactory
一个调试适配器工厂,用于创建 调试适配器描述符。
方法
createDebugAdapterDescriptor(session: DebugSession, executable: DebugAdapterExecutable): ProviderResult<DebugAdapterDescriptor>
在调试会话开始时调用 'createDebugAdapterDescriptor',以提供有关要使用的调试适配器的详细信息。这些详细信息必须作为 DebugAdapterDescriptor 类型的对象返回。目前支持两种类型的调试适配器
- 调试适配器可执行文件指定为命令路径和参数(请参见 DebugAdapterExecutable),
- 可通过通信端口访问的调试适配器服务器(请参见 DebugAdapterServer)。如果未实现该方法,则默认行为如下: createDebugAdapter(session: DebugSession, executable: DebugAdapterExecutable) { if (typeof session.configuration.debugServer === 'number') { return new DebugAdapterServer(session.configuration.debugServer); } return executable; }
参数 | 描述 |
---|---|
session: DebugSession | 将用于调试适配器的 调试会话。 |
executable: DebugAdapterExecutable | 在 package.json 中指定的调试适配器的可执行文件信息(如果不存在此类信息,则为 undefined)。 |
返回值 | 描述 |
ProviderResult<DebugAdapterDescriptor> | 调试适配器描述符 或 undefined。 |
DebugAdapterExecutable
表示调试适配器可执行文件以及传递给它的可选参数和运行时选项。
构造函数
new DebugAdapterExecutable(command: string, args?: string[], options?: DebugAdapterExecutableOptions): DebugAdapterExecutable
基于可执行程序创建调试适配器的描述。
参数 | 描述 |
---|---|
command: string | 实现调试适配器的命令或可执行文件路径。 |
args?: string[] | 要传递给命令或可执行文件的可选参数。 |
options?: DebugAdapterExecutableOptions | 启动命令或可执行文件时要使用的可选选项。 |
返回值 | 描述 |
DebugAdapterExecutable |
属性
传递给调试适配器可执行文件的参数。默认为空数组。
调试适配器可执行文件的命令或路径。命令必须是可执行文件的绝对路径,或者是要通过 PATH 环境变量查找的命令的名称。特殊值“node”将映射到编辑器的内置 Node.js 运行时。
options?: DebugAdapterExecutableOptions
启动调试适配器时要使用的可选选项。默认为 undefined。
DebugAdapterExecutableOptions
调试适配器可执行文件的选项。
属性
执行的调试适配器的当前工作目录。
执行的程序或 shell 的附加环境。如果省略,则使用父进程的环境。如果提供,则将其与父进程的环境合并。
DebugAdapterInlineImplementation
内联实现的调试适配器描述符。
构造函数
new DebugAdapterInlineImplementation(implementation: DebugAdapter): DebugAdapterInlineImplementation
为调试适配器的内联实现创建描述符。
参数 | 描述 |
---|---|
implementation: DebugAdapter | |
返回值 | 描述 |
DebugAdapterInlineImplementation |
DebugAdapterNamedPipeServer
表示作为基于命名管道(在 Windows 上)/UNIX 域套接字(在非 Windows 上)的服务器运行的调试适配器。
构造函数
new DebugAdapterNamedPipeServer(path: string): DebugAdapterNamedPipeServer
为作为基于命名管道(在 Windows 上)/UNIX 域套接字(在非 Windows 上)的服务器运行的调试适配器创建描述符。
参数 | 描述 |
---|---|
path: string | |
返回值 | 描述 |
DebugAdapterNamedPipeServer |
属性
命名管道/UNIX 域套接字的路径。
DebugAdapterServer
表示作为基于套接字的服务器运行的调试适配器。
构造函数
new DebugAdapterServer(port: number, host?: string): DebugAdapterServer
为作为基于套接字的服务器运行的调试适配器创建描述符。
参数 | 描述 |
---|---|
port: number | |
host?: string | |
返回值 | 描述 |
DebugAdapterServer |
属性
主机。
端口。
DebugAdapterTracker
调试适配器跟踪器是一种跟踪编辑器和调试适配器之间通信的方法。
事件
onDidSendMessage(message: any): void
调试适配器已向编辑器发送 Debug Adapter Protocol 消息。
参数 | 描述 |
---|---|
message: any | |
返回值 | 描述 |
void |
onWillReceiveMessage(message: any): void
调试适配器即将从编辑器接收 Debug Adapter Protocol 消息。
参数 | 描述 |
---|---|
message: any | |
返回值 | 描述 |
void |
与调试适配器的会话即将开始。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
调试适配器会话即将停止。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
方法
调试适配器发生错误。
参数 | 描述 |
---|---|
error: Error | |
返回值 | 描述 |
void |
onExit(code: number, signal: string): void
调试适配器已退出,并带有给定的退出代码或信号。
参数 | 描述 |
---|---|
code: number | |
signal: string | |
返回值 | 描述 |
void |
DebugAdapterTrackerFactory
一个调试适配器工厂,用于创建 调试适配器跟踪器。
方法
createDebugAdapterTracker(session: DebugSession): ProviderResult<DebugAdapterTracker>
在调试会话开始时调用 'createDebugAdapterTracker' 方法,以便返回一个“跟踪器”对象,该对象提供对编辑器和调试适配器之间通信的读取访问权限。
参数 | 描述 |
---|---|
session: DebugSession | 将用于调试适配器跟踪器的 调试会话。 |
返回值 | 描述 |
ProviderResult<DebugAdapterTracker> | 调试适配器跟踪器 或 undefined。 |
DebugConfiguration
调试会话的配置。
属性
调试会话的名称。
调试会话的请求类型。
调试会话的类型。
DebugConfigurationProvider
调试配置提供程序允许向调试服务添加调试配置,并在调试会话开始前解析启动配置。调试配置提供程序通过 debug.registerDebugConfigurationProvider 注册。
方法
provideDebugConfigurations(folder: WorkspaceFolder, token?: CancellationToken): ProviderResult<DebugConfiguration[]>
向调试服务提供 调试配置。如果为同一类型注册了多个调试配置提供程序,则调试配置将以任意顺序连接。
参数 | 描述 |
---|---|
folder: WorkspaceFolder | 工作区文件夹,配置用于该文件夹,或者对于无文件夹设置,则为 |
token?: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<DebugConfiguration[]> | 一个 调试配置 数组。 |
resolveDebugConfiguration(folder: WorkspaceFolder, debugConfiguration: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugConfiguration>
通过填充缺失值或添加/更改/删除属性来解析 调试配置。如果为同一类型注册了多个调试配置提供程序,则 resolveDebugConfiguration 调用将以任意顺序链接,并且初始调试配置将通过链传递。返回 'undefined' 值会阻止调试会话启动。返回 'null' 值会阻止调试会话启动并打开底层的调试配置。
参数 | 描述 |
---|---|
folder: WorkspaceFolder | 配置的来源工作区文件夹,或者对于无文件夹设置,则为 |
debugConfiguration: DebugConfiguration | 要解析的 调试配置。 |
token?: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<DebugConfiguration> | 已解析的调试配置,或 undefined 或 null。 |
resolveDebugConfigurationWithSubstitutedVariables(folder: WorkspaceFolder, debugConfiguration: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugConfiguration>
此钩子在 'resolveDebugConfiguration' 之后直接调用,但所有变量都已被替换。它可用于通过填充缺失值或添加/更改/删除属性来解析或验证 调试配置。如果为同一类型注册了多个调试配置提供程序,则 'resolveDebugConfigurationWithSubstitutedVariables' 调用将以任意顺序链接,并且初始调试配置将通过链传递。返回 'undefined' 值会阻止调试会话启动。返回 'null' 值会阻止调试会话启动并打开底层的调试配置。
参数 | 描述 |
---|---|
folder: WorkspaceFolder | 配置的来源工作区文件夹,或者对于无文件夹设置,则为 |
debugConfiguration: DebugConfiguration | 要解析的 调试配置。 |
token?: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<DebugConfiguration> | 已解析的调试配置,或 undefined 或 null。 |
DebugConfigurationProviderTriggerKind
DebugConfigurationProviderTriggerKind 指定何时触发 DebugConfigurationProvider
的 provideDebugConfigurations
方法。目前有两种情况:为新创建的 launch.json 提供初始调试配置,或者当用户通过 UI(例如,通过“选择并开始调试”命令)请求时提供动态生成的调试配置。当使用 debug.registerDebugConfigurationProvider 注册 DebugConfigurationProvider
时,将使用触发器类型。
枚举成员
调用 DebugConfigurationProvider.provideDebugConfigurations
以便为新创建的 launch.json 提供初始调试配置。
当用户通过 UI(例如,通过“选择并开始调试”命令)请求动态生成的调试配置时,将调用 DebugConfigurationProvider.provideDebugConfigurations
。
DebugConsole
表示调试控制台。
方法
将给定的值附加到调试控制台。
参数 | 描述 |
---|---|
value: string | 字符串,假值将不会被打印。 |
返回值 | 描述 |
void |
appendLine(value: string): void
将给定的值和一个换行符附加到调试控制台。
参数 | 描述 |
---|---|
value: string | 字符串,假值将被打印。 |
返回值 | 描述 |
void |
DebugConsoleMode
调试会话使用的调试控制台模式,请参阅 options。
枚举成员
调试会话应具有单独的调试控制台。
调试会话应与其父会话共享调试控制台。此值对于没有父会话的会话无效。
DebugProtocolBreakpoint
DebugProtocolBreakpoint 是调试适配器协议中定义的 Breakpoint 类型的不透明占位符类型。
DebugProtocolMessage
DebugProtocolMessage 是调试适配器协议中定义的 ProtocolMessage 类型的不透明占位符类型。
DebugProtocolSource
DebugProtocolSource 是调试适配器协议中定义的 Source 类型的不透明占位符类型。
DebugSession
一个调试会话。
属性
configuration: DebugConfiguration
此会话的“已解析”调试配置。“已解析”意味着
- 所有变量都已被替换,并且
- 特定于平台的属性部分已针对匹配平台“展平”,并已为不匹配平台删除。
此调试会话的唯一 ID。
调试会话的名称最初取自 调试配置。任何更改都将正确反映在 UI 中。
parentSession?: DebugSession
此调试会话的父会话(如果它是作为子会话创建的)。
另请参阅 DebugSessionOptions.parentSession
来自 调试配置 的调试会话类型。
workspaceFolder: WorkspaceFolder
此会话的工作区文件夹,或者对于无文件夹设置,则为 undefined
。
方法
customRequest(command: string, args?: any): Thenable<any>
向调试适配器发送自定义请求。
参数 | 描述 |
---|---|
command: string | |
args?: any | |
返回值 | 描述 |
Thenable<any> |
getDebugProtocolBreakpoint(breakpoint: Breakpoint): Thenable<DebugProtocolBreakpoint>
将编辑器中的断点映射到调试会话的调试适配器管理的相应调试适配器协议 (DAP) 断点。如果不存在 DAP 断点(要么是因为编辑器断点尚未注册,要么是因为调试适配器对断点不感兴趣),则返回 undefined
值。
参数 | 描述 |
---|---|
breakpoint: Breakpoint | 编辑器中的 断点。 |
返回值 | 描述 |
Thenable<DebugProtocolBreakpoint> | 解析为调试适配器协议断点或 |
DebugSessionCustomEvent
从 调试会话 收到的自定义调试适配器协议事件。
属性
事件特定信息。
事件类型。
session: DebugSession
接收到自定义事件的 调试会话。
DebugSessionOptions
用于 启动调试会话 的选项。
属性
控制调试会话的父会话是否显示在“调用堆栈”视图中,即使它只有一个子会话。默认情况下,调试会话永远不会隐藏其父会话。如果 compact 为 true,则在“调用堆栈”视图中隐藏具有单个子会话的调试会话,以使树更紧凑。
consoleMode?: DebugConsoleMode
控制此会话应具有单独的调试控制台还是与其父会话共享。对于没有父会话的会话无效。默认为 Separate。
lifecycleManagedByParent?: boolean
控制是否将“重启”等生命周期请求发送到新创建的会话或其父会话。默认情况下(如果该属性为 false 或缺失),生命周期请求将发送到新会话。如果会话没有父会话,则忽略此属性。
控制此会话是否应在不调试的情况下运行,从而忽略断点。如果未指定此属性,则使用父会话(如果存在)中的值。
parentSession?: DebugSession
指定后,新创建的调试会话将注册为此“父”调试会话的“子”会话。
suppressDebugStatusbar?: boolean
如果为 true,则此会话的窗口状态栏颜色将不会更改。
suppressDebugToolbar?: boolean
如果为 true,则此会话将不会显示调试工具栏。
如果为 true,则此会话将不会自动显示调试视图。
suppressSaveBeforeStart?: boolean
如果为 true,则在启动调试会话时不会为打开的编辑器触发保存,而与 debug.saveBeforeStart
设置的值无关。
testRun?: TestRun
向编辑器发出信号,指示调试会话是从测试运行请求启动的。这用于在 UI 操作中链接调试会话和测试运行的生命周期。
DebugStackFrame
表示调试会话中的堆栈帧。
属性
调试协议中堆栈帧的 ID。
session: DebugSession
线程的调试会话。
调试协议中关联线程的 ID。
DebugThread
表示调试会话中的线程。
属性
session: DebugSession
线程的调试会话。
调试协议中关联线程的 ID。
Declaration
Declaration: Location | Location[] | LocationLink[]
DeclarationCoverage
包含声明的覆盖率信息。根据报告程序和语言,这可能是函数、方法或命名空间等类型。
构造函数
new DeclarationCoverage(name: string, executed: number | boolean, location: Range | Position): DeclarationCoverage
参数 | 描述 |
---|---|
name: string | |
executed: number | boolean | 此声明的执行次数,或一个布尔值,指示是否执行(如果确切计数未知)。如果为零或 false,则声明将被标记为未覆盖。 |
location: Range | Position | 声明位置。 |
返回值 | 描述 |
DeclarationCoverage |
属性
此声明的执行次数,或一个布尔值,指示是否执行(如果确切计数未知)。如果为零或 false,则声明将被标记为未覆盖。
声明位置。
声明的名称。
DeclarationProvider
声明提供程序接口定义了扩展和转到声明功能之间的协定。
方法
provideDeclaration(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Declaration>
提供给定位置和文档处符号的声明。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<Declaration> | 声明或解析为声明的 Thenable。缺少结果可以通过返回 |
DecorationInstanceRenderOptions
表示装饰实例的渲染选项。请参阅 DecorationOptions.renderOptions。
属性
after?: ThemableDecorationAttachmentRenderOptions
定义插入到装饰文本之后的附件的渲染选项。
before?: ThemableDecorationAttachmentRenderOptions
定义插入到装饰文本之前的附件的渲染选项。
dark?: ThemableDecorationInstanceRenderOptions
深色主题的覆盖选项。
light?: ThemableDecorationInstanceRenderOptions
浅色主题的覆盖选项。
DecorationOptions
表示 装饰集 中特定装饰的选项。
属性
hoverMessage?: MarkdownString | MarkedString | Array<MarkdownString | MarkedString>
当鼠标悬停在装饰上方时应呈现的消息。
range: Range
应用此装饰的范围。范围不能为空。
renderOptions?: DecorationInstanceRenderOptions
应用于当前装饰的渲染选项。出于性能原因,请保持装饰特定选项的数量较少,并尽可能使用装饰类型。
DecorationRangeBehavior
描述在装饰边缘键入/编辑时的装饰行为。
枚举成员
当在开始或结束处进行编辑时,装饰的范围将扩大。
当在开始或结束处进行编辑时,装饰的范围不会扩大。
当在开始处进行编辑时,装饰的范围将扩大,但在结束处不会。
当在结束处进行编辑时,装饰的范围将扩大,但在开始处不会。
DecorationRenderOptions
表示 文本编辑器装饰 的渲染样式。
属性
after?: ThemableDecorationAttachmentRenderOptions
定义插入到装饰文本之后的附件的渲染选项。
backgroundColor?: string | ThemeColor
装饰的背景颜色。使用 rgba() 并定义透明背景颜色以与其他装饰良好配合。或者,可以 引用 颜色注册表中的颜色。
before?: ThemableDecorationAttachmentRenderOptions
定义插入到装饰文本之前的附件的渲染选项。
将应用于由装饰括起来的文本的 CSS 样式属性。
borderColor?: string | ThemeColor
将应用于由装饰括起来的文本的 CSS 样式属性。最好使用 'border' 来设置一个或多个单独的边框属性。
将应用于由装饰括起来的文本的 CSS 样式属性。最好使用 'border' 来设置一个或多个单独的边框属性。
将应用于由装饰括起来的文本的 CSS 样式属性。最好使用 'border' 来设置一个或多个单独的边框属性。
将应用于由装饰括起来的文本的 CSS 样式属性。最好使用 'border' 来设置一个或多个单独的边框属性。
将应用于由装饰括起来的文本的 CSS 样式属性。最好使用 'border' 来设置一个或多个单独的边框属性。
color?: string | ThemeColor
将应用于由装饰括起来的文本的 CSS 样式属性。
将应用于由装饰括起来的文本的 CSS 样式属性。
dark?: ThemableDecorationRenderOptions
深色主题的覆盖选项。
将应用于由装饰括起来的文本的 CSS 样式属性。
将应用于由装饰括起来的文本的 CSS 样式属性。
gutterIconPath?: string | Uri
一个绝对路径或一个URI,指向要在边槽中渲染的图像。
指定边槽图标的大小。可用值包括 'auto'、'contain'、'cover' 和任何百分比值。更多信息请参考:https://msdn.microsoft.com/en-us/library/jj127316(v=vs.85).aspx
装饰是否也应在行文本后的空白处渲染。默认为 false
。
将应用于由装饰括起来的文本的 CSS 样式属性。
light?: ThemableDecorationRenderOptions
浅色主题的覆盖选项。
将应用于由装饰括起来的文本的 CSS 样式属性。
将应用于由装饰括起来的文本的 CSS 样式属性。
outlineColor?: string | ThemeColor
将应用于装饰所包围文本的 CSS 样式属性。最好使用 'outline' 来设置一个或多个单独的轮廓属性。
将应用于装饰所包围文本的 CSS 样式属性。最好使用 'outline' 来设置一个或多个单独的轮廓属性。
将应用于装饰所包围文本的 CSS 样式属性。最好使用 'outline' 来设置一个或多个单独的轮廓属性。
overviewRulerColor?: string | ThemeColor
概览标尺中装饰的颜色。使用 rgba() 并定义透明颜色以便与其他装饰良好配合。
overviewRulerLane?: OverviewRulerLane
装饰应在概览标尺中渲染的位置。
rangeBehavior?: DecorationRangeBehavior
自定义在装饰范围的边缘发生编辑时装饰的增长行为。默认为 DecorationRangeBehavior.OpenOpen
。
将应用于由装饰括起来的文本的 CSS 样式属性。
Definition
符号的定义,表示为一个或多个 位置。对于大多数编程语言,一个符号只有一个定义位置。
Definition: Location | Location[]
DefinitionLink
关于符号定义位置的信息。
提供关于普通 Location 定义的额外元数据,包括定义符号的范围。
DefinitionLink: LocationLink
DefinitionProvider
定义提供程序接口定义了扩展与转到定义和查看定义功能之间的契约。
方法
provideDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | LocationLink[]>
提供给定位置和文档处符号的定义。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<Definition | LocationLink[]> | 一个定义或一个可以解析为此定义的 thenable 对象。缺少结果可以通过返回 |
Diagnostic
表示一个诊断,例如编译器错误或警告。诊断对象仅在文件的范围内有效。
构造函数
new Diagnostic(range: Range, message: string, severity?: DiagnosticSeverity): Diagnostic
创建一个新的诊断对象。
参数 | 描述 |
---|---|
range: Range | 此诊断适用的范围。 |
message: string | 人类可读的消息。 |
severity?: DiagnosticSeverity | 严重程度,默认为 error。 |
返回值 | 描述 |
Diagnostic |
属性
code?: string | number | {target: Uri, value: string | number}
此诊断的代码或标识符。应用于后续处理,例如在提供 代码操作 时。
人类可读的消息。
range: Range
此诊断适用的范围。
relatedInformation?: DiagnosticRelatedInformation[]
相关诊断信息数组,例如,当作用域内的符号名称冲突时,可以通过此属性标记所有定义。
severity: DiagnosticSeverity
严重程度,默认为 error。
描述此诊断来源的人类可读字符串,例如 'typescript' 或 'super lint'。
tags?: DiagnosticTag[]
关于诊断的附加元数据。
DiagnosticChangeEvent
当诊断更改时触发的事件。
属性
uris: readonly Uri[]
诊断已更改的资源数组。
DiagnosticCollection
诊断集合是一个容器,用于管理一组 诊断。诊断始终限定于诊断集合和资源。
要获取 DiagnosticCollection
的实例,请使用 createDiagnosticCollection。
属性
此诊断集合的名称,例如 typescript
。来自此集合的每个诊断都将与此名称关联。此外,任务框架在定义 问题匹配器 时使用此名称。
方法
从此集合中移除所有诊断。与调用 #set(undefined)
相同;
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
delete(uri: Uri): void
从此集合中移除属于所提供的 uri
的所有诊断。与 #set(uri, undefined)
相同。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
返回值 | 描述 |
void |
释放和释放关联的资源。调用 clear。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
forEach(callback: (uri: Uri, diagnostics: readonly Diagnostic[], collection: DiagnosticCollection) => any, thisArg?: any): void
迭代此集合中的每个条目。
参数 | 描述 |
---|---|
callback: (uri: Uri, diagnostics: readonly Diagnostic[], collection: DiagnosticCollection) => any | 为每个条目执行的函数。 |
thisArg?: any | 调用处理程序函数时使用的 |
返回值 | 描述 |
void |
get(uri: Uri): readonly Diagnostic[]
获取给定资源的诊断。注意,您无法修改从此调用返回的诊断数组。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
返回值 | 描述 |
readonly Diagnostic[] | 一个不可变的 诊断 数组或 |
has(uri: Uri): boolean
检查此集合是否包含给定资源的诊断。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
返回值 | 描述 |
boolean |
|
set(uri: Uri, diagnostics: readonly Diagnostic[]): void
为给定资源分配诊断。将替换该资源的现有诊断。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
diagnostics: readonly Diagnostic[] | 诊断数组或 |
返回值 | 描述 |
void |
set(entries: ReadonlyArray<[Uri, readonly Diagnostic[]]>): void
替换此集合中多个资源的诊断。
注意,相同 uri 的多个元组将被合并,例如 [[file1, [d1]], [file1, [d2]]]
等同于 [[file1, [d1, d2]]]
。如果诊断项为 undefined
,如 [file1, undefined]
中所示,则所有先前的诊断(但不包括后续的诊断)都将被移除。
参数 | 描述 |
---|---|
entries: ReadonlyArray<[Uri, readonly Diagnostic[]]> | 元组数组,例如 |
返回值 | 描述 |
void |
DiagnosticRelatedInformation
表示诊断的相关消息和源代码位置。这应用于指向导致诊断或与诊断相关的代码位置,例如,当在作用域中复制符号时。
构造函数
new DiagnosticRelatedInformation(location: Location, message: string): DiagnosticRelatedInformation
创建一个新的相关诊断信息对象。
参数 | 描述 |
---|---|
location: Location | 位置。 |
message: string | 消息。 |
返回值 | 描述 |
DiagnosticRelatedInformation |
属性
location: Location
此相关诊断信息的位置。
此相关诊断信息的消息。
DiagnosticSeverity
表示诊断的严重程度。
枚举成员
语言规则或其他方式不允许的内容。
可疑但允许的内容。
用于告知但不构成问题的内容。
提示更好的做事方式,例如提出重构建议。
DiagnosticTag
关于诊断类型的附加元数据。
枚举成员
未使用或不必要的代码。
带有此标签的诊断会以淡出方式渲染。淡出量由 "editorUnnecessaryCode.opacity"
主题颜色控制。例如,"editorUnnecessaryCode.opacity": "#000000c0"
将以 75% 的不透明度渲染代码。对于高对比度主题,请使用 "editorUnnecessaryCode.border"
主题颜色来underline不必要的代码,而不是淡出它。
已弃用或过时的代码。
带有此标签的诊断以删除线方式渲染。
Disposable
表示可以释放资源的类型,例如事件监听或计时器。
静态
from(...disposableLikes: Array<{dispose: () => any}>): Disposable
将多个类似 disposable 的对象组合成一个。当您拥有带有 dispose 函数但不是 Disposable
实例的对象时,可以使用此方法。
参数 | 描述 |
---|---|
...disposableLikes: Array<{dispose: () => any}> | 至少具有 |
返回值 | 描述 |
Disposable | 返回一个新的 disposable 对象,该对象在 dispose 时将 dispose 所有提供的 disposables 对象。 |
构造函数
new Disposable(callOnDispose: () => any): Disposable
创建一个新的 disposable 对象,该对象在 dispose 时调用提供的函数。
注意,不会等待异步函数。
参数 | 描述 |
---|---|
callOnDispose: () => any | dispose 某些内容的函数。 |
返回值 | 描述 |
Disposable |
方法
释放此对象。
参数 | 描述 |
---|---|
返回值 | 描述 |
any |
DocumentColorProvider
文档颜色提供程序定义了扩展与编辑器中选取和修改颜色的功能之间的契约。
方法
provideColorPresentations(color: Color, context: {document: TextDocument, range: Range}, token: CancellationToken): ProviderResult<ColorPresentation[]>
为颜色提供 表示。
参数 | 描述 |
---|---|
color: Color | 要显示和插入的颜色。 |
context: {document: TextDocument, range: Range} | 包含附加信息的上下文对象 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<ColorPresentation[]> | 颜色表示数组或可以解析为此数组的 thenable 对象。缺少结果可以通过返回 |
provideDocumentColors(document: TextDocument, token: CancellationToken): ProviderResult<ColorInformation[]>
为给定文档提供颜色。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<ColorInformation[]> | 颜色信息 数组或可以解析为此数组的 thenable 对象。缺少结果可以通过返回 |
DocumentDropEdit
应用于 拖放操作 的编辑操作。
构造函数
new DocumentDropEdit(insertText: string | SnippetString, title?: string, kind?: DocumentDropOrPasteEditKind): DocumentDropEdit
参数 | 描述 |
---|---|
insertText: string | SnippetString | 要在拖放位置插入的文本或代码片段。 |
title?: string | 描述编辑的人类可读标签。 |
kind?: DocumentDropOrPasteEditKind | |
返回值 | 描述 |
DocumentDropEdit |
属性
additionalEdit?: WorkspaceEdit
要在拖放时应用的额外的可选编辑。
insertText: string | SnippetString
要在拖放位置插入的文本或代码片段。
kind?: DocumentDropOrPasteEditKind
描述编辑的人类可读标签。
yieldTo?: readonly DocumentDropOrPasteEditKind[]
控制多个编辑的顺序。如果此提供程序让位于编辑,它将在列表中显示在下方。
DocumentDropEditProvider<T>
处理将资源拖放到文本编辑器中的提供程序。
这允许用户将资源(包括来自外部应用程序的资源)拖放到编辑器中。在拖放文件时,用户可以按住 shift
键将文件拖放到编辑器中,而不是打开它。需要启用 editor.dropIntoEditor.enabled
。
方法
provideDocumentDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, token: CancellationToken): ProviderResult<T | T[]>
提供将拖放内容插入文档的编辑。
参数 | 描述 |
---|---|
document: TextDocument | 发生拖放操作的文档。 |
position: Position | 文档中发生拖放操作的位置。 |
dataTransfer: DataTransfer | 一个 DataTransfer 对象,其中包含关于正在拖放的数据的信息。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T | T[]> | 一个 DocumentDropEdit 或一个可以解析为此对象的 thenable 对象。缺少结果可以通过返回 |
resolveDocumentDropEdit(edit: T, token: CancellationToken): ProviderResult<T>
可选方法,用于在应用编辑之前填充 DocumentDropEdit.additionalEdit。
这对于每个编辑调用一次,如果生成完整的编辑可能需要很长时间,则应使用此方法。Resolve 只能用于更改 DocumentDropEdit.additionalEdit。
参数 | 描述 |
---|---|
edit: T | 要解析的 DocumentDropEdit。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T> | 已解析的编辑或可以解析为此编辑的 thenable 对象。返回给定的 |
DocumentDropEditProviderMetadata
提供关于 DocumentDropEditProvider 如何工作的附加元数据。
属性
dropMimeTypes: readonly string[]
提供程序可以处理的 DataTransfer mime 类型列表。
这可以是精确的 mime 类型,例如 image/png
,也可以是通配符模式,例如 image/*
。
对于从工作台中的资源管理器或其他树视图中拖放的资源,请使用 text/uri-list
。
如果 DataTransfer 中存在任何 文件,则使用 files
指示应调用提供程序。请注意,仅当从编辑器外部(例如从操作系统)拖放内容时,才会创建 DataTransferFile 条目。
providedDropEditKinds?: readonly DocumentDropOrPasteEditKind[]
提供程序可能在 provideDocumentDropEdits 中返回的种类列表。
当请求特定 种类 的编辑时,这用于过滤掉提供程序。
DocumentDropOrPasteEditKind
静态
Empty: DocumentDropOrPasteEditKind
Text: DocumentDropOrPasteEditKind
基本文本编辑的根种类。
此种类应用于将基本文本插入文档的编辑。一个很好的例子是粘贴剪贴板文本的编辑,同时还根据粘贴的文本更新文件中的导入。为此,我们可以使用诸如 text.updateImports.someLanguageId
之类的种类。
即使大多数拖放/粘贴编辑最终都会插入文本,您也不应将 Text 用作每个编辑的基本种类,因为这是冗余的。相反,应使用更具体的种类来描述要插入的内容类型。例如,如果编辑添加了 Markdown 链接,请使用 markdown.link
,因为即使要插入的内容是文本,更重要的是要知道该编辑插入了 Markdown 语法。
TextUpdateImports: DocumentDropOrPasteEditKind
用于在文档中更新导入以及插入文本的编辑的根种类。
构造函数
new DocumentDropOrPasteEditKind(value: string): DocumentDropOrPasteEditKind
参数 | 描述 |
---|---|
value: string | |
返回值 | 描述 |
DocumentDropOrPasteEditKind |
属性
种类的原始字符串值。
方法
append(...parts: string[]): DocumentDropOrPasteEditKind
通过将其他作用域附加到当前种类来创建新种类。
不修改当前种类。
参数 | 描述 |
---|---|
...parts: string[] | |
返回值 | 描述 |
DocumentDropOrPasteEditKind |
contains(other: DocumentDropOrPasteEditKind): boolean
检查 other
是否是此 DocumentDropOrPasteEditKind
的子种类。
例如,种类 "text.plain"
包含 "text.plain"
和 "text.plain.list"
,但不包含 "text"
或 "unicorn.text.plain"
。
参数 | 描述 |
---|---|
other: DocumentDropOrPasteEditKind | 要检查的种类。 |
返回值 | 描述 |
boolean |
intersects(other: DocumentDropOrPasteEditKind): boolean
检查此种类是否与 other
相交。
例如,种类 "text.plain"
与 text
、"text.plain"
和 "text.plain.list"
相交,但不与 "unicorn"
或 "textUnicorn.plain"
相交。
参数 | 描述 |
---|---|
other: DocumentDropOrPasteEditKind | 要检查的种类。 |
返回值 | 描述 |
boolean |
DocumentFilter
文档过滤器通过不同的属性来表示文档,例如 语言、其资源的 方案 或应用于 路径 的 glob 模式。
示例 应用于磁盘上 typescript 文件的语言过滤器
{ language: 'typescript', scheme: 'file' }
示例 应用于所有 package.json 路径的语言过滤器
{ language: 'json', pattern: '**/package.json' }
属性
语言 ID,例如 typescript
。
pattern?: GlobPattern
一个 Uri scheme,例如 file
或 untitled
。
DocumentFormattingEditProvider
文档格式化提供程序接口定义了扩展和格式化功能之间的约定。
方法
provideDocumentFormattingEdits(document: TextDocument, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>
为整个文档提供格式化编辑。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
options: FormattingOptions | 控制格式化的选项。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<TextEdit[]> | 一组文本编辑或一个可解析为此的 thenable 对象。 缺少结果可以通过返回 |
DocumentHighlight
文档高亮是文本文档中值得特别关注的范围。 通常,文档高亮通过更改其范围的背景颜色来可视化。
构造函数
new DocumentHighlight(range: Range, kind?: DocumentHighlightKind): DocumentHighlight
创建一个新的文档高亮对象。
参数 | 描述 |
---|---|
range: Range | 高亮适用的范围。 |
kind?: DocumentHighlightKind | 高亮类型,默认为 text。 |
返回值 | 描述 |
DocumentHighlight |
属性
kind?: DocumentHighlightKind
高亮类型,默认为 text。
range: Range
此高亮适用的范围。
DocumentHighlightKind
文档高亮类型。
枚举成员
文本出现。
符号的读取访问,例如读取变量。
符号的写入访问,例如写入变量。
DocumentHighlightProvider
文档高亮提供程序接口定义了扩展和单词高亮功能之间的约定。
方法
provideDocumentHighlights(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<DocumentHighlight[]>
提供一组文档高亮,例如变量的所有出现或函数的所有出口点。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<DocumentHighlight[]> | 文档高亮的数组或一个可解析为此的 thenable 对象。 缺少结果可以通过返回 |
DocumentLink
文档链接是文本文档中链接到内部或外部资源(例如另一个文本文档或网站)的范围。
构造函数
new DocumentLink(range: Range, target?: Uri): DocumentLink
创建一个新的文档链接。
参数 | 描述 |
---|---|
range: Range | 文档链接适用的范围。 不能为空。 |
target?: Uri | 文档链接指向的 uri。 |
返回值 | 描述 |
DocumentLink |
属性
range: Range
此链接适用的范围。
target?: Uri
此链接指向的 uri。
当您悬停在此链接上时显示的工具提示文本。
如果提供了工具提示,它将显示在一个字符串中,该字符串包含有关如何触发链接的说明,例如 {0} (ctrl + click)
。 具体说明因操作系统、用户设置和本地化而异。
DocumentLinkProvider<T>
文档链接提供程序定义了扩展和在编辑器中显示链接的功能之间的约定。
方法
provideDocumentLinks(document: TextDocument, token: CancellationToken): ProviderResult<T[]>
为给定文档提供链接。 请注意,编辑器附带一个默认提供程序,用于检测 http(s)
和 file
链接。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T[]> | 一个 文档链接 数组或一个可解析为此的 thenable 对象。 缺少结果可以通过返回 |
resolveDocumentLink(link: T, token: CancellationToken): ProviderResult<T>
给定一个链接,填写其 target。 当在 UI 中选择不完整的链接时,将调用此方法。 提供程序可以实现此方法,并从 provideDocumentLinks 方法返回不完整的链接(没有 target),这通常有助于提高性能。
参数 | 描述 |
---|---|
link: T | 要解析的链接。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T> |
DocumentPasteEdit
应用粘贴操作的编辑。
构造函数
new DocumentPasteEdit(insertText: string | SnippetString, title: string, kind: DocumentDropOrPasteEditKind): DocumentPasteEdit
创建一个新的粘贴编辑。
参数 | 描述 |
---|---|
insertText: string | SnippetString | 要在粘贴位置插入的文本或代码片段。 |
title: string | 描述编辑的人类可读标签。 |
kind: DocumentDropOrPasteEditKind | |
返回值 | 描述 |
DocumentPasteEdit |
属性
additionalEdit?: WorkspaceEdit
粘贴时应用的 可选的附加编辑。
insertText: string | SnippetString
要在粘贴位置插入的文本或代码片段。
如果您的编辑需要更高级的插入逻辑,请将此项设置为空字符串,并提供 附加编辑 作为替代。
kind: DocumentDropOrPasteEditKind
描述编辑的人类可读标签。
yieldTo?: readonly DocumentDropOrPasteEditKind[]
当可以潜在地应用多个粘贴编辑时,控制排序。
如果此编辑让位于另一个编辑,它将在向用户显示的可能粘贴编辑列表中显示在较低的位置。
DocumentPasteEditContext
有关粘贴操作的附加信息。
属性
only: DocumentDropOrPasteEditKind
要返回的请求的粘贴编辑类型。
当通过 PasteAs 请求显式类型时,鼓励提供程序在生成请求类型的编辑时更加灵活。
triggerKind: DocumentPasteTriggerKind
请求粘贴编辑的原因。
DocumentPasteEditProvider<T>
当用户在 TextDocument 中复制或粘贴时调用的提供程序。
方法
prepareDocumentPaste(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, token: CancellationToken): void | Thenable<void>
用户从 文本编辑器 复制后调用的可选方法。
这允许提供程序将有关复制文本的元数据附加到 DataTransfer。 然后,此数据传输在 provideDocumentPasteEdits 中传递回提供程序。
请注意,当前对 DataTransfer 的任何更改都隔离到当前编辑器窗口。 这意味着其他编辑器窗口或其他应用程序看不到任何添加的元数据。
参数 | 描述 |
---|---|
document: TextDocument | 复制发生的文本文档。 |
ranges: readonly Range[] | 在 document 中复制的范围。 |
dataTransfer: DataTransfer | 与复制关联的数据传输。 您可以在此对象上存储其他值,以供稍后在 provideDocumentPasteEdits 中使用。 此对象仅在此方法持续期间有效。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
void | Thenable<void> | 可选的 thenable 对象,当对 |
provideDocumentPasteEdits(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, context: DocumentPasteEditContext, token: CancellationToken): ProviderResult<T[]>
在用户粘贴到 文本编辑器 之前调用。
返回的编辑可以替换标准粘贴行为。
参数 | 描述 |
---|---|
document: TextDocument | 要粘贴到的文档 |
ranges: readonly Range[] | document 中要粘贴到的范围。 |
dataTransfer: DataTransfer | 与粘贴关联的 数据传输。 此对象仅在粘贴操作期间有效。 |
context: DocumentPasteEditContext | 粘贴的附加上下文。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T[]> | 可以应用粘贴的潜在 编辑 集合。 一次只应用一个返回的 DocumentPasteEdit。 如果从所有提供程序返回多个编辑,则会自动应用第一个编辑,并显示一个小部件,允许用户切换到其他编辑。 |
resolveDocumentPasteEdit(pasteEdit: T, token: CancellationToken): ProviderResult<T>
可选方法,在应用编辑之前填写 DocumentPasteEdit.additionalEdit。
这对于每个编辑调用一次,如果生成完整编辑可能需要很长时间,则应使用此方法。 Resolve 只能用于更改 DocumentPasteEdit.insertText 或 DocumentPasteEdit.additionalEdit。
参数 | 描述 |
---|---|
pasteEdit: T | 要解析的 DocumentPasteEdit。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T> | 解析的粘贴编辑或一个可解析为此的 thenable 对象。 返回给定的 |
DocumentPasteProviderMetadata
提供有关 DocumentPasteEditProvider 工作方式的附加元数据。
属性
copyMimeTypes?: readonly string[]
prepareDocumentPaste 在复制时可能添加的 Mime 类型。
pasteMimeTypes?: readonly string[]
应为之调用 provideDocumentPasteEdits 的 Mime 类型。
这可以是精确的 mime 类型,例如 image/png
,也可以是通配符模式,例如 image/*
。
对于从工作台中的资源管理器或其他树视图中拖放的资源,请使用 text/uri-list
。
使用 files
指示如果 DataTransfer 中存在任何 文件,则应调用提供程序。 请注意,仅当从编辑器外部(例如从操作系统)粘贴内容时,才会创建 DataTransferFile 条目。
providedPasteEditKinds: readonly DocumentDropOrPasteEditKind[]
提供程序可能在 provideDocumentPasteEdits 中返回的 类型 列表。
当请求特定 种类 的编辑时,这用于过滤掉提供程序。
DocumentPasteTriggerKind
请求粘贴编辑的原因。
枚举成员
粘贴是作为正常粘贴操作的一部分请求的。
粘贴是用户通过 paste as
命令请求的。
DocumentRangeFormattingEditProvider
文档格式化提供程序接口定义了扩展和格式化功能之间的约定。
方法
provideDocumentRangeFormattingEdits(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>
为文档中的范围提供格式化编辑。
给定的范围是一个提示,提供程序可以决定格式化更小或更大的范围。 通常,这是通过将范围的开始和结束调整为完整的语法节点来完成的。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
range: Range | 应格式化的范围。 |
options: FormattingOptions | 控制格式化的选项。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<TextEdit[]> | 一组文本编辑或一个可解析为此的 thenable 对象。 缺少结果可以通过返回 |
provideDocumentRangesFormattingEdits(document: TextDocument, ranges: Range[], options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>
为文档中的多个范围提供格式化编辑。
此函数是可选的,但允许格式化程序在仅格式化修改后的范围或格式化大量选择时执行得更快。
给定的范围是提示,提供程序可以决定格式化更小或更大的范围。 通常,这是通过将范围的开始和结束调整为完整的语法节点来完成的。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
ranges: Range[] | 应格式化的范围。 |
options: FormattingOptions | 控制格式化的选项。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<TextEdit[]> | 一组文本编辑或一个可解析为此的 thenable 对象。 缺少结果可以通过返回 |
DocumentRangeSemanticTokensProvider
文档范围语义令牌提供程序接口定义了扩展和语义令牌之间的约定。
方法
provideDocumentRangeSemanticTokens(document: TextDocument, range: Range, token: CancellationToken): ProviderResult<SemanticTokens>
参数 | 描述 |
---|---|
document: TextDocument | |
range: Range | |
token: CancellationToken | |
返回值 | 描述 |
ProviderResult<SemanticTokens> |
DocumentSelector
语言选择器是一个或多个语言标识符和 语言过滤器 的组合。
注意,仅作为语言标识符的文档选择器选择所有文档,甚至包括那些未保存在磁盘上的文档。 仅当某个功能在没有进一步上下文的情况下工作时才使用此类选择器,例如,无需解析相关的“文件”。
示例
let sel: DocumentSelector = { scheme: 'file', language: 'typescript' };
DocumentSelector: DocumentFilter | string | ReadonlyArray<DocumentFilter | string>
DocumentSemanticTokensProvider
文档语义令牌提供程序接口定义了扩展和语义令牌之间的约定。
事件
onDidChangeSemanticTokens?: Event<void>
一个可选事件,用于指示来自此提供程序的语义令牌已更改。
方法
provideDocumentSemanticTokens(document: TextDocument, token: CancellationToken): ProviderResult<SemanticTokens>
文件中的令牌表示为整数数组。 每个令牌的位置相对于其之前的令牌表示,因为当在文件中进行编辑时,大多数令牌相对于彼此保持稳定。
简而言之,每个令牌需要 5 个整数来表示,因此文件中的特定令牌 i
由以下数组索引组成
- 在索引
5*i
-deltaLine
处:令牌行号,相对于前一个令牌 - 在索引
5*i+1
-deltaStart
处:令牌起始字符,相对于前一个令牌(如果它们在同一行,则相对于 0 或前一个令牌的起始字符) - 在索引
5*i+2
-length
处:令牌的长度。 令牌不能是多行的。 - 在索引
5*i+3
-tokenType
处:将在SemanticTokensLegend.tokenTypes
中查找。 我们目前要求tokenType
< 65536。 - 在索引
5*i+4
-tokenModifiers
处:每个设置的位将在SemanticTokensLegend.tokenModifiers
中查找
如何编码令牌
这是一个在 uint32 数组中编码包含 3 个令牌的文件的示例
{ line: 2, startChar: 5, length: 3, tokenType: "property", tokenModifiers: ["private", "static"] },
{ line: 2, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] },
{ line: 5, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] }
- 首先,必须设计一个图例。 必须预先提供此图例,并捕获所有可能的令牌类型。 对于此示例,我们将选择以下图例,该图例必须在注册提供程序时传入
tokenTypes: ['property', 'type', 'class'],
tokenModifiers: ['private', 'static']
- 第一个转换步骤是使用图例将
tokenType
和tokenModifiers
编码为整数。 令牌类型按索引查找,因此tokenType
值为1
表示tokenTypes[1]
。 可以通过使用位标志来设置多个令牌修饰符,因此tokenModifier
值3
首先被视为二进制0b00000011
,这意味着[tokenModifiers[0], tokenModifiers[1]]
,因为设置了位 0 和 1。 使用此图例,令牌现在是
{ line: 2, startChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 },
{ line: 2, startChar: 10, length: 4, tokenType: 1, tokenModifiers: 0 },
{ line: 5, startChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 }
- 下一步是表示文件中相对于前一个令牌的每个令牌。 在这种情况下,第二个令牌与第一个令牌位于同一行,因此第二个令牌的
startChar
相对于第一个令牌的startChar
,因此它将是10 - 5
。 第三个令牌与第二个令牌位于不同的行,因此第三个令牌的startChar
不会被更改
{ deltaLine: 2, deltaStartChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 },
{ deltaLine: 0, deltaStartChar: 5, length: 4, tokenType: 1, tokenModifiers: 0 },
{ deltaLine: 3, deltaStartChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 }
- 最后,最后一步是将令牌的 5 个字段中的每一个内联到单个数组中,这是一个内存友好的表示形式
// 1st token, 2nd token, 3rd token
[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
另请参阅 SemanticTokensBuilder,以获取将令牌编码为整数的帮助程序。 注意:在进行编辑时,可能会发生多次编辑,直到编辑器决定调用语义令牌提供程序。 注意:如果提供程序暂时无法计算语义令牌,则可以通过抛出消息为“Busy”的错误来指示这一点。
参数 | 描述 |
---|---|
document: TextDocument | |
token: CancellationToken | |
返回值 | 描述 |
ProviderResult<SemanticTokens> |
provideDocumentSemanticTokensEdits(document: TextDocument, previousResultId: string, token: CancellationToken): ProviderResult<SemanticTokens | SemanticTokensEdits>
DocumentSemanticTokensProvider
可以实现此方法 (provideDocumentSemanticTokensEdits
),然后返回先前提供的语义令牌的增量更新,而不是始终返回文件中的所有令牌。
当文档更改时令牌如何更改
假设 provideDocumentSemanticTokens
先前返回了以下语义令牌
// 1st token, 2nd token, 3rd token
[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
还假设在进行一些编辑后,文件中新的语义令牌是
// 1st token, 2nd token, 3rd token
[ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
可以根据应用于先前令牌的编辑来表达这些新令牌
[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] // old tokens
[ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] // new tokens
edit: { start: 0, deleteCount: 1, data: [3] } // replace integer at offset 0 with 3
注意:如果提供程序无法计算 SemanticTokensEdits
,它可以“放弃”并再次返回文档中的所有令牌。 注意:SemanticTokensEdits
中的所有编辑都包含旧整数数组中的索引,因此它们都引用先前的结果状态。
参数 | 描述 |
---|---|
document: TextDocument | |
previousResultId: string | |
token: CancellationToken | |
返回值 | 描述 |
ProviderResult<SemanticTokens | SemanticTokensEdits> |
DocumentSymbol
表示文档中出现的编程结构,如变量、类、接口等。 文档符号可以是分层的,并且它们有两个范围:一个范围包含其定义,另一个范围指向其最有趣的范围,例如标识符的范围。
构造函数
new DocumentSymbol(name: string, detail: string, kind: SymbolKind, range: Range, selectionRange: Range): DocumentSymbol
创建一个新的文档符号。
参数 | 描述 |
---|---|
name: string | 符号的名称。 |
detail: string | 符号的详细信息。 |
kind: SymbolKind | 符号的类型。 |
range: Range | 符号的完整范围。 |
selectionRange: Range | 应显示的范围。 |
返回值 | 描述 |
DocumentSymbol |
属性
children: DocumentSymbol[]
此符号的子项,例如类的属性。
此符号的更多详细信息,例如函数的签名。
kind: SymbolKind
此符号的类型。
此符号的名称。
range: Range
包含此符号的范围,不包括前导/尾随空格,但包括所有其他内容,例如注释和代码。
selectionRange: Range
当选择此符号时,应选择并显示的范围,例如函数的名称。 必须包含在 range 中。
tags?: readonly SymbolTag[]
此符号的标签。
DocumentSymbolProvider
文档符号提供程序接口定义了扩展和 转到符号 功能之间的约定。
方法
provideDocumentSymbols(document: TextDocument, token: CancellationToken): ProviderResult<DocumentSymbol[] | SymbolInformation[]>
为给定文档提供符号信息。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<DocumentSymbol[] | SymbolInformation[]> | 文档高亮的数组或一个可解析为此的 thenable 对象。 缺少结果可以通过返回 |
DocumentSymbolProviderMetadata
有关文档符号提供程序的元数据。
属性
当一个文档显示多个大纲树时,显示的易于理解的字符串。
EndOfLine
表示 文档 中的行尾字符序列。
枚举成员
换行符 \n
字符。
回车换行符 \r\n
序列。
EnterAction
描述按下 Enter 键时要执行的操作。
属性
描述在新行和缩进后追加的文本。
indentAction: IndentAction
描述如何处理缩进。
描述从新行的缩进中删除的字符数。
EnvironmentVariableCollection
扩展可以应用于进程环境的突变集合。
属性
description: string | MarkdownString
环境变量集合的描述,这将用于描述 UI 中的更改。
集合是否应为工作区缓存并在窗口重新加载时应用于终端。 当为 true 时,集合将在窗口重新加载等情况下立即激活。 此外,如果存在缓存版本,此 API 将返回缓存版本。 当扩展程序被卸载或集合被清除时,集合将失效。 默认为 true。
方法
append(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void
将值追加到环境变量。
请注意,扩展程序只能对任何一个变量进行一次更改,因此这将覆盖之前对 replace、append 或 prepend 的任何调用。
参数 | 描述 |
---|---|
variable: string | 要追加到的变量。 |
value: string | 要追加到变量的值。 |
options?: EnvironmentVariableMutatorOptions | 应用于 mutator 的选项,当未提供选项时,这将默认为 |
返回值 | 描述 |
void |
从此集合中清除所有 mutator。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
delete(variable: string): void
删除此集合中变量的 mutator。
参数 | 描述 |
---|---|
variable: string | 要删除 mutator 的变量。 |
返回值 | 描述 |
void |
forEach(callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any, thisArg?: any): void
迭代此集合中的每个 mutator。
参数 | 描述 |
---|---|
callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any | 为每个条目执行的函数。 |
thisArg?: any | 调用处理程序函数时使用的 |
返回值 | 描述 |
void |
get(variable: string): EnvironmentVariableMutator
获取此集合应用于变量的 mutator(如果有)。
参数 | 描述 |
---|---|
variable: string | 要获取 mutator 的变量。 |
返回值 | 描述 |
EnvironmentVariableMutator |
prepend(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void
将值前置到环境变量。
请注意,扩展程序只能对任何一个变量进行一次更改,因此这将覆盖之前对 replace、append 或 prepend 的任何调用。
参数 | 描述 |
---|---|
variable: string | 要前置的变量。 |
value: string | 要前置到变量的值。 |
options?: EnvironmentVariableMutatorOptions | 应用于 mutator 的选项,当未提供选项时,这将默认为 |
返回值 | 描述 |
void |
replace(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void
用值替换环境变量。
请注意,扩展程序只能对任何一个变量进行一次更改,因此这将覆盖之前对 replace、append 或 prepend 的任何调用。
参数 | 描述 |
---|---|
variable: string | 要替换的变量。 |
value: string | 用于替换变量的值。 |
options?: EnvironmentVariableMutatorOptions | 应用于 mutator 的选项,当未提供选项时,这将默认为 |
返回值 | 描述 |
void |
EnvironmentVariableMutator
要应用于环境变量的突变类型及其值。
属性
options: EnvironmentVariableMutatorOptions
应用于 mutator 的选项。
type: EnvironmentVariableMutatorType
将对变量发生的突变类型。
用于变量的值。
EnvironmentVariableMutatorOptions
应用于 mutator 的选项。
属性
applyAtProcessCreation?: boolean
刚好在进程创建之前应用于环境。 默认为 false。
applyAtShellIntegration?: boolean
应用于 shell 集成脚本中的环境。 请注意,如果 shell 集成被禁用或由于某种原因无法工作,则不会应用 mutator。 默认为 false。
EnvironmentVariableMutatorType
可以应用于环境变量的突变类型。
枚举成员
替换变量的现有值。
追加到变量现有值的末尾。
前置到变量现有值的开头。
EnvironmentVariableScope
环境变量集合应用到的作用域对象。
属性
workspaceFolder?: WorkspaceFolder
要获取集合的任何特定工作区文件夹。
EvaluatableExpression
EvaluatableExpression 表示文档中可以由活动调试器或运行时评估的表达式。 此评估的结果显示在类似工具提示的小部件中。 如果仅指定了范围,则将从基础文档中提取表达式。 可选的表达式可用于覆盖提取的表达式。 在这种情况下,范围仍然用于突出显示文档中的范围。
构造函数
new EvaluatableExpression(range: Range, expression?: string): EvaluatableExpression
创建新的可评估表达式对象。
参数 | 描述 |
---|---|
range: Range | 从中提取可评估表达式的基础文档中的范围。 |
expression?: string | 如果指定,则覆盖提取的表达式。 |
返回值 | 描述 |
EvaluatableExpression |
属性
range: Range
EvaluatableExpressionProvider
可评估表达式提供程序接口定义了扩展程序和调试悬停之间的约定。 在此约定中,提供程序为文档中的给定位置返回可评估表达式,编辑器在活动调试会话中评估此表达式,并在调试悬停中显示结果。
方法
provideEvaluatableExpression(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<EvaluatableExpression>
为给定的文档和位置提供可评估的表达式。 编辑器将在活动调试会话中评估此表达式,并将结果显示在调试悬停中。 表达式可以通过基础文档中的范围隐式指定,也可以通过显式返回表达式来指定。
参数 | 描述 |
---|---|
document: TextDocument | 调试悬停即将出现的文档。 |
position: Position | 调试悬停即将出现的文档中的行和字符位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<EvaluatableExpression> | EvaluatableExpression 或可解析为此表达式的可 thenable 对象。 缺少结果可以通过返回 |
Event<T>
表示类型化的事件。
一个函数,表示一个事件,您可以通过使用侦听器函数作为参数调用它来订阅该事件。
示例
item.onDidChange(function(event) {
console.log('Event happened: ' + event);
});
(listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable
一个函数,表示一个事件,您可以通过使用侦听器函数作为参数调用它来订阅该事件。
参数 | 描述 |
---|---|
listener: (e: T) => any | 当事件发生时,将调用侦听器函数。 |
thisArgs?: any | 调用事件侦听器时将使用的 |
disposables?: Disposable[] | 将在其中添加 Disposable 的数组。 |
返回值 | 描述 |
Disposable | 取消订阅事件侦听器的 disposable 对象。 |
EventEmitter<T>
事件发射器可用于创建和管理 Event 以供其他人订阅。 一个发射器始终拥有一个事件。
如果您想从扩展程序内部提供事件,例如在 TextDocumentContentProvider 中或在向其他扩展程序提供 API 时,请使用此类。
构造函数
new EventEmitter<T>(): EventEmitter<T>
参数 | 描述 |
---|---|
返回值 | 描述 |
EventEmitter<T> |
属性
event: Event<T>
事件侦听器可以订阅的事件。
方法
释放此对象并释放资源。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
通知 event 的所有订阅者。 一个或多个侦听器的失败不会导致此函数调用失败。
参数 | 描述 |
---|---|
data: T | 事件对象。 |
返回值 | 描述 |
void |
Extension<T>
表示一个扩展。
要获取 Extension
的实例,请使用 getExtension。
属性
此扩展程序导出的公共 API(activate
的返回值)。 在此扩展程序激活之前访问此字段是无效的操作。
extensionKind: ExtensionKind
扩展种类描述了扩展程序是在 UI 运行时运行,还是在远程扩展主机运行时运行。 扩展种类在扩展程序的 package.json
文件中定义,但也可以通过 remote.extensionKind
设置进行细化。 当不存在远程扩展主机时,该值为 ExtensionKind.UI。
包含此扩展程序的目录的绝对文件路径。 Extension.extensionUri.fsPath 的简写表示法(独立于 uri 方案)。
extensionUri: Uri
包含扩展程序的目录的 uri。
规范的扩展标识符,格式为:publisher.name
。
如果扩展程序已激活,则为 true
。
扩展程序的 package.json 的已解析内容。
方法
激活此扩展程序并返回其公共 API。
参数 | 描述 |
---|---|
返回值 | 描述 |
Thenable<T> | 当此扩展程序已激活时将解析的 Promise。 |
ExtensionContext
扩展上下文是扩展程序私有的实用程序集合。
ExtensionContext
的实例作为扩展程序的 activate
调用的第一个参数提供。
属性
environmentVariableCollection: GlobalEnvironmentVariableCollection
获取此工作区的扩展程序的全局环境变量集合,从而可以将更改应用于终端环境变量。
extension: Extension<any>
当前的 Extension
实例。
extensionMode: ExtensionMode
扩展程序运行的模式。 有关可能的值和方案,请参阅 ExtensionMode。
包含扩展程序的目录的绝对文件路径。 ExtensionContext.extensionUri.fsPath 的简写表示法(独立于 uri 方案)。
extensionUri: Uri
包含扩展程序的目录的 uri。
globalState: Memento & {setKeysForSync}
一个 memento 对象,用于存储独立于当前打开的 workspace 的状态。
扩展程序可以在其中存储全局状态的绝对文件路径。 该目录可能在磁盘上不存在,并且创建取决于扩展程序。 但是,保证父目录存在。
使用 globalState 存储键值数据。
- 已弃用 - 请改用 globalStorageUri。
globalStorageUri: Uri
扩展程序可以在其中存储全局状态的目录的 uri。 该目录可能在磁盘上不存在,并且创建取决于扩展程序。 但是,保证父目录存在。
使用 globalState 存储键值数据。
另请参阅 workspace.fs,了解如何从 uri 读取和写入文件和文件夹。
languageModelAccessInformation: LanguageModelAccessInformation
一个对象,用于保存有关此扩展程序如何使用语言模型的信息。
扩展程序可以在其中创建日志文件的目录的绝对文件路径。 该目录可能在磁盘上不存在,并且创建取决于扩展程序。 但是,保证父目录存在。
- 已弃用 - 请改用 logUri。
logUri: Uri
扩展程序可以在其中创建日志文件的目录的 uri。 该目录可能在磁盘上不存在,并且创建取决于扩展程序。 但是,保证父目录存在。
另请参阅 workspace.fs,了解如何从 uri 读取和写入文件和文件夹。
secrets: SecretStorage
一个 secret storage 对象,用于存储独立于当前打开的 workspace 的状态。
扩展程序可以在其中存储私有状态的工作区特定目录的绝对文件路径。 该目录可能在磁盘上不存在,并且创建取决于扩展程序。 但是,保证父目录存在。
使用 workspaceState 或 globalState 存储键值数据。
- 已弃用 - 请改用 storageUri。
storageUri: Uri
扩展程序可以在其中存储私有状态的工作区特定目录的 uri。 该目录可能不存在,并且创建取决于扩展程序。 但是,保证父目录存在。 当未打开工作区或文件夹时,该值为 undefined
。
使用 workspaceState 或 globalState 存储键值数据。
另请参阅 workspace.fs,了解如何从 uri 读取和写入文件和文件夹。
subscriptions: Array<{dispose}>
可以在其中添加 disposable 对象的数组。 当此扩展程序被停用时,disposable 对象将被释放。
注意:异步 dispose 函数不会被等待。
workspaceState: Memento
一个 memento 对象,用于存储当前打开的 workspace 上下文中的状态。
方法
asAbsolutePath(relativePath: string): string
获取扩展程序中包含的资源的绝对路径。
注意:可以使用 Uri.joinPath 和 extensionUri 构建绝对 uri,例如 vscode.Uri.joinPath(context.extensionUri, relativePath);
参数 | 描述 |
---|---|
relativePath: string | 扩展程序中包含的资源的相对路径。 |
返回值 | 描述 |
string | 资源的绝对路径。 |
ExtensionKind
在远程窗口中,扩展种类描述了扩展程序是在 UI(窗口)运行时运行,还是远程运行。
枚举成员
扩展程序在 UI 运行时运行。
扩展程序在远程扩展主机运行时运行。
ExtensionMode
ExtensionMode 在 ExtensionContext
上提供,并指示特定扩展程序在其中运行的模式。
枚举成员
扩展程序已在编辑器中正常安装(例如,从 Marketplace 或 VSIX)。
扩展程序正在从启动编辑器时提供的 --extensionDevelopmentPath
运行。
扩展程序正在从 --extensionTestsPath
运行,并且扩展主机正在运行单元测试。
ExtensionTerminalOptions
值对象,描述虚拟进程终端应使用的选项。
属性
color?: ThemeColor
终端的图标 ThemeColor。 建议使用标准 terminal.ansi*
主题键,以获得最佳对比度以及跨主题的一致性。
iconPath?: IconPath
终端的图标路径或 ThemeIcon。
选择退出在重启和重新加载时的默认终端持久化。这仅在启用 terminal.integrated.enablePersistentSessions
时生效。
location?: TerminalEditorLocationOptions | TerminalSplitLocationOptions | TerminalLocation
一个人类可读的字符串,将在 UI 中用于表示终端。
pty: Pseudoterminal
一个 Pseudoterminal 的实现,允许扩展控制终端。
FileChangeEvent
文件系统提供程序必须使用此事件来发出文件更改信号。
属性
type: FileChangeType
更改的类型。
uri: Uri
已更改文件的 URI。
FileChangeType
文件更改类型枚举。
枚举成员
文件的内容或元数据已更改。
已创建文件。
已删除文件。
FileCoverage
包含文件的覆盖率元数据。
静态
fromDetails(uri: Uri, details: readonly FileCoverageDetail[]): FileCoverage
使用从覆盖率详细信息填充的计数创建 FileCoverage 实例。
参数 | 描述 |
---|---|
uri: Uri | 已覆盖文件 URI |
details: readonly FileCoverageDetail[] | |
返回值 | 描述 |
FileCoverage |
构造函数
new FileCoverage(uri: Uri, statementCoverage: TestCoverageCount, branchCoverage?: TestCoverageCount, declarationCoverage?: TestCoverageCount, includesTests?: TestItem[]): FileCoverage
参数 | 描述 |
---|---|
uri: Uri | 已覆盖文件 URI |
statementCoverage: TestCoverageCount | 语句覆盖率信息。如果报告程序不提供语句覆盖率信息,则可以改为使用此信息来表示行覆盖率。 |
branchCoverage?: TestCoverageCount | 分支覆盖率信息 |
declarationCoverage?: TestCoverageCount | 声明覆盖率信息 |
includesTests?: TestItem[] | 此覆盖率报告中包含的测试用例,请参阅 includesTests |
返回值 | 描述 |
FileCoverage |
属性
branchCoverage?: TestCoverageCount
分支覆盖率信息。
declarationCoverage?: TestCoverageCount
声明覆盖率信息。根据报告程序和语言,这可能是函数、方法或命名空间等类型。
includesTests?: TestItem[]
在此文件中生成覆盖率的 测试用例列表。如果设置,则还应定义 TestRunProfile.loadDetailedCoverageForTest 以检索详细的覆盖率信息。
statementCoverage: TestCoverageCount
语句覆盖率信息。如果报告程序不提供语句覆盖率信息,则可以改为使用此信息来表示行覆盖率。
uri: Uri
文件 URI。
FileCoverageDetail
从 TestRunProfile.loadDetailedCoverage 返回的覆盖率详细信息。
FileCoverageDetail: StatementCoverage | DeclarationCoverage
FileCreateEvent
文件创建后触发的事件。
属性
files: readonly Uri[]
已创建的文件。
FileDecoration
文件装饰表示可以与文件一起呈现的元数据。
构造函数
new FileDecoration(badge?: string, tooltip?: string, color?: ThemeColor): FileDecoration
创建新的装饰。
参数 | 描述 |
---|---|
badge?: string | 表示装饰的字母。 |
tooltip?: string | 装饰的工具提示。 |
color?: ThemeColor | 装饰的颜色。 |
返回值 | 描述 |
FileDecoration |
属性
表示此装饰的非常短的字符串。
color?: ThemeColor
此装饰的颜色。
一个标志,表示此装饰应传播到其父级。
此装饰的人类可读工具提示。
FileDecorationProvider
装饰提供程序接口定义了扩展和文件装饰之间的约定。
事件
onDidChangeFileDecorations?: Event<Uri | Uri[]>
方法
provideFileDecoration(uri: Uri, token: CancellationToken): ProviderResult<FileDecoration>
为给定的 URI 提供装饰。
注意:仅当文件在 UI 中呈现时才调用此函数。这意味着来自向上传播的后代的装饰必须通过 onDidChangeFileDecorations 事件向编辑器发出信号。
参数 | 描述 |
---|---|
uri: Uri | 要为其提供装饰的文件的 URI。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<FileDecoration> | 装饰或可解析为这种装饰的可 Thenable 对象。 |
FileDeleteEvent
文件删除后触发的事件。
属性
files: readonly Uri[]
已删除的文件。
FilePermission
文件的权限。
枚举成员
文件是只读的。
注意: 来自使用 isReadonly: true
选项注册的 FileSystemProvider
的所有 FileStat
将被隐式处理,就好像设置了 FilePermission.Readonly
一样。因此,不可能拥有注册为只读文件系统提供程序,但其中某些 FileStat
不是只读的。
FileRenameEvent
文件重命名后触发的事件。
属性
files: ReadonlyArray<{newUri: Uri, oldUri: Uri}>
已重命名的文件。
FileStat
FileStat
类型表示有关文件的元数据
属性
自 1970 年 1 月 1 日 00:00:00 UTC 以来经过的创建时间戳(以毫秒为单位)。
自 1970 年 1 月 1 日 00:00:00 UTC 以来经过的修改时间戳(以毫秒为单位)。
注意: 如果文件已更改,则务必提供从先前值递增的更新后的 mtime
。否则,可能会有优化措施,例如不会在编辑器中显示更新后的文件内容。
permissions?: FilePermission
文件的权限,例如文件是否为只读。
注意: 此值可能是位掩码,例如 FilePermission.Readonly | FilePermission.Other
。
大小(以字节为单位)。
注意: 如果文件已更改,则务必提供更新后的 size
。否则,可能会有优化措施,例如不会在编辑器中显示更新后的文件内容。
type: FileType
文件的类型,例如是常规文件、目录还是指向文件的符号链接。
注意: 此值可能是位掩码,例如 FileType.File | FileType.SymbolicLink
。
FileSystem
文件系统接口公开了编辑器的内置和贡献的 文件系统提供程序。它允许扩展使用来自本地磁盘的文件以及来自远程位置(如远程扩展主机或 ftp 服务器)的文件。
注意:此接口的实例作为 workspace.fs 提供。
方法
copy(source: Uri, target: Uri, options?: {overwrite: boolean}): Thenable<void>
复制文件或文件夹。
createDirectory(uri: Uri): Thenable<void>
创建新目录(注意,新文件是通过 write
调用创建的)。
注意:缺少目录会自动创建,例如,此调用具有 mkdirp
语义。
参数 | 描述 |
---|---|
uri: Uri | 新文件夹的 URI。 |
返回值 | 描述 |
Thenable<void> |
delete(uri: Uri, options?: {recursive: boolean, useTrash: boolean}): Thenable<void>
删除文件。
参数 | 描述 |
---|---|
uri: Uri | 要删除的资源。 |
options?: {recursive: boolean, useTrash: boolean} | 定义是否应使用回收站以及文件夹删除是否为递归 |
返回值 | 描述 |
Thenable<void> |
isWritableFileSystem(scheme: string): boolean
检查给定的文件系统是否支持写入文件。
请记住,仅仅因为文件系统支持写入,并不意味着写入总是会成功。可能存在权限问题或其他错误阻止写入文件。
参数 | 描述 |
---|---|
scheme: string | 文件系统的方案,例如 |
返回值 | 描述 |
boolean | 如果文件系统支持写入,则为 |
readDirectory(uri: Uri): Thenable<Array<[string, FileType]>>
检索 目录 的所有条目。
readFile(uri: Uri): Thenable<Uint8Array>
读取文件的完整内容。
参数 | 描述 |
---|---|
uri: Uri | 文件的 URI。 |
返回值 | 描述 |
Thenable<Uint8Array> | 字节数组或可解析为这种数组的可 Thenable 对象。 |
rename(source: Uri, target: Uri, options?: {overwrite: boolean}): Thenable<void>
重命名文件或文件夹。
stat(uri: Uri): Thenable<FileStat>
writeFile(uri: Uri, content: Uint8Array): Thenable<void>
将数据写入文件,替换其全部内容。
参数 | 描述 |
---|---|
uri: Uri | 文件的 URI。 |
content: Uint8Array | 文件的新内容。 |
返回值 | 描述 |
Thenable<void> |
FileSystemError
文件系统提供程序应使用此类型来发出错误信号。
此类具有用于常见错误情况的工厂方法,例如当文件或文件夹不存在时使用 FileNotFound
,像这样使用它们:throw vscode.FileSystemError.FileNotFound(someUri);
静态
FileExists(messageOrUri?: string | Uri): FileSystemError
创建一个错误信号,表示文件或文件夹已存在,例如,在创建但不覆盖文件时。
参数 | 描述 |
---|---|
messageOrUri?: string | Uri | 消息或 URI。 |
返回值 | 描述 |
FileSystemError |
FileIsADirectory(messageOrUri?: string | Uri): FileSystemError
创建一个错误信号,表示文件是文件夹。
参数 | 描述 |
---|---|
messageOrUri?: string | Uri | 消息或 URI。 |
返回值 | 描述 |
FileSystemError |
FileNotADirectory(messageOrUri?: string | Uri): FileSystemError
创建一个错误信号,表示文件不是文件夹。
参数 | 描述 |
---|---|
messageOrUri?: string | Uri | 消息或 URI。 |
返回值 | 描述 |
FileSystemError |
FileNotFound(messageOrUri?: string | Uri): FileSystemError
创建一个错误信号,表示未找到文件或文件夹。
参数 | 描述 |
---|---|
messageOrUri?: string | Uri | 消息或 URI。 |
返回值 | 描述 |
FileSystemError |
NoPermissions(messageOrUri?: string | Uri): FileSystemError
创建一个错误信号,表示操作缺少所需的权限。
参数 | 描述 |
---|---|
messageOrUri?: string | Uri | 消息或 URI。 |
返回值 | 描述 |
FileSystemError |
Unavailable(messageOrUri?: string | Uri): FileSystemError
创建一个错误信号,表示文件系统不可用或太忙而无法完成请求。
参数 | 描述 |
---|---|
messageOrUri?: string | Uri | 消息或 URI。 |
返回值 | 描述 |
FileSystemError |
构造函数
new FileSystemError(messageOrUri?: string | Uri): FileSystemError
创建一个新的文件系统错误。
参数 | 描述 |
---|---|
messageOrUri?: string | Uri | 消息或 URI。 |
返回值 | 描述 |
FileSystemError |
属性
标识此错误的代码。
可能的值是错误名称,例如 FileNotFound,或 Unknown
表示未指定的错误。
FileSystemProvider
文件系统提供程序定义了编辑器读取、写入、发现和管理文件和文件夹所需的内容。它允许扩展从远程位置(如 ftp 服务器)提供文件,并将这些文件无缝集成到编辑器中。
事件
onDidChangeFile: Event<FileChangeEvent[]>
方法
copy(source: Uri, destination: Uri, options: {overwrite: boolean}): void | Thenable<void>
复制文件或文件夹。实现此函数是可选的,但它将加快复制操作。
- 抛出 - 当
source
不存在时抛出 FileNotFound。
- 抛出 - 当
destination
的父级不存在时抛出 FileNotFound,例如,不需要 mkdirp 逻辑。
- 抛出 - 当
destination
存在且overwrite
选项不为true
时抛出 FileExists。
- 抛出 - 当权限不足时抛出 NoPermissions。
createDirectory(uri: Uri): void | Thenable<void>
创建新目录(注意,新文件是通过 write
调用创建的)。
- 抛出 - 当
uri
的父级不存在时抛出 FileNotFound,例如,不需要 mkdirp 逻辑。
- 抛出 - 当
uri
已存在时抛出 FileExists。
- 抛出 - 当权限不足时抛出 NoPermissions。
参数 | 描述 |
---|---|
uri: Uri | 新文件夹的 URI。 |
返回值 | 描述 |
void | Thenable<void> |
delete(uri: Uri, options: {recursive: boolean}): void | Thenable<void>
参数 | 描述 |
---|---|
uri: Uri | 要删除的资源。 |
options: {recursive: boolean} | 定义文件夹删除是否为递归。 |
返回值 | 描述 |
void | Thenable<void> |
readDirectory(uri: Uri): Array<[string, FileType]> | Thenable<Array<[string, FileType]>>
检索 目录 的所有条目。
- 抛出 - 当
uri
不存在时抛出 FileNotFound。
readFile(uri: Uri): Uint8Array | Thenable<Uint8Array>
读取文件的完整内容。
- 抛出 - 当
uri
不存在时抛出 FileNotFound。
参数 | 描述 |
---|---|
uri: Uri | 文件的 URI。 |
返回值 | 描述 |
Uint8Array | Thenable<Uint8Array> | 字节数组或可解析为这种数组的可 Thenable 对象。 |
rename(oldUri: Uri, newUri: Uri, options: {overwrite: boolean}): void | Thenable<void>
重命名文件或文件夹。
- 抛出 - 当
oldUri
不存在时抛出 FileNotFound。
- 抛出 - 当
newUri
的父级不存在时抛出 FileNotFound,例如,不需要 mkdirp 逻辑。
- 抛出 - 当
newUri
存在且overwrite
选项不为true
时抛出 FileExists。
- 抛出 - 当权限不足时抛出 NoPermissions。
stat(uri: Uri): FileStat | Thenable<FileStat>
检索有关文件的元数据。
请注意,符号链接的元数据应为它们引用的文件的元数据。但是,除了实际类型外,还必须使用 SymbolicLink 类型,例如 FileType.SymbolicLink | FileType.Directory
。
- 抛出 - 当
uri
不存在时抛出 FileNotFound。
watch(uri: Uri, options: {excludes: readonly string[], recursive: boolean}): Disposable
订阅由 uri
表示的文件或文件夹中的文件更改事件。对于文件夹,recursive
选项指示是否也应监视子文件夹、子子文件夹等的文件更改。当 recursive: false
时,只有对文件夹的直接子文件所做的更改才会触发事件。
excludes
数组用于指示应从文件监视中排除的路径。它通常从用户可配置的 files.watcherExclude
设置派生而来。每个条目可以是
- 要排除的绝对路径
- 要排除的相对路径 (例如
build/output
) - 简单的 glob 模式 (例如
**/build
,output/**
)
文件系统提供程序的任务是针对根据这些规则的每个更改调用 onDidChangeFile。对于与任何提供的排除项匹配的文件,不应发出任何事件。
参数 | 描述 |
---|---|
uri: Uri | 要监视的文件或文件夹的 uri。 |
options: {excludes: readonly string[], recursive: boolean} | 配置监视。 |
返回值 | 描述 |
Disposable | 一个 disposable,告知提供程序停止监视 |
writeFile(uri: Uri, content: Uint8Array, options: {create: boolean, overwrite: boolean}): void | Thenable<void>
将数据写入文件,替换其全部内容。
- throws - 当
uri
不存在且未设置create
时,抛出 FileNotFound 错误。
- throws - 当
uri
的父目录不存在且设置了create
时,抛出 FileNotFound 错误,例如,不需要 mkdirp 逻辑。
- throws - 当
uri
已存在,设置了create
但未设置overwrite
时,抛出 FileExists 错误。
- 抛出 - 当权限不足时抛出 NoPermissions。
参数 | 描述 |
---|---|
uri: Uri | 文件的 URI。 |
content: Uint8Array | 文件的新内容。 |
options: {create: boolean, overwrite: boolean} | 定义是否应创建或必须创建缺失的文件。 |
返回值 | 描述 |
void | Thenable<void> |
FileSystemWatcher
文件系统监视器通知关于磁盘上或来自其他 FileSystemProvider 的文件和文件夹的更改。
要获取 FileSystemWatcher
的实例,请使用 createFileSystemWatcher。
事件
在文件/文件夹更改时触发的事件。
在文件/文件夹创建时触发的事件。
在文件/文件夹删除时触发的事件。
属性
如果此文件系统监视器已创建为忽略更改文件系统事件,则为 true。
如果此文件系统监视器已创建为忽略创建文件系统事件,则为 true。
如果此文件系统监视器已创建为忽略删除文件系统事件,则为 true。
方法
释放此对象。
参数 | 描述 |
---|---|
返回值 | 描述 |
any |
FileType
文件类型的枚举。类型 File
和 Directory
也可以是符号链接,在这种情况下,请使用 FileType.File | FileType.SymbolicLink
和 FileType.Directory | FileType.SymbolicLink
。
枚举成员
文件类型未知。
一个常规文件。
一个目录。
指向文件的符号链接。
FileWillCreateEvent
当文件即将被创建时触发的事件。
要在文件创建之前对工作区进行修改,请调用 waitUntil 函数,并传入一个 resolve 为 workspace edit 的 thenable。
属性
files: readonly Uri[]
即将被创建的文件。
token: CancellationToken
取消令牌。
方法
waitUntil(thenable: Thenable<WorkspaceEdit>): void
允许暂停事件并应用 workspace edit。
注意: 此函数只能在事件分发期间调用,而不能以异步方式调用
workspace.onWillCreateFiles(event => {
// async, will *throw* an error
setTimeout(() => event.waitUntil(promise));
// sync, OK
event.waitUntil(promise);
});
参数 | 描述 |
---|---|
thenable: Thenable<WorkspaceEdit> | 一个延迟保存的 thenable。 |
返回值 | 描述 |
void |
waitUntil(thenable: Thenable<any>): void
允许暂停事件,直到提供的 thenable resolve。
注意: 此函数只能在事件分发期间调用。
参数 | 描述 |
---|---|
thenable: Thenable<any> | 一个延迟保存的 thenable。 |
返回值 | 描述 |
void |
FileWillDeleteEvent
当文件即将被删除时触发的事件。
要在文件删除之前对工作区进行修改,请调用 waitUntil
函数,并传入一个 resolve 为 workspace edit 的 thenable。
属性
files: readonly Uri[]
即将被删除的文件。
token: CancellationToken
取消令牌。
方法
waitUntil(thenable: Thenable<WorkspaceEdit>): void
允许暂停事件并应用 workspace edit。
注意: 此函数只能在事件分发期间调用,而不能以异步方式调用
workspace.onWillCreateFiles(event => {
// async, will *throw* an error
setTimeout(() => event.waitUntil(promise));
// sync, OK
event.waitUntil(promise);
});
参数 | 描述 |
---|---|
thenable: Thenable<WorkspaceEdit> | 一个延迟保存的 thenable。 |
返回值 | 描述 |
void |
waitUntil(thenable: Thenable<any>): void
允许暂停事件,直到提供的 thenable resolve。
注意: 此函数只能在事件分发期间调用。
参数 | 描述 |
---|---|
thenable: Thenable<any> | 一个延迟保存的 thenable。 |
返回值 | 描述 |
void |
FileWillRenameEvent
当文件即将被重命名时触发的事件。
要在文件重命名之前对工作区进行修改,请调用 waitUntil
函数,并传入一个 resolve 为 workspace edit 的 thenable。
属性
files: ReadonlyArray<{newUri: Uri, oldUri: Uri}>
即将被重命名的文件。
token: CancellationToken
取消令牌。
方法
waitUntil(thenable: Thenable<WorkspaceEdit>): void
允许暂停事件并应用 workspace edit。
注意: 此函数只能在事件分发期间调用,而不能以异步方式调用
workspace.onWillCreateFiles(event => {
// async, will *throw* an error
setTimeout(() => event.waitUntil(promise));
// sync, OK
event.waitUntil(promise);
});
参数 | 描述 |
---|---|
thenable: Thenable<WorkspaceEdit> | 一个延迟保存的 thenable。 |
返回值 | 描述 |
void |
waitUntil(thenable: Thenable<any>): void
允许暂停事件,直到提供的 thenable resolve。
注意: 此函数只能在事件分发期间调用。
参数 | 描述 |
---|---|
thenable: Thenable<any> | 一个延迟保存的 thenable。 |
返回值 | 描述 |
void |
FoldingContext
折叠上下文 (供将来使用)
FoldingRange
基于行的折叠范围。要使其有效,起始行和结束行必须大于零且小于文档中的行数。无效的范围将被忽略。
构造函数
new FoldingRange(start: number, end: number, kind?: FoldingRangeKind): FoldingRange
创建一个新的折叠范围。
参数 | 描述 |
---|---|
start: number | 折叠范围的起始行。 |
end: number | 折叠范围的结束行。 |
kind?: FoldingRangeKind | 折叠范围的种类。 |
返回值 | 描述 |
FoldingRange |
属性
要折叠的范围的从零开始的结束行。折叠区域以该行的最后一个字符结束。要使其有效,结束行必须为零或更大,且小于文档中的行数。
kind?: FoldingRangeKind
描述折叠范围的种类,例如 Comment 或 Region。种类用于对折叠范围进行分类,并供 “折叠所有注释” 等命令使用。有关所有种类的枚举,请参见 FoldingRangeKind。如果未设置,则该范围源自语法元素。
要折叠的范围的从零开始的起始行。折叠区域从该行的最后一个字符之后开始。要使其有效,结束行必须为零或更大,且小于文档中的行数。
FoldingRangeKind
特定折叠范围种类的枚举。种类是 FoldingRange 的可选字段,用于区分特定的折叠范围,例如源自注释的范围。种类供 折叠所有注释
或 折叠所有区域
等命令使用。如果未在范围上设置种类,则该范围源自注释、导入或区域标记以外的语法元素。
枚举成员
表示注释的折叠范围的种类。
表示导入的折叠范围的种类。
表示源自折叠标记 (如 #region
和 #endregion
) 的区域的折叠范围的种类。
FoldingRangeProvider
折叠范围提供程序接口定义了扩展与编辑器中 Folding 之间的约定。
事件
onDidChangeFoldingRanges?: Event<void>
一个可选事件,用于指示此提供程序的折叠范围已更改。
方法
provideFoldingRanges(document: TextDocument, context: FoldingContext, token: CancellationToken): ProviderResult<FoldingRange[]>
如果提供程序不想参与或已取消,则返回折叠范围列表,或者返回 null 和 undefined。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
context: FoldingContext | 其他上下文信息 (供将来使用) |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<FoldingRange[]> |
FormattingOptions
描述格式化应使用哪些选项的值对象。
属性
首选空格而不是制表符。
制表符在空格中的大小。
FunctionBreakpoint
由函数名称指定的断点。
构造函数
new FunctionBreakpoint(functionName: string, enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): FunctionBreakpoint
创建一个新的函数断点。
参数 | 描述 |
---|---|
functionName: string | |
enabled?: boolean | |
condition?: string | |
hitCondition?: string | |
logMessage?: string | |
返回值 | 描述 |
FunctionBreakpoint |
属性
条件断点的可选表达式。
是否启用断点。
此断点附加到的函数的名称。
一个可选表达式,用于控制忽略断点的命中次数。
断点的唯一 ID。
命中此断点时要记录的可选消息。{} 中的嵌入式表达式由调试适配器内插。
GlobalEnvironmentVariableCollection
扩展可以应用于进程环境的突变集合。应用于所有作用域。
属性
description: string | MarkdownString
环境变量集合的描述,这将用于描述 UI 中的更改。
集合是否应为工作区缓存并在窗口重新加载时应用于终端。 当为 true 时,集合将在窗口重新加载等情况下立即激活。 此外,如果存在缓存版本,此 API 将返回缓存版本。 当扩展程序被卸载或集合被清除时,集合将失效。 默认为 true。
方法
append(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void
将值追加到环境变量。
请注意,扩展程序只能对任何一个变量进行一次更改,因此这将覆盖之前对 replace、append 或 prepend 的任何调用。
参数 | 描述 |
---|---|
variable: string | 要追加到的变量。 |
value: string | 要追加到变量的值。 |
options?: EnvironmentVariableMutatorOptions | 应用于 mutator 的选项,当未提供选项时,这将默认为 |
返回值 | 描述 |
void |
从此集合中清除所有 mutator。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
delete(variable: string): void
删除此集合中变量的 mutator。
参数 | 描述 |
---|---|
variable: string | 要删除 mutator 的变量。 |
返回值 | 描述 |
void |
forEach(callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any, thisArg?: any): void
迭代此集合中的每个 mutator。
参数 | 描述 |
---|---|
callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any | 为每个条目执行的函数。 |
thisArg?: any | 调用处理程序函数时使用的 |
返回值 | 描述 |
void |
get(variable: string): EnvironmentVariableMutator
获取此集合应用于变量的 mutator(如果有)。
参数 | 描述 |
---|---|
variable: string | 要获取 mutator 的变量。 |
返回值 | 描述 |
EnvironmentVariableMutator |
getScoped(scope: EnvironmentVariableScope): EnvironmentVariableCollection
获取扩展的作用域特定的环境变量集合。 这使得可以仅在指定作用域内更改终端环境变量,并在全局集合之外(和之后)应用。
通过此方法获得的每个对象都是隔离的,并且不会影响其他作用域的对象,包括全局集合。
参数 | 描述 |
---|---|
scope: EnvironmentVariableScope | 环境变量集合应用的作用域。 如果省略作用域参数,则返回适用于该参数所有相关作用域的集合。 例如,如果未指定“workspaceFolder”参数,则将返回适用于所有工作区文件夹的集合。 |
返回值 | 描述 |
EnvironmentVariableCollection | 传入作用域的环境变量集合。 |
prepend(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void
将值前置到环境变量。
请注意,扩展程序只能对任何一个变量进行一次更改,因此这将覆盖之前对 replace、append 或 prepend 的任何调用。
参数 | 描述 |
---|---|
variable: string | 要前置的变量。 |
value: string | 要前置到变量的值。 |
options?: EnvironmentVariableMutatorOptions | 应用于 mutator 的选项,当未提供选项时,这将默认为 |
返回值 | 描述 |
void |
replace(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void
用值替换环境变量。
请注意,扩展程序只能对任何一个变量进行一次更改,因此这将覆盖之前对 replace、append 或 prepend 的任何调用。
参数 | 描述 |
---|---|
variable: string | 要替换的变量。 |
value: string | 用于替换变量的值。 |
options?: EnvironmentVariableMutatorOptions | 应用于 mutator 的选项,当未提供选项时,这将默认为 |
返回值 | 描述 |
void |
GlobPattern
用于匹配文件路径的文件 glob 模式。 这可以是 glob 模式字符串 (例如 **/*.{ts,js}
或 *.{ts,js}
) 或 relative pattern。
Glob 模式可以具有以下语法
*
匹配路径段中的零个或多个字符?
匹配路径段中的一个字符**
匹配任意数量的路径段,包括零个{}
对条件进行分组 (例如**/*.{ts,js}
匹配所有 TypeScript 和 JavaScript 文件)[]
声明要在路径段中匹配的字符范围 (例如,example.[0-9]
匹配example.0
、example.1
、…)[!...]
否定要在路径段中匹配的字符范围 (例如,example.[!0-9]
匹配example.a
、example.b
,但不匹配example.0
)
注意:反斜杠 (``) 在 glob 模式中无效。 如果您有要匹配的现有文件路径,请考虑使用 relative pattern 支持,该支持负责将任何反斜杠转换为斜杠。 否则,请确保在创建 glob 模式时将任何反斜杠转换为斜杠。
GlobPattern: string | RelativePattern
Hover
Hover 表示符号或单词的附加信息。 Hover 在类似工具提示的小部件中呈现。
构造函数
new Hover(contents: MarkdownString | MarkedString | Array<MarkdownString | MarkedString>, range?: Range): Hover
创建一个新的 hover 对象。
参数 | 描述 |
---|---|
contents: MarkdownString | MarkedString | Array<MarkdownString | MarkedString> | hover 的内容。 |
range?: Range | hover 应用的范围。 |
返回值 | 描述 |
Hover |
属性
contents: Array<MarkdownString | MarkedString>
此 hover 的内容。
range?: Range
此 hover 应用的范围。 缺少时,编辑器将使用当前位置的范围或当前位置本身。
HoverProvider
hover 提供程序接口定义了扩展与 hover 功能之间的约定。
方法
provideHover(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Hover>
为给定位置和文档提供 hover。 同一位置的多个 hover 将由编辑器合并。 Hover 可以具有一个范围,该范围在省略时默认为该位置的单词范围。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<Hover> | 一个 hover 或一个 resolve 为 hover 的 thenable。 结果的缺失可以通过返回 |
IconPath
表示 UI 中的图标。 这可以是 uri、浅色和深色主题的单独 uri,或 主题图标。
IconPath: Uri | {dark: Uri, light: Uri} | ThemeIcon
ImplementationProvider
实现提供程序接口定义了扩展与转到实现功能之间的约定。
方法
provideImplementation(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | LocationLink[]>
提供给定位置和文档处符号的实现。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<Definition | LocationLink[]> | 一个定义或一个可以解析为此定义的 thenable 对象。缺少结果可以通过返回 |
IndentAction
描述在按 Enter 键时如何处理缩进。
枚举成员
插入新行并复制上一行的缩进。
插入新行并缩进一次 (相对于上一行的缩进)。
插入两行新行
- 第一行缩进,光标将位于该行
- 第二行与第一行处于相同的缩进级别
插入新行并减少缩进一次 (相对于上一行的缩进)。
IndentationRule
描述语言的缩进规则。
属性
如果一行与此模式匹配,则其后的所有行都应减少缩进一次 (直到另一个规则匹配)。
如果一行与此模式匹配,则其后的所有行都应增加缩进一次 (直到另一个规则匹配)。
indentNextLinePattern?: RegExp
如果一行与此模式匹配,则只有其后的下一行应增加缩进一次。
unIndentedLinePattern?: RegExp
如果一行与此模式匹配,则其缩进不应更改,并且不应根据其他规则对其进行评估。
InlayHint
内嵌提示信息。
构造函数
new InlayHint(position: Position, label: string | InlayHintLabelPart[], kind?: InlayHintKind): InlayHint
创建一个新的内嵌提示。
参数 | 描述 |
---|---|
position: Position | 提示的位置。 |
label: string | InlayHintLabelPart[] | 提示的标签。 |
kind?: InlayHintKind | 提示的 种类。 |
返回值 | 描述 |
InlayHint |
属性
kind?: InlayHintKind
此提示的种类。 内嵌提示种类定义了此内嵌提示的外观。
label: string | InlayHintLabelPart[]
此提示的标签。 可读字符串或 标签部分 的数组。
注意 字符串和标签部分都不能为空。
在提示之前呈现内边距。 内边距将使用编辑器的背景颜色,而不是提示本身的背景颜色。 这意味着内边距可用于视觉上对齐/分隔内嵌提示。
在提示后渲染内边距。内边距将使用编辑器的背景颜色,而不是提示本身的背景颜色。这意味着内边距可以用于视觉上对齐/分隔内嵌提示。
position: Position
此提示的位置。
textEdits?: TextEdit[]
tooltip?: string | MarkdownString
当您悬停在此项目上时显示的工具提示文本。
注意,此属性可以在 解析 内嵌提示期间稍后设置。
InlayHintKind
内嵌提示类型。
内联提示的类型定义了其外观,例如,将使用相应的颜色和背景颜色。
枚举成员
用于类型注解的内嵌提示。
用于参数的内嵌提示。
InlayHintLabelPart
内嵌提示标签部分允许内嵌提示的交互式和复合标签。
构造函数
new InlayHintLabelPart(value: string): InlayHintLabelPart
创建一个新的内嵌提示标签部分。
参数 | 描述 |
---|---|
value: string | 该部分的值。 |
返回值 | 描述 |
InlayHintLabelPart |
属性
command?: Command
location?: Location
tooltip?: string | MarkdownString
当您悬停在此标签部分上时显示的工具提示文本。
注意,此属性可以在 解析 内嵌提示期间稍后设置。
此标签部分的值。
InlayHintsProvider<T>
内嵌提示提供程序接口定义了扩展和内嵌提示功能之间的契约。
事件
onDidChangeInlayHints?: Event<void>
一个可选事件,用于指示来自此提供程序的内嵌提示已更改。
方法
provideInlayHints(document: TextDocument, range: Range, token: CancellationToken): ProviderResult<T[]>
为给定的范围和文档提供内嵌提示。
注意,不被给定范围 包含 的内嵌提示将被忽略。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
range: Range | 应计算内嵌提示的范围。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T[]> | 内嵌提示数组或解析为此数组的 thenable 对象。 |
resolveInlayHint(hint: T, token: CancellationToken): ProviderResult<T>
参数 | 描述 |
---|---|
hint: T | 一个内嵌提示。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T> | 已解析的内嵌提示或解析为此提示的 thenable 对象。 可以返回给定的 |
InlineCompletionContext
提供有关请求内联完成的上下文信息。
属性
selectedCompletionInfo: SelectedCompletionInfo
如果自动完成小部件可见,则提供有关其中当前选定项目的信息。
如果已设置,则提供的内联完成必须扩展选定项目的文本并使用相同的范围,否则它们不会显示为预览。例如,如果文档文本是 console.
并且选定项目是 .log
(替换文档中的 .
),则内联完成也必须替换 .
并且以 .log
开头,例如 .log()
。
每当选定项目更改时,都会再次请求内联完成提供程序。
triggerKind: InlineCompletionTriggerKind
描述内联完成的触发方式。
InlineCompletionItem
内联完成项表示以内联方式建议的文本片段,用于完成正在键入的文本。
另请参阅 InlineCompletionItemProvider.provideInlineCompletionItems
构造函数
new InlineCompletionItem(insertText: string | SnippetString, range?: Range, command?: Command): InlineCompletionItem
创建一个新的内联完成项。
参数 | 描述 |
---|---|
insertText: string | SnippetString | 用于替换范围的文本。 |
range?: Range | 要替换的范围。如果未设置,将使用请求位置的单词。 |
command?: Command | 一个可选的 命令,在之后插入此完成时执行。 |
返回值 | 描述 |
InlineCompletionItem |
属性
command?: Command
一个可选的 命令,在之后插入此完成时执行。
用于确定是否应显示此内联完成的文本。当为 falsy
时,将使用 InlineCompletionItem.insertText。
如果要替换的文本是筛选文本的前缀,则显示内联完成。
insertText: string | SnippetString
用于替换范围的文本。必须设置。同时用于预览和接受操作。
range?: Range
要替换的范围。必须在同一行开始和结束。
与插入相比,首选替换,以便在用户删除键入的文本时提供更好的体验。
InlineCompletionItemProvider
内联完成项提供程序接口定义了扩展和内联完成功能之间的契约。
提供程序通过用户手势显式请求完成,或在键入时隐式请求完成。
方法
provideInlineCompletionItems(document: TextDocument, position: Position, context: InlineCompletionContext, token: CancellationToken): ProviderResult<InlineCompletionList | InlineCompletionItem[]>
为给定的位置和文档提供内联完成项。如果启用了内联完成,则每当用户停止键入时,都会调用此方法。当用户显式触发内联完成或显式请求下一个或上一个内联完成时,也会调用此方法。在这种情况下,应返回所有可用的内联完成。 context.triggerKind
可用于区分这些场景。
参数 | 描述 |
---|---|
document: TextDocument | 请求内联完成的文档。 |
position: Position | 请求内联完成的位置。 |
context: InlineCompletionContext | 包含附加信息的上下文对象。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<InlineCompletionList | InlineCompletionItem[]> | 完成项数组或解析为完成项数组的 thenable 对象。 |
InlineCompletionList
表示要在编辑器中呈现的 内联完成项 的集合。
构造函数
new InlineCompletionList(items: InlineCompletionItem[]): InlineCompletionList
创建一个新的内联完成项列表。
参数 | 描述 |
---|---|
items: InlineCompletionItem[] | |
返回值 | 描述 |
InlineCompletionList |
属性
items: InlineCompletionItem[]
内联完成项。
InlineCompletionTriggerKind
描述如何触发 内联完成提供程序。
枚举成员
完成是由用户手势显式触发的。返回多个完成项以启用在它们之间循环。
完成是在编辑时自动触发的。在这种情况下,返回单个完成项就足够了。
InlineValue
内联值信息可以通过不同的方式提供
- 直接作为文本值(类 InlineValueText)。
- 作为用于变量查找的名称(类 InlineValueVariableLookup)
- 作为可评估的表达式(类 InlineValueEvaluatableExpression) InlineValue 类型将所有内联值类型组合为一个类型。
InlineValue: InlineValueText | InlineValueVariableLookup | InlineValueEvaluatableExpression
InlineValueContext
一个值对象,当从 InlineValuesProvider 请求内联值时,其中包含上下文信息。
属性
执行已停止的堆栈帧(作为 DAP ID)。
stoppedLocation: Range
执行已停止的文档范围。通常,范围的结束位置表示显示内联值的行。
InlineValueEvaluatableExpression
通过表达式求值提供内联值。如果仅指定了范围,则将从底层文档中提取表达式。可选的表达式可用于覆盖提取的表达式。
构造函数
new InlineValueEvaluatableExpression(range: Range, expression?: string): InlineValueEvaluatableExpression
创建一个新的 InlineValueEvaluatableExpression 对象。
参数 | 描述 |
---|---|
range: Range | 从中提取可评估表达式的基础文档中的范围。 |
expression?: string | 如果指定,则覆盖提取的表达式。 |
返回值 | 描述 |
InlineValueEvaluatableExpression |
属性
如果指定,则表达式将覆盖提取的表达式。
range: Range
内联值适用的文档范围。该范围用于从底层文档中提取可评估的表达式。
InlineValuesProvider
内联值提供程序接口定义了扩展和编辑器的调试器内联值功能之间的契约。在此契约中,提供程序返回给定文档范围的内联值信息,编辑器在行尾的编辑器中显示此信息。
事件
onDidChangeInlineValues?: Event<void>
一个可选事件,用于指示内联值已更改。
另请参阅 EventEmitter
方法
provideInlineValues(document: TextDocument, viewPort: Range, context: InlineValueContext, token: CancellationToken): ProviderResult<InlineValue[]>
为给定的文档和范围提供“内联值”信息。每当调试在给定文档中停止时,编辑器都会调用此方法。返回的内联值信息在行尾的编辑器中呈现。
参数 | 描述 |
---|---|
document: TextDocument | 需要内联值信息的文档。 |
viewPort: Range | 应计算内联值的可见文档范围。 |
context: InlineValueContext | 包含上下文信息(如当前位置)的包。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<InlineValue[]> | InlineValueDescriptors 数组或解析为此数组的 thenable 对象。 缺少结果可以通过返回 |
InlineValueText
以文本形式提供内联值。
构造函数
new InlineValueText(range: Range, text: string): InlineValueText
创建一个新的 InlineValueText 对象。
参数 | 描述 |
---|---|
range: Range | 在其中显示内联值的文档行。 |
text: string | 要为该行显示的值。 |
返回值 | 描述 |
InlineValueText |
属性
range: Range
内联值适用的文档范围。
内联值的文本。
InlineValueVariableLookup
通过变量查找提供内联值。如果仅指定了范围,则将从底层文档中提取变量名。可选的变量名可用于覆盖提取的名称。
构造函数
new InlineValueVariableLookup(range: Range, variableName?: string, caseSensitiveLookup?: boolean): InlineValueVariableLookup
创建一个新的 InlineValueVariableLookup 对象。
参数 | 描述 |
---|---|
range: Range | 在其中显示内联值的文档行。 |
variableName?: string | 要查找的变量的名称。 |
caseSensitiveLookup?: boolean | 如何执行查找。如果缺少,则查找区分大小写。 |
返回值 | 描述 |
InlineValueVariableLookup |
属性
如何执行查找。
range: Range
内联值适用的文档范围。该范围用于从底层文档中提取变量名。
如果指定,则为要查找的变量的名称。
InputBox
一个具体的 QuickInput,用于让用户输入文本值。
请注意,在许多情况下,更方便的 window.showInputBox 更易于使用。当 window.showInputBox 不提供所需的灵活性时,应使用 window.createInputBox。
事件
onDidAccept: Event<void>
一个事件,指示用户何时表示接受输入值。
onDidChangeValue: Event<string>
一个事件,指示值何时发生更改。
onDidHide: Event<void>
一个事件,指示何时隐藏此输入 UI。
此 UI 可能需要隐藏的原因有多种,扩展程序将通过 QuickInput.onDidHide 收到通知。(示例包括:显式调用 QuickInput.hide、用户按下 Esc、打开其他输入 UI 等)
onDidTriggerButton: Event<QuickInputButton>
一个事件,指示何时触发按钮。
属性
UI 是否应显示进度指示器。默认为 false。
例如,在加载更多数据或验证用户输入时,将其更改为 true。
buttons: readonly QuickInputButton[]
UI 中操作的按钮。
UI 是否应允许用户输入。默认为 true。
例如,在验证用户输入或为用户输入的下一步加载数据时,将其更改为 false。
即使在失去 UI 焦点时,UI 是否应保持打开状态。默认为 false。此设置在 iPad 上被忽略,并且始终为 false。
是否应隐藏输入值。默认为 false。
未输入值时显示的可选占位符。
一个可选的提示文本,向用户提供一些询问或解释。
一个可选的当前步骤计数。
一个可选的标题。
一个可选的总步骤计数。
validationMessage: string | InputBoxValidationMessage
一个可选的验证消息,指示当前输入值存在问题。通过返回字符串,InputBox 将使用默认的 InputBoxValidationSeverity 错误级别。返回 undefined 将清除验证消息。
当前输入值。
valueSelection: readonly [number, number]
输入值中的选定范围。定义为两个数字的元组,其中第一个是包含的起始索引,第二个是不包含的结束索引。当为 undefined
时,将选择整个预填充值;当为空(开始等于结束)时,仅设置光标;否则,将选择定义的范围。
当用户键入或进行选择时,此属性不会更新,但可以由扩展程序更新。
方法
释放此输入 UI 和任何关联的资源。如果它仍然可见,则首先将其隐藏。在此调用之后,输入 UI 将不再起作用,并且不应再访问其上的其他方法或属性。而应创建一个新的输入 UI。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
隐藏此输入 UI。 这也将触发 QuickInput.onDidHide 事件。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
使其输入 UI 在其当前配置中可见。任何其他输入 UI 将首先触发 QuickInput.onDidHide 事件。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
InputBoxOptions
用于配置输入框 UI 行为的选项。
属性
设置为 true
以在焦点移动到编辑器的另一部分或另一个窗口时保持输入框打开。此设置在 iPad 上被忽略,并且始终为 false。
控制是否显示密码输入。密码输入会隐藏键入的文本。
一个可选字符串,在输入框中显示为占位符,以指导用户键入内容。
要在输入框下方显示的文本。
一个可选字符串,表示输入框的标题。
要在输入框中预填充的值。
valueSelection?: [number, number]
选择预填充的 value。定义为两个数字的元组,其中第一个是包含的起始索引,第二个是排除的结束索引。当为 undefined
时,将选择整个预填充值;当为空(起始索引等于结束索引)时,仅设置光标;否则,将选择定义的范围。
方法
validateInput(value: string): string | InputBoxValidationMessage | Thenable<string | InputBoxValidationMessage>
一个可选函数,将用于验证输入并向用户给出提示。
参数 | 描述 |
---|---|
value: string | 输入框的当前值。 |
返回值 | 描述 |
string | InputBoxValidationMessage | Thenable<string | InputBoxValidationMessage> | 一个人类可读的字符串,作为错误消息呈现,或者是一个 InputBoxValidationMessage,它可以提供特定的消息严重性。当 'value' 有效时,返回 |
InputBoxValidationMessage
用于配置验证消息行为的对象。
属性
要显示的验证消息。
severity: InputBoxValidationSeverity
验证消息的严重性。注意:当使用 InputBoxValidationSeverity.Error
时,用户将无法接受(按 ENTER 键)输入。Info
和 Warning
仍然允许 InputBox 接受输入。
InputBoxValidationSeverity
输入框验证的严重性级别。
枚举成员
信息性严重级别。
警告严重级别。
错误严重级别。
LanguageConfiguration
语言配置接口定义了扩展和各种编辑器功能之间的契约,例如自动括号插入、自动缩进等。
属性
__characterPairSupport?: {autoClosingPairs: Array<{close: string, notIn: string[], open: string}>}
已弃用 请勿使用。
- deprecated - * 请改用语言配置文件中的 autoClosingPairs 属性。
参数 | 描述 |
---|---|
autoClosingPairs: Array<{close: string, notIn: string[], open: string}> |
|
__electricCharacterSupport?: {brackets: any, docComment: {close: string, lineStart: string, open: string, scope: string}}
已弃用 请勿使用。
- deprecated - 即将由更好的 API 替代。
参数 | 描述 |
---|---|
brackets: any | 此属性已弃用,并且将被编辑器忽略。
|
docComment: {close: string, lineStart: string, open: string, scope: string} | 此属性已弃用,并且不再被编辑器完全支持(scope 和 lineStart 已被忽略)。请改用语言配置文件中的 autoClosingPairs 属性。
|
autoClosingPairs?: AutoClosingPair[]
该语言的自动闭合配对。
brackets?: CharacterPair[]
该语言的括号。此配置隐式地影响在这些括号周围按 Enter 键的行为。
comments?: CommentRule
该语言的注释设置。
indentationRules?: IndentationRule
该语言的缩进设置。
onEnterRules?: OnEnterRule[]
按下 Enter 键时要评估的语言规则。
该语言的单词定义。如果该语言支持 Unicode 标识符(例如 JavaScript),则最好提供一个使用排除已知分隔符的单词定义。例如:一个正则表达式,匹配除已知分隔符之外的任何内容(并且允许点号出现在浮点数中)
/(-?\d*\.\d\w*)|([^\`\~\!\\#\%\^\&\*\(\)\-\=\+\[\{\]\}\\\|\;\:\'\"\,\.\<\>/\?\s]+)/g
LanguageModelAccessInformation
表示关于语言模型访问的扩展特定信息。
事件
onDidChange: Event<void>
当访问信息更改时触发的事件。
方法
canSendRequest(chat: LanguageModelChat): boolean
检查是否可以向语言模型发出请求。
注意,调用此函数不会触发同意 UI,而只是检查持久化状态。
参数 | 描述 |
---|---|
chat: LanguageModelChat | 一个语言模型聊天对象。 |
返回值 | 描述 |
boolean | 如果可以发出请求,则为 |
LanguageModelChat
表示用于发出聊天请求的语言模型。
另请参阅 lm.selectChatModels
属性
语言模型的不透明家族名称。值可能是 gpt-3.5-turbo
、gpt4
、phi2
或 llama
,但它们由贡献语言的扩展定义,并且可能会更改。
语言模型的不透明标识符。
单个请求中可以发送到模型的最大令牌数。
语言模型的人类可读名称。
语言模型供应商的知名标识符。一个例子是 copilot
,但值由贡献聊天模型的扩展定义,需要与它们一起查找。
模型的不透明版本字符串。这由贡献语言模型的扩展定义,并且可能会更改。
方法
countTokens(text: string | LanguageModelChatMessage, token?: CancellationToken): Thenable<number>
使用模型特定的分词器逻辑计算消息中的令牌数量。
参数 | 描述 |
---|---|
text: string | LanguageModelChatMessage | 一个字符串或消息实例。 |
token?: CancellationToken | 可选的取消令牌。有关如何创建取消令牌,请参阅 CancellationTokenSource。 |
返回值 | 描述 |
Thenable<number> | 一个 thenable,它解析为令牌的数量。 |
sendRequest(messages: LanguageModelChatMessage[], options?: LanguageModelChatRequestOptions, token?: CancellationToken): Thenable<LanguageModelChatResponse>
使用语言模型发出聊天请求。
注意,语言模型的使用可能受到访问限制和用户同意的约束。首次(对于扩展)调用此函数将向用户显示同意对话框,因此此函数必须仅在响应用户操作时调用! 扩展可以使用 LanguageModelAccessInformation.canSendRequest 来检查它们是否具有发出请求的必要权限。
如果无法向语言模型发出请求,此函数将返回一个被拒绝的 Promise。原因可能是
- 用户未给予同意,请参阅
NoPermissions
- 模型不再存在,请参阅
NotFound
- 超出配额限制,请参阅
Blocked
- 其他问题,在这种情况下,扩展必须检查 [LanguageModelError.cause
LanguageModelError.cause
](#LanguageModelError.causeLanguageModelError.cause
)
扩展可以通过将一组工具传递给 LanguageModelChatRequestOptions.tools 来利用语言模型工具调用。语言模型将返回一个 LanguageModelToolCallPart,扩展可以调用该工具并使用结果发出另一个请求。
参数 | 描述 |
---|---|
messages: LanguageModelChatMessage[] | 消息实例数组。 |
options?: LanguageModelChatRequestOptions | 控制请求的选项。 |
token?: CancellationToken | 控制请求的取消令牌。有关如何创建一个取消令牌,请参阅 CancellationTokenSource。 |
返回值 | 描述 |
Thenable<LanguageModelChatResponse> | 一个 thenable,它解析为一个 LanguageModelChatResponse。当请求无法发出时,Promise 将被拒绝。 |
LanguageModelChatMessage
表示聊天中的一条消息。可以扮演不同的角色,例如用户或助手。
静态
Assistant(content: string | Array<LanguageModelTextPart | LanguageModelToolCallPart>, name?: string): LanguageModelChatMessage
用于创建新的助手消息的实用程序。
参数 | 描述 |
---|---|
content: string | Array<LanguageModelTextPart | LanguageModelToolCallPart> | 消息的内容。 |
name?: string | 消息的可选用户名。 |
返回值 | 描述 |
LanguageModelChatMessage |
User(content: string | Array<LanguageModelTextPart | LanguageModelToolResultPart>, name?: string): LanguageModelChatMessage
用于创建新的用户消息的实用程序。
参数 | 描述 |
---|---|
content: string | Array<LanguageModelTextPart | LanguageModelToolResultPart> | 消息的内容。 |
name?: string | 消息的可选用户名。 |
返回值 | 描述 |
LanguageModelChatMessage |
构造函数
new LanguageModelChatMessage(role: LanguageModelChatMessageRole, content: string | Array<LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart>, name?: string): LanguageModelChatMessage
创建一个新的用户消息。
参数 | 描述 |
---|---|
role: LanguageModelChatMessageRole | 消息的角色。 |
content: string | Array<LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart> | 消息的内容。 |
name?: string | 消息的可选用户名。 |
返回值 | 描述 |
LanguageModelChatMessage |
属性
content: Array<LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart>
一个字符串或异构数组,表示消息可以作为内容包含的事物。对于某些模型,某些部分可能是消息类型特定的。
此消息的可选用户名。
role: LanguageModelChatMessageRole
此消息的角色。
LanguageModelChatMessageRole
表示聊天消息的角色。可以是用户或助手。
枚举成员
用户角色,例如与语言模型交互的人。
助手角色,例如生成响应的语言模型。
LanguageModelChatRequestOptions
使用语言模型发出聊天请求的选项。
属性
一条人类可读的消息,解释了为什么需要访问语言模型以及它启用了什么功能。
一组控制语言模型行为的选项。这些选项特定于语言模型,需要在各自的文档中查找。
toolMode?: LanguageModelChatToolMode
要使用的工具选择模式。默认为 LanguageModelChatToolMode.Auto。
tools?: LanguageModelChatTool[]
语言模型可用的可选工具列表。这些可以是可通过 lm.tools 获得的已注册工具,也可以是在调用扩展中实现的私有工具。
如果 LLM 请求调用这些工具之一,它将在 LanguageModelChatResponse.stream 中返回 LanguageModelToolCallPart。调用者有责任调用该工具。如果它是在 lm.tools 中注册的工具,则意味着调用 lm.invokeTool。
然后,可以通过创建一个带有 LanguageModelToolCallPart 的助手类型 LanguageModelChatMessage,然后创建一个带有 LanguageModelToolResultPart 的用户类型消息,将工具结果提供给 LLM。
LanguageModelChatResponse
表示语言模型响应。
属性
stream: AsyncIterable<unknown>
一个异步可迭代对象,它是构成整体响应的文本和工具调用部分的流。LanguageModelTextPart 是助手的响应的一部分,将显示给用户。LanguageModelToolCallPart 是来自语言模型的调用工具的请求。后者仅在工具通过 LanguageModelChatRequestOptions.tools 在请求中传递时返回。unknown
类型用作未来部分的占位符,例如图像数据部分。
注意,如果在数据接收期间发生错误,此流将出错。流的消费者应相应地处理错误。
要取消流,消费者可以 cancel 用于发出请求的令牌或从 for 循环中跳出。
示例
try {
// consume stream
for await (const chunk of response.stream) {
if (chunk instanceof LanguageModelTextPart) {
console.log('TEXT', chunk);
} else if (chunk instanceof LanguageModelToolCallPart) {
console.log('TOOL CALL', chunk);
}
}
} catch (e) {
// stream ended with an error
console.error(e);
}
这等效于从 LanguageModelChatResponse.stream 中过滤掉除文本部分之外的所有内容。
LanguageModelChatSelector
描述如何选择用于聊天请求的语言模型。
另请参阅 lm.selectChatModels
属性
语言模型家族。
语言模型的标识符。
另请参阅 LanguageModelChat.id
语言模型供应商。
语言模型的版本。
LanguageModelChatTool
可通过 LanguageModelChatRequestOptions 提供给语言模型的工具。语言模型使用此接口的所有属性来决定要调用哪个工具以及如何调用它。
属性
工具的描述。
此工具接受的输入的 JSON 模式。
工具的名称。
LanguageModelChatToolMode
语言模型要使用的工具调用模式。
枚举成员
语言模型可以选择调用工具或生成消息。是默认设置。
语言模型必须调用提供的工具之一。注意 - 某些模型在使用此模式时仅支持单个工具。
LanguageModelError
语言模型特定错误的错误类型。
语言模型的消费者应检查 code 属性以确定特定失败原因,例如 if(someError.code === vscode.LanguageModelError.NotFound.name) {...}
,以处理引用未知语言模型的情况。对于未指定的错误,cause
属性将包含实际错误。
静态
Blocked(message?: string): LanguageModelError
请求者被阻止使用此语言模型。
参数 | 描述 |
---|---|
message?: string | |
返回值 | 描述 |
LanguageModelError |
NoPermissions(message?: string): LanguageModelError
请求者没有使用此语言模型的权限
参数 | 描述 |
---|---|
message?: string | |
返回值 | 描述 |
LanguageModelError |
NotFound(message?: string): LanguageModelError
语言模型不存在。
参数 | 描述 |
---|---|
message?: string | |
返回值 | 描述 |
LanguageModelError |
构造函数
new LanguageModelError(message?: string): LanguageModelError
参数 | 描述 |
---|---|
message?: string | |
返回值 | 描述 |
LanguageModelError |
属性
标识此错误的代码。
可能的值是错误名称,例如 NotFound,或者对于来自语言模型本身未指定的错误,为 Unknown
。在后一种情况下,cause
属性将包含实际错误。
LanguageModelPromptTsxPart
一个语言模型响应部分,包含来自 vscode/prompt-tsx
的 PromptElementJSON。
构造函数
new LanguageModelPromptTsxPart(value: unknown): LanguageModelPromptTsxPart
使用给定内容构造一个 prompt-tsx 部分。
参数 | 描述 |
---|---|
value: unknown | 该部分的值,来自 |
返回值 | 描述 |
LanguageModelPromptTsxPart |
属性
该部分的值。
LanguageModelTextPart
一个语言模型响应部分,包含一段文本,从 LanguageModelChatResponse 返回。
构造函数
new LanguageModelTextPart(value: string): LanguageModelTextPart
使用给定内容构造一个文本部分。
参数 | 描述 |
---|---|
value: string | 该部分的文本内容。 |
返回值 | 描述 |
LanguageModelTextPart |
属性
该部分的文本内容。
LanguageModelTool<T>
一个可以通过调用 LanguageModelChat 来调用的工具。
方法
invoke(options: LanguageModelToolInvocationOptions<T>, token: CancellationToken): ProviderResult<LanguageModelToolResult>
使用给定的输入调用工具并返回结果。
提供的 LanguageModelToolInvocationOptions.input 已根据声明的模式进行验证。
参数 | 描述 |
---|---|
options: LanguageModelToolInvocationOptions<T> | |
token: CancellationToken | |
返回值 | 描述 |
ProviderResult<LanguageModelToolResult> |
prepareInvocation(options: LanguageModelToolInvocationPrepareOptions<T>, token: CancellationToken): ProviderResult<PreparedToolInvocation>
在工具被调用之前调用一次。建议实现此方法以自定义工具运行时显示进度消息,并提供更实用的消息,其中包含来自调用输入的上下文。如果适用,还可以发出信号,表明工具在运行前需要用户确认。
- 注意 1: 必须没有副作用。
- 注意 2: 调用
prepareInvocation
不一定之后会调用invoke
。
参数 | 描述 |
---|---|
options: LanguageModelToolInvocationPrepareOptions<T> | |
token: CancellationToken | |
返回值 | 描述 |
ProviderResult<PreparedToolInvocation> |
LanguageModelToolCallPart
语言模型响应部分,指示工具调用,从 LanguageModelChatResponse 返回,也可以作为内容部分包含在 LanguageModelChatMessage 中,以表示聊天请求中之前的工具调用。
构造函数
new LanguageModelToolCallPart(callId: string, name: string, input: object): LanguageModelToolCallPart
创建一个新的 LanguageModelToolCallPart。
参数 | 描述 |
---|---|
callId: string | 工具调用的 ID。 |
name: string | 要调用的工具的名称。 |
input: object | 用于调用工具的输入。 |
返回值 | 描述 |
LanguageModelToolCallPart |
属性
工具调用的 ID。这是聊天请求中工具调用的唯一标识符。
用于调用工具的输入。
要调用的工具的名称。
LanguageModelToolConfirmationMessages
当在 PreparedToolInvocation 中返回此项时,将要求用户在运行工具之前进行确认。这些消息将与“继续”和“取消”按钮一起显示。
属性
message: string | MarkdownString
确认消息的正文。
确认消息的标题。
LanguageModelToolInformation
关于在 lm.tools 中注册的可用工具的信息。
属性
可以传递给语言模型的此工具的描述。
此工具接受的输入的 JSON 模式。
工具的唯一名称。
工具声明的一组标签,大致描述了工具的功能。工具用户可以使用这些标签来过滤工具集,仅保留与手头任务相关的工具。
LanguageModelToolInvocationOptions<T>
为工具调用提供的选项。
属性
用于调用工具的输入。输入必须与 LanguageModelToolInformation.inputSchema 中定义的架构匹配
tokenizationOptions?: LanguageModelToolTokenizationOptions
用于提示工具应在其响应中返回多少令牌的选项,并使工具能够准确地计数令牌。
toolInvocationToken: undefined
一个不透明的对象,将工具调用与来自 聊天参与者 的聊天请求联系起来。
获取有效工具调用令牌的唯一方法是使用来自聊天请求的提供的 toolInvocationToken。 在这种情况下,将在聊天响应视图中自动显示工具调用的进度条,如果工具需要用户确认,它将以内联方式显示在聊天视图中。
如果工具在聊天请求之外被调用,则应传递 undefined
,并且除了确认之外,不会显示任何特殊的 UI。
注意,在其调用期间调用另一个工具的工具可以传递其接收到的 toolInvocationToken
。
LanguageModelToolInvocationPrepareOptions<T>
属性
工具正在使用的输入。
LanguageModelToolResult
从工具调用返回的结果。如果使用 vscode/prompt-tsx
,则可以使用 ToolResult
呈现此结果。
构造函数
new LanguageModelToolResult(content: Array<LanguageModelTextPart | LanguageModelPromptTsxPart>): LanguageModelToolResult
创建 LanguageModelToolResult
参数 | 描述 |
---|---|
content: Array<LanguageModelTextPart | LanguageModelPromptTsxPart> | 工具结果内容部分的列表 |
返回值 | 描述 |
LanguageModelToolResult |
属性
工具结果内容部分的列表。包含 unknown
是因为此列表将来可能会扩展新的内容类型。
另请参见 lm.invokeTool。
LanguageModelToolResultPart
工具调用的结果。这是 工具调用 的对应部分,它只能包含在用户消息的内容中
构造函数
new LanguageModelToolResultPart(callId: string, content: unknown[]): LanguageModelToolResultPart
参数 | 描述 |
---|---|
callId: string | 工具调用的 ID。 |
content: unknown[] | 工具结果的内容。 |
返回值 | 描述 |
LanguageModelToolResultPart |
属性
工具调用的 ID。
注意,这应该与工具调用部分的 callId 匹配。
工具结果的值。
LanguageModelToolTokenizationOptions
与工具调用的令牌化相关的选项。
属性
如果已知,工具应在其结果中发出的最大令牌数。
方法
countTokens(text: string, token?: CancellationToken): Thenable<number>
使用模型特定的分词器逻辑计算消息中的令牌数量。
参数 | 描述 |
---|---|
text: string | 一个字符串。 |
token?: CancellationToken | 可选的取消令牌。有关如何创建取消令牌,请参阅 CancellationTokenSource。 |
返回值 | 描述 |
Thenable<number> | 一个 thenable,它解析为令牌的数量。 |
LanguageStatusItem
语言状态项是显示活动文本编辑器的语言状态报告的首选方式,例如选定的 linter 或通知配置问题。
属性
accessibilityInformation?: AccessibilityInformation
当屏幕阅读器与此项目交互时使用的辅助功能信息
控制项目是否显示为“忙碌”。默认为 false
。
command: Command
此项目的 命令。
可选的、人类可读的此项目的详细信息。
此项目的标识符。
此项目的简称,例如“Java 语言状态”等。
selector: DocumentSelector
一个 选择器,用于定义此项目为哪些编辑器显示。
severity: LanguageStatusSeverity
此项目的严重性。
默认为 information。您可以使用此属性向用户发出信号,表明存在需要注意的问题,例如缺少可执行文件或配置无效。
要为条目显示的文本。您可以通过利用以下语法在文本中嵌入图标
我的文本 $(icon-name) 包含图标,例如 $(icon-name) 这个。
其中 icon-name 取自 ThemeIcon 图标集,例如 light-bulb
、thumbsup
、zap
等。
方法
释放和释放关联的资源。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
LanguageStatusSeverity
表示语言状态的严重性级别。
枚举成员
信息性严重级别。
警告严重级别。
错误严重级别。
LinkedEditingRangeProvider
链接编辑范围提供程序接口定义了扩展与链接编辑功能之间的契约。
方法
provideLinkedEditingRanges(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<LinkedEditingRanges>
对于文档中的给定位置,返回该位置符号的范围以及所有具有相同内容的范围。如果新内容有效,则对其中一个范围的更改可以应用于所有其他范围。可以使用结果返回可选的单词模式,以描述有效内容。如果未提供特定于结果的单词模式,则使用来自语言配置的单词模式。
参数 | 描述 |
---|---|
document: TextDocument | 调用提供程序的文档。 |
position: Position | 调用提供程序的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<LinkedEditingRanges> | 可以一起编辑的范围列表 |
LinkedEditingRanges
表示可以一起编辑的范围列表以及描述有效范围内容的单词模式。
构造函数
new LinkedEditingRanges(ranges: Range[], wordPattern?: RegExp): LinkedEditingRanges
创建一个新的链接编辑范围对象。
参数 | 描述 |
---|---|
ranges: Range[] | 可以一起编辑的范围列表 |
wordPattern?: RegExp | 一个可选的单词模式,用于描述给定范围的有效内容 |
返回值 | 描述 |
LinkedEditingRanges |
属性
ranges: Range[]
可以一起编辑的范围列表。范围必须具有相同的长度和文本内容。这些范围不能重叠。
一个可选的单词模式,用于描述给定范围的有效内容。如果未提供模式,将使用语言配置的单词模式。
Location
表示资源内部的位置,例如文本文件中的一行。
构造函数
new Location(uri: Uri, rangeOrPosition: Range | Position): Location
属性
range: Range
此位置的文档范围。
uri: Uri
此位置的资源标识符。
LocationLink
表示两个位置的连接。提供比普通 位置 更多的元数据,包括原始范围。
属性
originSelectionRange?: Range
此链接的原始范围的跨度。
用作鼠标定义悬停的下划线跨度。默认为定义位置的单词范围。
targetRange: Range
此链接的完整目标范围。
targetSelectionRange?: Range
此链接的跨度。
targetUri: Uri
此链接的目标资源标识符。
LogLevel
日志级别
枚举成员
此级别不记录任何消息。
此级别记录所有消息。
此级别记录调试和更高级别日志级别的消息。
此级别记录信息和更高级别日志级别的消息。
此级别记录警告和更高级别日志级别的消息。
此级别仅记录错误消息。
LogOutputChannel
用于包含日志输出的通道。
要获取 LogOutputChannel
的实例,请使用 createOutputChannel。
事件
onDidChangeLogLevel: Event<LogLevel>
一个 事件,当通道的日志级别更改时触发。
属性
logLevel: LogLevel
通道的当前日志级别。默认为 编辑器日志级别。
此输出通道的人类可读名称。
方法
将给定的值附加到通道。
参数 | 描述 |
---|---|
value: string | 字符串,假值将不会被打印。 |
返回值 | 描述 |
void |
appendLine(value: string): void
将给定的值和一个换行符附加到通道。
参数 | 描述 |
---|---|
value: string | 字符串,假值将被打印。 |
返回值 | 描述 |
void |
从通道中删除所有输出。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
debug(message: string, ...args: any[]): void
将给定的调试消息输出到通道。
仅当通道配置为显示 debug 日志级别或更低级别时,才会记录消息。
参数 | 描述 |
---|---|
message: string | 要记录的调试消息 |
...args: any[] | |
返回值 | 描述 |
void |
释放和释放关联的资源。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
error(error: string | Error, ...args: any[]): void
将给定的错误或错误消息输出到通道。
仅当通道配置为显示 error 日志级别或更低级别时,才会记录消息。
参数 | 描述 |
---|---|
error: string | Error | 要记录的错误或错误消息 |
...args: any[] | |
返回值 | 描述 |
void |
从 UI 中隐藏此通道。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
info(message: string, ...args: any[]): void
将给定的信息消息输出到通道。
仅当通道配置为显示 info 日志级别或更低级别时,才会记录消息。
参数 | 描述 |
---|---|
message: string | 要记录的信息消息 |
...args: any[] | |
返回值 | 描述 |
void |
用给定的值替换通道中的所有输出。
参数 | 描述 |
---|---|
value: string | 字符串,假值将不会被打印。 |
返回值 | 描述 |
void |
show(preserveFocus?: boolean): void
在 UI 中显示此通道。
参数 | 描述 |
---|---|
preserveFocus?: boolean | 当 |
返回值 | 描述 |
void |
show(column?: ViewColumn, preserveFocus?: boolean): void
在 UI 中显示此通道。
- 已弃用 - 使用只有一个参数的重载 (
show(preserveFocus?: boolean): void
)。
参数 | 描述 |
---|---|
column?: ViewColumn | 此参数已弃用,将被忽略。 |
preserveFocus?: boolean | 当 |
返回值 | 描述 |
void |
trace(message: string, ...args: any[]): void
将给定的跟踪消息输出到通道。使用此方法记录详细信息。
仅当通道配置为显示 trace 日志级别时,才会记录消息。
参数 | 描述 |
---|---|
message: string | 要记录的跟踪消息 |
...args: any[] | |
返回值 | 描述 |
void |
warn(message: string, ...args: any[]): void
将给定的警告消息输出到通道。
仅当通道配置为显示 warning 日志级别或更低级别时,才会记录消息。
参数 | 描述 |
---|---|
message: string | 要记录的警告消息 |
...args: any[] | |
返回值 | 描述 |
void |
MarkdownString
人类可读的文本,支持通过 markdown 语法 进行格式化。
当 supportThemeIcons 设置为 true
时,支持通过 $(<name>)
语法渲染 主题图标。
当 supportHtml 设置为 true
时,支持渲染嵌入的 html。
构造函数
new MarkdownString(value?: string, supportThemeIcons?: boolean): MarkdownString
创建一个具有给定值的新 markdown 字符串。
参数 | 描述 |
---|---|
value?: string | 可选的初始值。 |
supportThemeIcons?: boolean | 可选,指定是否在 MarkdownString 中支持 ThemeIcons。 |
返回值 | 描述 |
MarkdownString |
属性
baseUri?: Uri
相对路径相对于其解析的 Uri。
如果 baseUri
以 /
结尾,则将其视为目录,并且 markdown 中的相对路径相对于该目录解析
const md = new vscode.MarkdownString(`[link](./file.js)`);
md.baseUri = vscode.Uri.file('/path/to/dir/');
// Here 'link' in the rendered markdown resolves to '/path/to/dir/file.js'
如果 baseUri
是文件,则 markdown 中的相对路径相对于该文件的父目录解析
const md = new vscode.MarkdownString(`[link](./file.js)`);
md.baseUri = vscode.Uri.file('/path/to/otherFile.js');
// Here 'link' in the rendered markdown resolves to '/path/to/file.js'
isTrusted?: boolean | {enabledCommands: readonly string[]}
表示此 markdown 字符串是否来自受信任的来源。只有受信任的 markdown 支持执行命令的链接,例如 [Run it](command:myCommandId)
。
默认为 false
(命令被禁用)。
表示此 markdown 字符串是否可以包含原始 html 标签。默认为 false
。
当 supportHtml
为 false 时,markdown 渲染器将剥离 markdown 文本中出现的任何原始 html 标签。这意味着您只能使用 markdown 语法进行渲染。
当 supportHtml
为 true 时,markdown 渲染器还将允许渲染安全子集的 html 标签和属性。有关所有支持的标签和属性的列表,请参阅 https://github.com/microsoft/vscode/blob/6d2920473c6f13759c978dd89104c4270a83422d/src/vs/base/browser/markdownRenderer.ts#L296。
表示此 markdown 字符串是否可以包含 ThemeIcons,例如 $(zap)
。
markdown 字符串。
方法
appendCodeblock(value: string, language?: string): MarkdownString
使用提供的语言将给定的字符串作为代码块追加。
参数 | 描述 |
---|---|
value: string | 代码片段。 |
language?: string | 可选的 语言标识符。 |
返回值 | 描述 |
MarkdownString |
appendMarkdown(value: string): MarkdownString
将给定的字符串“按原样”追加到此 markdown 字符串。当 supportThemeIcons 为 true
时,value
中的 ThemeIcons 将被图标化。
参数 | 描述 |
---|---|
value: string | Markdown 字符串。 |
返回值 | 描述 |
MarkdownString |
appendText(value: string): MarkdownString
将给定的字符串追加并转义到此 markdown 字符串。
参数 | 描述 |
---|---|
value: string | 纯文本。 |
返回值 | 描述 |
MarkdownString |
MarkedString
MarkedString 可用于渲染人类可读的文本。它可以是 markdown 字符串,也可以是提供语言和代码片段的代码块。请注意,markdown 字符串将被清理 - 这意味着 html 将被转义。
- 已弃用 - 此类型已弃用,请使用 MarkdownString 代替。
MarkedString: string | {language: string, value: string}
Memento
Memento 表示存储实用程序。它可以存储和检索值。
方法
返回值。
参数 | 描述 |
---|---|
key: string | 一个字符串。 |
返回值 | 描述 |
T | 存储的值或 |
get<T>(key: string, defaultValue: T): T
返回值。
参数 | 描述 |
---|---|
key: string | 一个字符串。 |
defaultValue: T | 当给定键没有值 ( |
返回值 | 描述 |
T | 存储的值或 defaultValue。 |
返回存储的键。
参数 | 描述 |
---|---|
返回值 | 描述 |
readonly string[] | 存储的键。 |
update(key: string, value: any): Thenable<void>
存储一个值。该值必须是可 JSON 字符串化的。
注意:使用 undefined
作为值会从底层存储中删除该键。
参数 | 描述 |
---|---|
key: string | 一个字符串。 |
value: any | 一个值。必须不包含循环引用。 |
返回值 | 描述 |
Thenable<void> |
MessageItem
属性
模态对话框的提示,指示当用户取消对话框时(例如,通过按 ESC 键)应触发该项。
注意:此选项对于非模态消息将被忽略。
简短的标题,如“重试”、“打开日志”等。
MessageOptions
属性
人类可读的详细消息,以较不突出的方式渲染。注意:详细信息仅针对 模态 消息显示。
表示此消息应为模态。
NotebookCell
属性
document: TextDocument
此单元格的 文本,表示为文本文档。
executionSummary: NotebookCellExecutionSummary
此单元格最近的 执行摘要。
此单元格在其 包含的 notebook 中的索引。当单元格在其 notebook 中移动时,索引会更新。当单元格已从其 notebook 中删除时,索引为 -1
。
kind: NotebookCellKind
此单元格的类型。
此单元格的元数据。可以是任何内容,但必须是可 JSON 字符串化的。
notebook: NotebookDocument
包含此单元格的 notebook。
outputs: readonly NotebookCellOutput[]
此单元格的输出。
NotebookCellData
NotebookCellData 是 notebook 单元格的原始表示形式。它是 NotebookData 的一部分。
构造函数
new NotebookCellData(kind: NotebookCellKind, value: string, languageId: string): NotebookCellData
创建新的单元格数据。最小单元格数据指定其类型、其源值及其源的语言标识符。
参数 | 描述 |
---|---|
kind: NotebookCellKind | 类型。 |
value: string | 源值。 |
languageId: string | 源值的语言标识符。 |
返回值 | 描述 |
NotebookCellData |
属性
executionSummary?: NotebookCellExecutionSummary
此单元格数据的执行摘要。
kind: NotebookCellKind
此单元格数据的 类型。
此单元格数据的源值的语言标识符。可以使用来自 getLanguages 的任何值。
此单元格数据的任意元数据。可以是任何内容,但必须是可 JSON 字符串化的。
outputs?: NotebookCellOutput[]
此单元格数据的输出。
此单元格数据的源值 - 可以是源代码或格式化文本。
NotebookCellExecution
NotebookCellExecution 是 notebook 控制器 在执行 notebook 单元格时修改它的方式。
当创建单元格执行对象时,单元格进入 [NotebookCellExecutionState.Pending Pending](#NotebookCellExecutionState.Pending Pending) 状态。当在执行任务上调用 start(...) 时,它进入 [NotebookCellExecutionState.Executing Executing](#NotebookCellExecutionState.Executing Executing) 状态。当调用 end(...) 时,它进入 [NotebookCellExecutionState.Idle Idle](#NotebookCellExecutionState.Idle Idle) 状态。
属性
cell: NotebookCell
为其创建此执行的 单元格。
设置和取消设置此单元格执行的顺序。
token: CancellationToken
方法
appendOutput(out: NotebookCellOutput | readonly NotebookCellOutput[], cell?: NotebookCell): Thenable<void>
追加到正在执行的单元格的输出,或追加到受此执行影响的另一个单元格。
参数 | 描述 |
---|---|
out: NotebookCellOutput | readonly NotebookCellOutput[] | 追加到当前输出的输出。 |
cell?: NotebookCell | 为其清除输出的单元格。默认为此执行的 单元格。 |
返回值 | 描述 |
Thenable<void> | 操作完成时解析的 thenable。 |
appendOutputItems(items: NotebookCellOutputItem | readonly NotebookCellOutputItem[], output: NotebookCellOutput): Thenable<void>
将输出项追加到现有的单元格输出。
参数 | 描述 |
---|---|
items: NotebookCellOutputItem | readonly NotebookCellOutputItem[] | 追加到现有输出的输出项。 |
output: NotebookCellOutput | 已存在的输出对象。 |
返回值 | 描述 |
Thenable<void> | 操作完成时解析的 thenable。 |
clearOutput(cell?: NotebookCell): Thenable<void>
清除正在执行的单元格的输出,或清除受此执行影响的另一个单元格的输出。
参数 | 描述 |
---|---|
cell?: NotebookCell | 为其清除输出的单元格。默认为此执行的 单元格。 |
返回值 | 描述 |
Thenable<void> | 操作完成时解析的 thenable。 |
end(success: boolean, endTime?: number): void
发出执行已结束的信号。
参数 | 描述 |
---|---|
success: boolean | 如果为 true,则在单元格状态栏上显示绿色对勾。如果为 false,则显示红色 X。如果未定义,则不显示对勾或 X 图标。 |
endTime?: number | 执行完成的时间,以 Unix 纪元毫秒为单位。 |
返回值 | 描述 |
void |
replaceOutput(out: NotebookCellOutput | readonly NotebookCellOutput[], cell?: NotebookCell): Thenable<void>
替换正在执行的单元格的输出,或替换受此执行影响的另一个单元格的输出。
参数 | 描述 |
---|---|
out: NotebookCellOutput | readonly NotebookCellOutput[] | 替换当前输出的输出。 |
cell?: NotebookCell | 为其清除输出的单元格。默认为此执行的 单元格。 |
返回值 | 描述 |
Thenable<void> | 操作完成时解析的 thenable。 |
replaceOutputItems(items: NotebookCellOutputItem | readonly NotebookCellOutputItem[], output: NotebookCellOutput): Thenable<void>
替换现有单元格输出的所有输出项。
参数 | 描述 |
---|---|
items: NotebookCellOutputItem | readonly NotebookCellOutputItem[] | 替换现有输出项的输出项。 |
output: NotebookCellOutput | 已存在的输出对象。 |
返回值 | 描述 |
Thenable<void> | 操作完成时解析的 thenable。 |
start(startTime?: number): void
发出执行已开始的信号。
参数 | 描述 |
---|---|
startTime?: number | 执行开始的时间,以 Unix 纪元毫秒为单位。用于驱动显示单元格已运行多长时间的时钟。如果未给定,则不会显示时钟。 |
返回值 | 描述 |
void |
NotebookCellExecutionSummary
notebook 单元格执行的摘要。
属性
执行发生的顺序。
执行是否成功完成。
timing?: {endTime: number, startTime: number}
执行开始和结束的时间,以 Unix 时间戳表示
参数 | 描述 |
---|---|
endTime: number | 执行结束时间。 |
startTime: number | 执行开始时间。 |
NotebookCellKind
notebook 单元格类型。
枚举成员
标记单元格是用于显示的格式化源。
NotebookCellOutput
Notebook 单元格输出表示执行单元格的结果。它是多个 输出项 的容器类型,其中包含的项表示相同的结果,但使用不同的 MIME 类型。
构造函数
new NotebookCellOutput(items: NotebookCellOutputItem[], metadata?: ): NotebookCellOutput
创建新的 notebook 输出。
参数 | 描述 |
---|---|
items: NotebookCellOutputItem[] | Notebook 输出项。 |
metadata?: | 可选的元数据。 |
返回值 | 描述 |
NotebookCellOutput |
属性
items: NotebookCellOutputItem[]
此输出的输出项。每个项必须表示相同的结果。注意:每个输出重复的 MIME 类型是无效的,编辑器将只选择其中一个。
new vscode.NotebookCellOutput([
vscode.NotebookCellOutputItem.text('Hello', 'text/plain'),
vscode.NotebookCellOutputItem.text('<i>Hello</i>', 'text/html'),
vscode.NotebookCellOutputItem.text('_Hello_', 'text/markdown'),
vscode.NotebookCellOutputItem.text('Hey', 'text/plain') // INVALID: repeated type, editor will pick just one
]);
此单元格输出的任意元数据。可以是任何内容,但必须是可 JSON 字符串化的。
NotebookCellOutputItem
表示 notebook 输出 的一种形式,由 MIME 类型和数据定义。
静态
error(value: Error): NotebookCellOutputItem
用于创建使用 application/vnd.code.notebook.error
mime 类型的 NotebookCellOutputItem
的工厂函数。
参数 | 描述 |
---|---|
value: Error | 一个错误对象。 |
返回值 | 描述 |
NotebookCellOutputItem | 一个新的输出项对象。 |
json(value: any, mime?: string): NotebookCellOutputItem
用于从 JSON 对象创建 NotebookCellOutputItem
的工厂函数。
注意:此函数不期望“字符串化的 JSON”,而是期望可以字符串化的对象。当传递的值无法进行 JSON 字符串化时,此函数将抛出错误。
参数 | 描述 |
---|---|
value: any | 可 JSON 字符串化的值。 |
mime?: string | 可选的 MIME 类型,默认为 |
返回值 | 描述 |
NotebookCellOutputItem | 一个新的输出项对象。 |
stderr(value: string): NotebookCellOutputItem
用于创建使用 application/vnd.code.notebook.stderr
mime 类型的 NotebookCellOutputItem
的工厂函数。
参数 | 描述 |
---|---|
value: string | 一个字符串。 |
返回值 | 描述 |
NotebookCellOutputItem | 一个新的输出项对象。 |
stdout(value: string): NotebookCellOutputItem
用于创建使用 application/vnd.code.notebook.stdout
mime 类型的 NotebookCellOutputItem
的工厂函数。
参数 | 描述 |
---|---|
value: string | 一个字符串。 |
返回值 | 描述 |
NotebookCellOutputItem | 一个新的输出项对象。 |
text(value: string, mime?: string): NotebookCellOutputItem
用于从字符串创建 NotebookCellOutputItem
的工厂函数。
注意:UTF-8 编码器用于为字符串创建字节。
参数 | 描述 |
---|---|
value: string | 一个字符串。 |
mime?: string | 可选的 MIME 类型,默认为 |
返回值 | 描述 |
NotebookCellOutputItem | 一个新的输出项对象。 |
构造函数
new NotebookCellOutputItem(data: Uint8Array, mime: string): NotebookCellOutputItem
创建一个新的 notebook 单元格输出项。
参数 | 描述 |
---|---|
data: Uint8Array | 输出项的值。 |
mime: string | 输出项的 mime 类型。 |
返回值 | 描述 |
NotebookCellOutputItem |
属性
此输出项的数据。必须始终是无符号 8 位整数数组。
mime 类型,它确定如何解释 data 属性。
Notebook 内置支持某些 mime 类型,扩展可以添加对新类型的支持并覆盖现有类型。
NotebookCellStatusBarAlignment
表示状态栏项的对齐方式。
枚举成员
与左侧对齐。
与右侧对齐。
NotebookCellStatusBarItem
对单元格状态栏的贡献
构造函数
new NotebookCellStatusBarItem(text: string, alignment: NotebookCellStatusBarAlignment): NotebookCellStatusBarItem
创建一个新的 NotebookCellStatusBarItem。
参数 | 描述 |
---|---|
text: string | 要为该项显示的文本。 |
alignment: NotebookCellStatusBarAlignment | 该项是对齐到左侧还是右侧。 |
返回值 | 描述 |
NotebookCellStatusBarItem |
属性
accessibilityInformation?: AccessibilityInformation
当屏幕阅读器与此项交互时使用的辅助功能信息。
alignment: NotebookCellStatusBarAlignment
该项是对齐到左侧还是右侧。
command?: string | Command
该项的优先级。值较高的项将更靠左显示。
要为该项显示的文本。
鼠标悬停在该项上时显示的工具提示。
NotebookCellStatusBarItemProvider
一个提供程序,可以向单元格编辑器下方出现的状态栏贡献项。
事件
onDidChangeCellStatusBarItems?: Event<void>
一个可选事件,用于发出状态栏项已更改的信号。将再次调用 provide 方法。
方法
provideCellStatusBarItems(cell: NotebookCell, token: CancellationToken): ProviderResult<NotebookCellStatusBarItem | NotebookCellStatusBarItem[]>
当单元格滚动到视图中、当其内容、输出、语言或元数据更改以及当其执行状态更改时,将调用提供程序。
参数 | 描述 |
---|---|
cell: NotebookCell | 为其返回项的单元格。 |
token: CancellationToken | 如果应取消此请求,则会触发令牌。 |
返回值 | 描述 |
ProviderResult<NotebookCellStatusBarItem | NotebookCellStatusBarItem[]> | 一个或多个 单元格状态栏项 |
NotebookController
notebook 控制器表示可以执行 notebook 单元格的实体。这通常被称为内核。
可以有多个控制器,编辑器将让用户选择要用于特定 notebook 的控制器。notebookType 属性定义控制器适用于哪种 notebook,而 updateNotebookAffinity 函数允许控制器为特定的 notebook 文档设置首选项。当控制器被选中后,其 onDidChangeSelectedNotebooks 事件会触发。
当单元格正在运行时,编辑器将调用 executeHandler,并且控制器需要创建和完成一个 notebook cell execution。但是,控制器也可以自由地自行创建 execution。
事件
onDidChangeSelectedNotebooks: Event<{notebook: NotebookDocument, selected: boolean}>
属性
人类可读的描述,渲染时不太突出。
人类可读的详细信息,渲染时不太突出。
executeHandler: (cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController) => void | Thenable<void>
当在 UI 中选择运行手势时(例如,运行单元格、全部运行、运行所选内容等),将调用 execute handler。Execute handler 负责创建和管理 execution 对象。
参数 | 描述 |
---|---|
cells: NotebookCell[] | |
notebook: NotebookDocument | |
controller: NotebookController | |
返回值 | 描述 |
void | Thenable<void> |
此笔记本控制器的标识符。
注意,控制器通过其标识符记住,并且扩展应在会话之间使用稳定的标识符。
interruptHandler?: (notebook: NotebookDocument) => void | Thenable<void>
可选的中断处理程序。
默认情况下,单元格执行通过 tokens 取消。取消令牌要求控制器可以跟踪其执行,以便稍后可以取消特定的执行。并非所有场景都允许这样做,例如,REPL 样式的控制器通常通过中断当前正在运行的任何内容来工作。对于这些情况,存在中断处理程序 - 它可以被认为是终端中 SIGINT
或 Control+C
的等效项。
注意,支持 取消令牌 是首选,并且只有在无法支持令牌时才应使用中断处理程序。
参数 | 描述 |
---|---|
notebook: NotebookDocument | |
返回值 | 描述 |
void | Thenable<void> |
此笔记本控制器的人类可读标签。
此控制器适用的笔记本类型。
此控制器支持的语言标识符数组。来自 getLanguages 的任何语言标识符都是可能的。当为 falsy 时,支持所有语言。
示例
// support JavaScript and TypeScript
myController.supportedLanguages = ['javascript', 'typescript'];
// support all languages
myController.supportedLanguages = undefined; // falsy
myController.supportedLanguages = []; // falsy
supportsExecutionOrder?: boolean
此控制器是否支持执行顺序,以便编辑器可以为其呈现占位符。
方法
createNotebookCellExecution(cell: NotebookCell): NotebookCellExecution
创建单元格执行任务。
注意,一次每个单元格只能有一个执行,如果在另一个执行仍在活动状态时创建单元格执行,则会抛出错误。
这应在响应 execution handler 被调用时使用,或者在单元格执行已启动时使用,例如,当单元格已在执行或单元格执行从另一个源触发时。
参数 | 描述 |
---|---|
cell: NotebookCell | 要为其创建执行的笔记本单元格。 |
返回值 | 描述 |
NotebookCellExecution | 一个笔记本单元格执行。 |
释放和释放关联的资源。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
updateNotebookAffinity(notebook: NotebookDocument, affinity: NotebookControllerAffinity): void
控制器可以为特定的笔记本文档设置亲和性。这允许控制器对于某些笔记本更突出地显示。
参数 | 描述 |
---|---|
notebook: NotebookDocument | 为其设置优先级的笔记本。 |
affinity: NotebookControllerAffinity | 控制器亲和性 |
返回值 | 描述 |
void |
NotebookControllerAffinity
笔记本控制器对笔记本文档的亲和性。
枚举成员
默认亲和性。
控制器是笔记本的首选。
NotebookData
构造函数
new NotebookData(cells: NotebookCellData[]): NotebookData
创建新的笔记本数据。
参数 | 描述 |
---|---|
cells: NotebookCellData[] | 单元格数据数组。 |
返回值 | 描述 |
NotebookData |
属性
cells: NotebookCellData[]
此笔记本数据的单元格数据。
笔记本数据的任意元数据。
NotebookDocument
属性
笔记本中的单元格数量。
如果笔记本已关闭,则为 true
。关闭的笔记本不再同步,并且当再次打开相同的资源时不会重复使用。
如果存在未持久化的更改,则为 true
。
此笔记本是否表示尚未保存的未命名文件。
此笔记本的任意元数据。可以是任何内容,但必须是 JSON 可字符串化的。
笔记本的类型。
uri: Uri
此笔记本的关联 URI。
注意,大多数笔记本使用 file
方案,这意味着它们是磁盘上的文件。但是,并非所有笔记本都保存在磁盘上,因此在尝试访问底层文件或磁盘上的同级文件之前,必须检查 scheme
。
另请参阅 FileSystemProvider
此笔记本的版本号(在每次更改后都会严格增加,包括撤消/重做)。
方法
cellAt(index: number): NotebookCell
返回指定索引处的单元格。索引将调整为笔记本。
参数 | 描述 |
---|---|
index: number | 要检索的单元格的索引。 |
返回值 | 描述 |
NotebookCell | 一个 单元格。 |
getCells(range?: NotebookRange): NotebookCell[]
获取此笔记本的单元格。可以通过提供范围来检索子集。范围将调整为笔记本。
参数 | 描述 |
---|---|
range?: NotebookRange | 一个笔记本范围。 |
返回值 | 描述 |
NotebookCell[] | 范围或所有单元格包含的单元格。 |
保存文档。保存将由相应的 serializer 处理。
参数 | 描述 |
---|---|
返回值 | 描述 |
Thenable<boolean> | 一个 Promise,当文档已保存时将解析为 true。如果文件未修改或保存失败,将返回 false。 |
NotebookDocumentCellChange
描述对笔记本单元格的更改。
属性
cell: NotebookCell
受影响的单元格。
document: TextDocument
单元格的文档,或者当它没有更改时为 undefined
。
注意,您应该使用 onDidChangeTextDocument 事件来获取详细的更改信息,例如已执行的编辑。
executionSummary: NotebookCellExecutionSummary
单元格的新执行摘要,或者当它没有更改时为 undefined
。
单元格的新元数据,或者当它没有更改时为 undefined
。
outputs: readonly NotebookCellOutput[]
单元格的新输出,或者当它们没有更改时为 undefined
。
NotebookDocumentChangeEvent
描述事务性 notebook 更改的事件。
属性
cellChanges: readonly NotebookDocumentCellChange[]
一个 单元格更改 数组。
contentChanges: readonly NotebookDocumentContentChange[]
描述添加或删除 单元格 的内容更改数组。
笔记本的新元数据,或者当它没有更改时为 undefined
。
notebook: NotebookDocument
受影响的笔记本。
NotebookDocumentContentChange
描述笔记本文档的结构性更改,例如新添加和删除的单元格。
属性
addedCells: readonly NotebookCell[]
已添加到文档的单元格。
range: NotebookRange
已添加或删除单元格的范围。
请注意,当此范围为 空 时,没有 removedCells。
removedCells: readonly NotebookCell[]
已从文档中删除的单元格。
NotebookDocumentContentOptions
笔记本内容选项定义了笔记本的哪些部分被持久化。注意
例如,笔记本序列化器可以选择不保存输出,在这种情况下,当笔记本的输出发生更改时,编辑器不会将笔记本标记为 dirty。
属性
控制单元格元数据属性更改事件是否会触发笔记本文档内容更改事件,以及是否会在差异编辑器中使用,默认为 false。如果内容提供程序未在文件文档中持久化元数据属性,则应将其设置为 true。
控制文档元数据属性更改事件是否会触发笔记本文档内容更改事件,以及是否会在差异编辑器中使用,默认为 false。如果内容提供程序未在文件文档中持久化元数据属性,则应将其设置为 true。
控制输出更改事件是否会触发笔记本文档内容更改事件,以及是否会在差异编辑器中使用,默认为 false。如果内容提供程序未在文件文档中持久化输出,则应将其设置为 true。
NotebookDocumentShowOptions
表示配置在 notebook editor 中显示 notebook document 的行为的选项。
属性
一个可选标志,当为 true
时,将阻止 notebook editor 获取焦点。
一个可选标志,控制 notebook editor 选项卡是否显示为预览。预览选项卡将被替换和重用,直到设置为保持 - 显式或通过编辑。默认行为取决于 workbench.editor.enablePreview
设置。
selections?: readonly NotebookRange[]
要在 notebook editor 中为文档应用的可选选择。
viewColumn?: ViewColumn
应在其中显示 notebook editor 的可选视图列。默认为 active。不存在的列将根据需要创建,最多为 ViewColumn.Nine。使用 ViewColumn.Beside 将编辑器打开到当前活动编辑器的侧面。
NotebookDocumentWillSaveEvent
当 notebook document 即将保存时触发的事件。
要在文档保存之前对其进行修改,请使用解析为 workspace edit 的 thenable 调用 waitUntil 函数。
属性
notebook: NotebookDocument
即将保存的 notebook document。
reason: TextDocumentSaveReason
触发保存的原因。
token: CancellationToken
取消令牌。
方法
waitUntil(thenable: Thenable<WorkspaceEdit>): void
允许暂停事件循环并应用 workspace edit。后续调用此函数的编辑将按顺序应用。如果笔记本文档发生并发修改,则编辑将被忽略。
注意: 此函数只能在事件分发期间调用,而不能以异步方式调用
workspace.onWillSaveNotebookDocument(event => {
// async, will *throw* an error
setTimeout(() => event.waitUntil(promise));
// sync, OK
event.waitUntil(promise);
});
参数 | 描述 |
---|---|
thenable: Thenable<WorkspaceEdit> | 解析为 workspace edit 的 thenable。 |
返回值 | 描述 |
void |
waitUntil(thenable: Thenable<any>): void
允许暂停事件循环,直到提供的 thenable 解析。
注意: 此函数只能在事件分发期间调用。
参数 | 描述 |
---|---|
thenable: Thenable<any> | 一个延迟保存的 thenable。 |
返回值 | 描述 |
void |
NotebookEdit
笔记本编辑表示应应用于笔记本内容的编辑。
静态
deleteCells(range: NotebookRange): NotebookEdit
用于创建编辑以删除笔记本中单元格的实用程序。
参数 | 描述 |
---|---|
range: NotebookRange | 要删除的单元格范围。 |
返回值 | 描述 |
NotebookEdit |
insertCells(index: number, newCells: NotebookCellData[]): NotebookEdit
用于创建编辑以替换笔记本中单元格的实用程序。
参数 | 描述 |
---|---|
index: number | 插入单元格的索引。 |
newCells: NotebookCellData[] | 新的笔记本单元格。 |
返回值 | 描述 |
NotebookEdit |
replaceCells(range: NotebookRange, newCells: NotebookCellData[]): NotebookEdit
用于创建编辑以替换笔记本中单元格的实用程序。
参数 | 描述 |
---|---|
range: NotebookRange | 要替换的单元格范围 |
newCells: NotebookCellData[] | 新的笔记本单元格。 |
返回值 | 描述 |
NotebookEdit |
updateCellMetadata(index: number, newCellMetadata: ): NotebookEdit
用于创建编辑以更新单元格元数据的实用程序。
参数 | 描述 |
---|---|
index: number | 要更新的单元格的索引。 |
newCellMetadata: | 单元格的新元数据。 |
返回值 | 描述 |
NotebookEdit |
updateNotebookMetadata(newNotebookMetadata: ): NotebookEdit
用于创建编辑以更新笔记本元数据的实用程序。
参数 | 描述 |
---|---|
newNotebookMetadata: | 笔记本的新元数据。 |
返回值 | 描述 |
NotebookEdit |
构造函数
new NotebookEdit(range: NotebookRange, newCells: NotebookCellData[]): NotebookEdit
创建一个新的笔记本编辑。
参数 | 描述 |
---|---|
range: NotebookRange | 一个笔记本范围。 |
newCells: NotebookCellData[] | 新的单元格数据数组。 |
返回值 | 描述 |
NotebookEdit |
属性
单元格的可选新元数据。
newCells: NotebookCellData[]
正在插入的新单元格。可能为空。
笔记本的可选新元数据。
range: NotebookRange
正在编辑的单元格的范围。可能为空。
NotebookEditor
表示附加到 notebook 的笔记本编辑器。NotebookEditor 的其他属性在建议的 API 中可用,稍后将最终确定。
属性
notebook: NotebookDocument
与此笔记本编辑器关联的 notebook document。
selection: NotebookRange
此笔记本编辑器中的主选择。
selections: readonly NotebookRange[]
此笔记本编辑器中的所有选择。
主选择(或焦点范围)是 selections[0]
。当文档没有单元格时,主选择为空 { start: 0, end: 0 }
;
viewColumn?: ViewColumn
此编辑器显示的列。
visibleRanges: readonly NotebookRange[]
编辑器中当前可见的范围(垂直方向)。
方法
revealRange(range: NotebookRange, revealType?: NotebookEditorRevealType): void
按照 revealType
的指示滚动,以显示给定的范围。
参数 | 描述 |
---|---|
range: NotebookRange | 一个范围。 |
revealType?: NotebookEditorRevealType | 用于显示 |
返回值 | 描述 |
void |
NotebookEditorRevealType
表示附加到 notebook 的笔记本编辑器。
枚举成员
将以尽可能少的滚动显示范围。
范围将始终在视口的中心显示。
如果范围在视口之外,则它将在视口的中心显示。否则,它将以尽可能少的滚动显示。
范围将始终在视口的顶部显示。
NotebookEditorSelectionChangeEvent
表示描述 notebook editor 的选择 更改的事件。
属性
notebookEditor: NotebookEditor
其选择已更改的 notebook editor。
selections: readonly NotebookRange[]
notebook editor 的选择 的新值。
NotebookEditorVisibleRangesChangeEvent
表示描述 notebook editor 的 visibleRanges 更改的事件。
属性
notebookEditor: NotebookEditor
其 visible ranges 已更改的 notebook editor。
visibleRanges: readonly NotebookRange[]
NotebookRange
notebook range 表示两个单元格索引的有序对。保证 start 小于或等于 end。
构造函数
new NotebookRange(start: number, end: number): NotebookRange
创建一个新的 notebook range。如果 start
不早于或等于 end
,则这些值将被交换。
参数 | 描述 |
---|---|
start: number | 起始索引 |
end: number | 结束索引。 |
返回值 | 描述 |
NotebookRange |
属性
此范围的独占结束索引(从零开始)。
如果 start
和 end
相等,则为 true
。
此范围的从零开始的起始索引。
方法
with(change: {end: number, start: number}): NotebookRange
为此范围派生一个新范围。
参数 | 描述 |
---|---|
change: {end: number, start: number} | 描述此范围更改的对象。 |
返回值 | 描述 |
NotebookRange | 反映给定更改的范围。如果更改未更改任何内容,将返回 |
NotebookRendererMessaging
Renderer messaging 用于与单个渲染器通信。它从 notebooks.createRendererMessaging 返回。
事件
onDidReceiveMessage: Event<{editor: NotebookEditor, message: any}>
当从渲染器接收到消息时触发的事件。
方法
postMessage(message: any, editor?: NotebookEditor): Thenable<boolean>
向一个或所有渲染器发送消息。
参数 | 描述 |
---|---|
message: any | 要发送的消息 |
editor?: NotebookEditor | 要将消息定向到的编辑器。如果未提供,则消息将发送到所有渲染器。 |
返回值 | 描述 |
Thenable<boolean> | 一个布尔值,指示消息是否已成功传递到任何渲染器。 |
NotebookSerializer
notebook serializer 使编辑器能够打开 notebook 文件。
在其核心,编辑器只知道 notebook 数据结构,但不知道该数据结构如何写入文件,也不知道如何从文件读取。notebook serializer 通过将字节反序列化为 notebook 数据,反之亦然,来弥合这一差距。
方法
deserializeNotebook(content: Uint8Array, token: CancellationToken): NotebookData | Thenable<NotebookData>
将 notebook 文件的内容反序列化为 notebook 数据结构。
参数 | 描述 |
---|---|
content: Uint8Array | notebook 文件的内容。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
NotebookData | Thenable<NotebookData> | Notebook 数据或可解析为 Notebook 数据的 Thenable 对象。 |
serializeNotebook(data: NotebookData, token: CancellationToken): Uint8Array | Thenable<Uint8Array>
将 notebook 数据序列化为文件内容。
参数 | 描述 |
---|---|
data: NotebookData | Notebook 数据结构。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
Uint8Array | Thenable<Uint8Array> | 字节数组或可解析为这种数组的可 Thenable 对象。 |
OnEnterRule
描述按下 Enter 键时要评估的规则。
属性
action: EnterAction
要执行的操作。
仅当光标后的文本与此正则表达式匹配时,此规则才会执行。
仅当光标前的文本与此正则表达式匹配时,此规则才会执行。
仅当当前行上方的文本与此正则表达式匹配时,此规则才会执行。
OnTypeFormattingEditProvider
文档格式化提供程序接口定义了扩展和格式化功能之间的约定。
方法
provideOnTypeFormattingEdits(document: TextDocument, position: Position, ch: string, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>
在键入字符后提供格式化编辑。
给定的位置和字符应提示提供程序要扩展到的范围位置,例如在输入 }
时查找匹配的 {
。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
ch: string | 已键入的字符。 |
options: FormattingOptions | 控制格式化的选项。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<TextEdit[]> | 一组文本编辑或一个可解析为此的 thenable 对象。 缺少结果可以通过返回 |
OpenDialogOptions
用于配置文件打开对话框行为的选项。
- 注意 1:在 Windows 和 Linux 上,文件对话框不能同时作为文件选择器和文件夹选择器,因此如果在这些平台上将
canSelectFiles
和canSelectFolders
都设置为true
,则将显示文件夹选择器。 - 注意 2:显式将
canSelectFiles
和canSelectFolders
设置为false
是徒劳的,编辑器然后会静默调整选项以选择文件。
属性
允许选择文件,默认为 true
。
允许选择文件夹,默认为 false
。
允许选择多个文件或文件夹。
defaultUri?: Uri
对话框打开时显示的资源。
对话框使用的一组文件过滤器。每个条目都是人类可读的标签,例如“TypeScript”,以及扩展名数组,例如
{
'Images': ['png', 'jpg'],
'TypeScript': ['ts', 'tsx']
}
打开按钮的人类可读字符串。
对话框标题。
此参数可能会被忽略,因为并非所有操作系统都在打开对话框上显示标题(例如,macOS)。
OutputChannel
输出通道是只读文本信息的容器。
要获取 OutputChannel
的实例,请使用 createOutputChannel。
属性
此输出通道的人类可读名称。
方法
将给定的值附加到通道。
参数 | 描述 |
---|---|
value: string | 字符串,假值将不会被打印。 |
返回值 | 描述 |
void |
appendLine(value: string): void
将给定的值和一个换行符附加到通道。
参数 | 描述 |
---|---|
value: string | 字符串,假值将被打印。 |
返回值 | 描述 |
void |
从通道中删除所有输出。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
释放和释放关联的资源。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
从 UI 中隐藏此通道。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
用给定的值替换通道中的所有输出。
参数 | 描述 |
---|---|
value: string | 字符串,假值将不会被打印。 |
返回值 | 描述 |
void |
show(preserveFocus?: boolean): void
在 UI 中显示此通道。
参数 | 描述 |
---|---|
preserveFocus?: boolean | 当 |
返回值 | 描述 |
void |
show(column?: ViewColumn, preserveFocus?: boolean): void
在 UI 中显示此通道。
- 已弃用 - 使用只有一个参数的重载 (
show(preserveFocus?: boolean): void
)。
参数 | 描述 |
---|---|
column?: ViewColumn | 此参数已弃用,将被忽略。 |
preserveFocus?: boolean | 当 |
返回值 | 描述 |
void |
OverviewRulerLane
表示在 overview ruler 中渲染装饰的不同位置。overview ruler 支持三个通道。
枚举成员
overview ruler 的左侧通道。
overview ruler 的中心通道。
overview ruler 的右侧通道。
overview ruler 的所有通道。
ParameterInformation
表示可调用签名的参数。参数可以具有标签和文档注释。
构造函数
new ParameterInformation(label: string | [number, number], documentation?: string | MarkdownString): ParameterInformation
创建一个新的 parameter information 对象。
参数 | 描述 |
---|---|
label: string | [number, number] | 标签字符串或包含签名标签内的包含起始偏移量和独占结束偏移量。 |
documentation?: string | MarkdownString | 文档字符串。 |
返回值 | 描述 |
ParameterInformation |
属性
documentation?: string | MarkdownString
此签名的人类可读文档注释。将在 UI 中显示,但可以省略。
label: string | [number, number]
此签名的标签。
字符串或包含签名信息 signature label 内的包含起始偏移量和独占结束偏移量。注意:字符串类型的标签必须是其包含签名信息的 label 的子字符串。
Position
构造函数
new Position(line: number, character: number): Position
参数 | 描述 |
---|---|
line: number | 从零开始的行值。 |
character: number | 从零开始的字符值。 |
返回值 | 描述 |
Position |
属性
从零开始的字符值。
从零开始的行值。
方法
compareTo(other: Position): number
将此位置与 other
进行比较。
参数 | 描述 |
---|---|
other: Position | 一个位置。 |
返回值 | 描述 |
number | 如果此位置在给定位置之前,则为小于零的数字;如果此位置在给定位置之后,则为大于零的数字;如果此位置和给定位置相等,则为零。 |
isAfter(other: Position): boolean
检查此位置是否在 other
之后。
参数 | 描述 |
---|---|
other: Position | 一个位置。 |
返回值 | 描述 |
boolean | 如果位置在更大的行上,或者在同一行上但在更大的字符上,则为 |
isAfterOrEqual(other: Position): boolean
检查此位置是否在 other
之后或与之相等。
参数 | 描述 |
---|---|
other: Position | 一个位置。 |
返回值 | 描述 |
boolean | 如果位置在更大的行上,或者在同一行上但在更大或相等的字符上,则为 |
isBefore(other: Position): boolean
检查此位置是否在 other
之前。
参数 | 描述 |
---|---|
other: Position | 一个位置。 |
返回值 | 描述 |
boolean | 如果位置在更小的行上,或者在同一行上但在更小的字符上,则为 |
isBeforeOrEqual(other: Position): boolean
检查此位置是否在 other
之前或与之相等。
参数 | 描述 |
---|---|
other: Position | 一个位置。 |
返回值 | 描述 |
boolean | 如果位置在更小的行上,或者在同一行上但在更小或相等的字符上,则为 |
isEqual(other: Position): boolean
检查此位置是否等于 other
。
参数 | 描述 |
---|---|
other: Position | 一个位置。 |
返回值 | 描述 |
boolean | 如果给定位置的行和字符与此位置的行和字符相等,则为 |
translate(lineDelta?: number, characterDelta?: number): Position
创建相对于此位置的新位置。
参数 | 描述 |
---|---|
lineDelta?: number | 行值的增量值,默认为 |
characterDelta?: number | 字符值的增量值,默认为 |
返回值 | 描述 |
Position | 行和字符是当前行和字符与相应增量之和的位置。 |
translate(change: {characterDelta: number, lineDelta: number}): Position
派生相对于此位置的新位置。
参数 | 描述 |
---|---|
change: {characterDelta: number, lineDelta: number} | 描述此位置增量的对象。 |
返回值 | 描述 |
Position | 反映给定增量的位置。如果更改未更改任何内容,将返回 |
with(line?: number, character?: number): Position
创建从此位置派生的新位置。
with(change: {character: number, line: number}): Position
从此位置派生新位置。
参数 | 描述 |
---|---|
change: {character: number, line: number} | 描述此位置更改的对象。 |
返回值 | 描述 |
Position | 反映给定更改的位置。如果更改未更改任何内容,将返回 |
PreparedToolInvocation
属性
confirmationMessages?: LanguageModelToolConfirmationMessages
此属性的存在表明应要求用户在运行工具之前进行确认。对于任何具有副作用或可能存在危险的工具,都应要求用户进行确认。
invocationMessage?: string | MarkdownString
在工具运行时显示的自定义进度消息。
ProcessExecution
任务的执行作为外部进程发生,没有 shell 交互。
构造函数
new ProcessExecution(process: string, options?: ProcessExecutionOptions): ProcessExecution
创建进程执行。
参数 | 描述 |
---|---|
process: string | 要启动的进程。 |
options?: ProcessExecutionOptions | 启动进程的可选选项。 |
返回值 | 描述 |
ProcessExecution |
new ProcessExecution(process: string, args: string[], options?: ProcessExecutionOptions): ProcessExecution
创建进程执行。
参数 | 描述 |
---|---|
process: string | 要启动的进程。 |
args: string[] | 要传递给进程的参数。 |
options?: ProcessExecutionOptions | 启动进程的可选选项。 |
返回值 | 描述 |
ProcessExecution |
属性
传递给进程的参数。默认为空数组。
options?: ProcessExecutionOptions
执行进程时使用的进程选项。默认为 undefined。
要执行的进程。
ProcessExecutionOptions
进程执行的选项
属性
已执行程序或 shell 的当前工作目录。如果省略,则使用工具的当前工作区根目录。
执行的程序或 shell 的附加环境。如果省略,则使用父进程的环境。如果提供,则将其与父进程的环境合并。
Progress<T>
定义报告进度更新的通用方法。
方法
报告进度更新。
参数 | 描述 |
---|---|
value: T | 进度项,例如消息和/或关于完成多少工作的报告 |
返回值 | 描述 |
void |
ProgressLocation
编辑器中可以显示进度信息的位置。进度在视觉上的表示方式取决于位置。
枚举成员
显示源代码管理视图的进度,作为图标的叠加层和视图内的进度条(可见时)。两者都不支持取消或离散进度,也不支持描述操作的标签。
在编辑器的状态栏中显示进度。既不支持取消也不支持离散进度。支持通过进度标签中的 $(<name>)
语法渲染 主题图标。
将进度显示为带有可选取消按钮的通知。支持显示无限和离散进度,但不支持渲染图标。
ProgressOptions
描述进度应显示的位置和方式的值对象。
属性
控制是否应显示取消按钮以允许用户取消长时间运行的操作。请注意,目前只有 ProgressLocation.Notification
支持显示取消按钮。
location: ProgressLocation | {viewId: string}
应显示进度的位置。
将用于描述操作的人类可读字符串。
ProviderResult<T>
提供程序结果表示提供程序(例如 HoverProvider)可能返回的值。首先,这是实际结果类型 T
,例如 Hover
,或可解析为该类型 T
的 thenable 对象。此外,可以返回 null
和 undefined
- 可以直接返回,也可以从 thenable 对象返回。
以下代码段都是 HoverProvider 的有效实现
let a: HoverProvider = {
provideHover(doc, pos, token): ProviderResult<Hover> {
return new Hover('Hello World');
}
};
let b: HoverProvider = {
provideHover(doc, pos, token): ProviderResult<Hover> {
return new Promise(resolve => {
resolve(new Hover('Hello World'));
});
}
};
let c: HoverProvider = {
provideHover(doc, pos, token): ProviderResult<Hover> {
return; // undefined
}
};
ProviderResult: T | undefined | null | Thenable<T | undefined | null>
PseudoterminalPseudoterminal
定义终端 pty 的接口,使扩展能够控制终端。
事件
Pseudoterminal.onDidChangeNameonDidChangeName?: Event<string>
当事件触发时,允许更改终端名称。
在调用 Pseudoterminal.open 之前触发的事件将被忽略。
示例: 将终端名称更改为“My new terminal”。
const writeEmitter = new vscode.EventEmitter<string>();
const changeNameEmitter = new vscode.EventEmitter<string>();
const pty: vscode.Pseudoterminal = {
onDidWrite: writeEmitter.event,
onDidChangeName: changeNameEmitter.event,
open: () => changeNameEmitter.fire('My new terminal'),
close: () => {}
};
vscode.window.createTerminal({ name: 'My terminal', pty });
Pseudoterminal.onDidCloseonDidClose?: Event<number | void>
当事件触发时,将发出 pty 已关闭的信号并释放终端。
在调用 Pseudoterminal.open 之前触发的事件将被忽略。
数字可以用于为终端提供退出代码。退出代码必须为正数,非零退出代码表示失败,这将为常规终端显示通知,并允许依赖任务在使用 CustomExecution
API 时继续执行。
示例: 当按下“y”时退出终端,否则显示通知。
const writeEmitter = new vscode.EventEmitter<string>();
const closeEmitter = new vscode.EventEmitter<void>();
const pty: vscode.Pseudoterminal = {
onDidWrite: writeEmitter.event,
onDidClose: closeEmitter.event,
open: () => writeEmitter.fire('Press y to exit successfully'),
close: () => {},
handleInput: data => {
if (data !== 'y') {
vscode.window.showInformationMessage('Something went wrong');
}
closeEmitter.fire();
}
};
const terminal = vscode.window.createTerminal({ name: 'Exit example', pty });
terminal.show(true);
Pseudoterminal.onDidOverrideDimensionsonDidOverrideDimensions?: Event<TerminalDimensions>
当事件触发时,允许覆盖终端的 dimensions。请注意,设置后,覆盖的尺寸仅在低于终端的实际尺寸时才生效(即,永远不会出现滚动条)。设置为 undefined
使终端返回常规尺寸(适应面板大小)。
在调用 Pseudoterminal.open 之前触发的事件将被忽略。
示例: 将终端的尺寸覆盖为 20 列和 10 行
const dimensionsEmitter = new vscode.EventEmitter<vscode.TerminalDimensions>();
const pty: vscode.Pseudoterminal = {
onDidWrite: writeEmitter.event,
onDidOverrideDimensions: dimensionsEmitter.event,
open: () => {
dimensionsEmitter.fire({
columns: 20,
rows: 10
});
},
close: () => {}
};
vscode.window.createTerminal({ name: 'My terminal', pty });
Pseudoterminal.onDidWriteonDidWrite: Event<string>
当事件触发时,将数据写入终端。与 Terminal.sendText 将文本发送到下层子伪设备(子设备)不同,这将把文本写入父伪设备(终端本身)。
请注意,写入 \n
只会将光标向下移动 1 行,您还需要写入 \r
以将光标移动到最左侧的单元格。
在调用 Pseudoterminal.open 之前触发的事件将被忽略。
示例: 将红色文本写入终端
const writeEmitter = new vscode.EventEmitter<string>();
const pty: vscode.Pseudoterminal = {
onDidWrite: writeEmitter.event,
open: () => writeEmitter.fire('\x1b[31mHello world\x1b[0m'),
close: () => {}
};
vscode.window.createTerminal({ name: 'My terminal', pty });
示例: 将光标移动到第 10 行和第 20 列,并写入星号
writeEmitter.fire('\x1b[10;20H*');
方法
Pseudoterminal.closeclose(): void
实现以处理用户操作关闭终端时的情况。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
Pseudoterminal.handleInputhandleInput(data: string): void
实现以处理终端中传入的击键或扩展调用 Terminal.sendText 时的情况。data
包含序列化为其对应的 VT 序列表示形式的击键/文本。
参数 | 描述 |
---|---|
data: string | 传入的数据。 示例: 在终端中回显输入。回车符 (
|
返回值 | 描述 |
void |
Pseudoterminal.openopen(initialDimensions: TerminalDimensions): void
实现以处理 pty 打开并准备好开始触发事件时的情况。
参数 | 描述 |
---|---|
initialDimensions: TerminalDimensions | 终端的尺寸,如果终端面板在此调用之前未打开,则此值将为 undefined。 |
返回值 | 描述 |
void |
Pseudoterminal.setDimensionssetDimensions(dimensions: TerminalDimensions): void
实现以处理终端面板中可以容纳的行数和列数发生变化时的情况,例如,当字体大小发生变化或面板大小调整时。在触发此事件之前,终端尺寸的初始状态应被视为 undefined
,因为终端的大小在用户界面中显示之前是未知的。
当尺寸被 Pseudoterminal.onDidOverrideDimensions 覆盖时,setDimensions
将继续使用常规面板尺寸进行调用,从而允许扩展继续响应尺寸变化。
参数 | 描述 |
---|---|
dimensions: TerminalDimensions | 新的尺寸。 |
返回值 | 描述 |
void |
QuickDiffProviderQuickDiffProvider
快速差异提供程序提供一个 uri,指向已修改资源的原始状态。编辑器将使用此信息在文本中呈现临时的差异。
方法
QuickDiffProvider.provideOriginalResourceprovideOriginalResource(uri: Uri, token: CancellationToken): ProviderResult<T><Uri>
为任何给定的资源 uri 提供指向原始资源的 Uri。
参数 | 描述 |
---|---|
uri: Uri | 在文本编辑器中打开的资源的 uri。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T><Uri> | 一个 thenable,它解析为匹配的原始资源的 uri。 |
QuickInputQuickInput
一个轻量级的用户输入 UI,最初不可见。在通过其属性进行配置后,扩展可以通过调用 QuickInput.show 使其可见。
此 UI 可能需要隐藏的原因有多种,扩展程序将通过 QuickInput.onDidHide 收到通知。(示例包括:显式调用 QuickInput.hide、用户按下 Esc、打开其他输入 UI 等)
用户按下 Enter 键或表示接受当前状态的其他手势不会自动隐藏此 UI 组件。是否接受用户的输入以及是否应通过调用 QuickInput.hide 隐藏 UI 取决于扩展。
当扩展不再需要此输入 UI 时,应 QuickInput.dispose 它以释放与其关联的任何资源。
事件
QuickInput.onDidHideonDidHide: Event<void>
一个事件,指示何时隐藏此输入 UI。
此 UI 可能需要隐藏的原因有多种,扩展程序将通过 QuickInput.onDidHide 收到通知。(示例包括:显式调用 QuickInput.hide、用户按下 Esc、打开其他输入 UI 等)
属性
QuickInput.busybusy: boolean
UI 是否应显示进度指示器。默认为 false。
例如,在加载更多数据或验证用户输入时,将其更改为 true。
QuickInput.enabledenabled: boolean
UI 是否应允许用户输入。默认为 true。
例如,在验证用户输入或为用户输入的下一步加载数据时,将其更改为 false。
QuickInput.ignoreFocusOutignoreFocusOut: boolean
即使在失去 UI 焦点时,UI 是否应保持打开状态。默认为 false。此设置在 iPad 上被忽略,并且始终为 false。
QuickInput.stepstep: number
一个可选的当前步骤计数。
QuickInput.titletitle: string
一个可选的标题。
QuickInput.totalStepstotalSteps: number
一个可选的总步骤计数。
方法
QuickInput.disposedispose(): void
释放此输入 UI 和任何关联的资源。如果它仍然可见,则首先将其隐藏。在此调用之后,输入 UI 将不再起作用,并且不应再访问其上的其他方法或属性。而应创建一个新的输入 UI。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
QuickInput.hidehide(): void
隐藏此输入 UI。 这也将触发 QuickInput.onDidHide 事件。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
QuickInput.showshow(): void
使其输入 UI 在其当前配置中可见。任何其他输入 UI 将首先触发 QuickInput.onDidHide 事件。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
QuickInputButtonQuickInputButton
属性
QuickInputButton.iconPathiconPath: IconPath
按钮的图标。
QuickInputButton.tooltiptooltip?: string
可选的工具提示。
QuickInputButtonsQuickInputButtons
静态
QuickInputButtons.BackBack: QuickInputButton
QuickPick<T>QuickPick<T>
一个具体的 QuickInput,用于让用户从类型为 T 的项目列表中选择一个项目。可以通过过滤器文本字段过滤项目,并且有一个选项 QuickPick.canSelectMany 允许选择多个项目。
请注意,在许多情况下,更方便的 window.showQuickPick 更易于使用。当 window.showQuickPick 不提供所需的灵活性时,应使用 window.createQuickPick。
事件
QuickPick.onDidAcceptonDidAccept: Event<void>
当用户指示接受所选项目时发出的事件。
QuickPick.onDidChangeActiveonDidChangeActive: Event<readonly T[]>
当活动项目发生更改时发出的事件。
QuickPick.onDidChangeSelectiononDidChangeSelection: Event<readonly T[]>
当选定项目发生更改时发出的事件。
QuickPick.onDidChangeValueonDidChangeValue: Event<string>
当过滤器文本的值发生更改时发出的事件。
QuickPick.onDidHideonDidHide: Event<void>
一个事件,指示何时隐藏此输入 UI。
此 UI 可能需要隐藏的原因有多种,扩展程序将通过 QuickInput.onDidHide 收到通知。(示例包括:显式调用 QuickInput.hide、用户按下 Esc、打开其他输入 UI 等)
QuickPick.onDidTriggerButtononDidTriggerButton: Event<QuickInputButton>
当触发顶层按钮(存储在 QuickPick.buttons 中的按钮)时发出的事件。此事件不会为 QuickPickItem 上的按钮触发。
QuickPick.onDidTriggerItemButtononDidTriggerItemButton: Event<QuickPickItemButtonEvent<T>>
当触发特定 QuickPickItem 中的按钮时发出的事件。此事件不会为标题栏中的按钮触发。
属性
QuickPick.activeItemsactiveItems: readonly T[]
活动项目。扩展可以读取和更新此项。
QuickPick.busybusy: boolean
UI 是否应显示进度指示器。默认为 false。
例如,在加载更多数据或验证用户输入时,将其更改为 true。
QuickPick.buttonsbuttons: readonly QuickInputButton[]
UI 中操作的按钮。
QuickPick.canSelectManycanSelectMany: boolean
是否可以同时选择多个项目。默认为 false。
QuickPick.enabledenabled: boolean
UI 是否应允许用户输入。默认为 true。
例如,在验证用户输入或为用户输入的下一步加载数据时,将其更改为 false。
QuickPick.ignoreFocusOutignoreFocusOut: boolean
即使在失去 UI 焦点时,UI 是否应保持打开状态。默认为 false。此设置在 iPad 上被忽略,并且始终为 false。
QuickPick.itemsitems: readonly T[]
要从中选择的项目。扩展可以读取和更新此项。
QuickPick.keepScrollPositionkeepScrollPosition?: boolean
一个可选标志,用于在快速选择项目更新时保持快速选择的滚动位置。默认为 false。
QuickPick.matchOnDescriptionmatchOnDescription: boolean
过滤器文本是否也应与项目的描述匹配。默认为 false。
QuickPick.matchOnDetailmatchOnDetail: boolean
过滤器文本是否也应与项目的详细信息匹配。默认为 false。
QuickPick.placeholderplaceholder: string
当未输入任何过滤器时,在过滤器文本框中显示的可选占位符。
QuickPick.selectedItemsselectedItems: readonly T[]
选定的项目。扩展可以读取和更新此项。
QuickPick.stepstep: number
一个可选的当前步骤计数。
QuickPick.titletitle: string
一个可选的标题。
QuickPick.totalStepstotalSteps: number
一个可选的总步骤计数。
QuickPick.valuevalue: string
过滤器文本的当前值。
方法
QuickPick.disposedispose(): void
释放此输入 UI 和任何关联的资源。如果它仍然可见,则首先将其隐藏。在此调用之后,输入 UI 将不再起作用,并且不应再访问其上的其他方法或属性。而应创建一个新的输入 UI。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
QuickPick.hidehide(): void
隐藏此输入 UI。 这也将触发 QuickInput.onDidHide 事件。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
QuickPick.showshow(): void
使其输入 UI 在其当前配置中可见。任何其他输入 UI 将首先触发 QuickInput.onDidHide 事件。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
QuickPickItemQuickPickItem
表示可以从项目列表中选择的项目。
属性
QuickPickItem.alwaysShowalwaysShow?: boolean
始终显示此项目。
注意:当 QuickPickItem.kind 设置为 QuickPickItemKind.Separator 时,此属性将被忽略
QuickPickItem.buttonsbuttons?: readonly QuickInputButton[]
将在此特定项目上呈现的可选按钮。单击这些按钮将触发 QuickPickItemButtonEvent。仅当使用 window.createQuickPick API 创建的 quickpick 时,才会呈现按钮。当使用 window.showQuickPick API 时,不会呈现按钮。
注意:当 QuickPickItem.kind 设置为 QuickPickItemKind.Separator 时,此属性将被忽略
QuickPickItem.descriptiondescription?: string
一个人可读的字符串,在同一行中以较不突出的方式呈现。支持通过 $(<name>)
语法呈现 theme icons。
注意:当 QuickPickItem.kind 设置为 QuickPickItemKind.Separator 时,此属性将被忽略
QuickPickItem.detaildetail?: string
一个人可读的字符串,在单独的行中以较不突出的方式呈现。支持通过 $(<name>)
语法呈现 theme icons。
注意:当 QuickPickItem.kind 设置为 QuickPickItemKind.Separator 时,此属性将被忽略
QuickPickItem.iconPathiconPath?: IconPath
QuickPickItem 的图标路径或 ThemeIcon。
QuickPickItem.kindkind?: QuickPickItemKind
QuickPickItem 的种类,它将决定此项目在快速选择中的呈现方式。如果未指定,则默认为 QuickPickItemKind.Default。
QuickPickItem.labellabel: string
一个人可读的字符串,以突出的方式呈现。支持通过 $(<name>)
语法呈现 theme icons。
QuickPickItem.pickedpicked?: boolean
可选标志,指示此项目是否最初被选中。仅在使用 window.showQuickPick API 时才有效。要使用 window.createQuickPick API 执行相同的操作,只需将 QuickPick.selectedItems 设置为您想要最初选中的项目。(注意:仅当选择器允许多项选择时才有效。)
另请参阅 QuickPickOptions.canPickMany
注意:当 QuickPickItem.kind 设置为 QuickPickItemKind.Separator 时,此属性将被忽略
QuickPickItemButtonEvent<T>QuickPickItemButtonEvent<T>
当触发特定 QuickPickItem 中的按钮时发出的事件。此事件不会为标题栏中的按钮触发。
属性
QuickPickItemButtonEvent.buttonbutton: QuickInputButton
被单击的按钮。
QuickPickItemButtonEvent.itemitem: T
按钮所属的项目。
QuickPickItemKindQuickPickItemKind
快速选择项目的种类。
枚举成员
QuickPickItemKind.SeparatorSeparator: -1
当 QuickPickItem 的种类为 QuickPickItemKind.Separator 时,该项目仅为视觉分隔符,不代表真实的项目。唯一适用的属性是 QuickPickItem.label。QuickPickItem 上的所有其他属性都将被忽略,并且不起作用。
QuickPickItemKind.DefaultDefault: 0
默认的 QuickPickItem.kind 是可以在快速选择中选择的项目。
QuickPickOptionsQuickPickOptions
用于配置快速选择 UI 行为的选项。
事件
QuickPickOptions.onDidSelectItemonDidSelectItem(item: string | QuickPickItem): any
一个可选函数,每当选择一个项目时调用。
参数 | 描述 |
---|---|
item: string | QuickPickItem | |
返回值 | 描述 |
any |
属性
QuickPickOptions.canPickManycanPickMany?: boolean
一个可选标志,使选择器接受多项选择,如果为 true,则结果是一个选择数组。
QuickPickOptions.ignoreFocusOutignoreFocusOut?: boolean
设置为 true
以在焦点移动到编辑器的另一部分或另一个窗口时保持选择器打开。此设置在 iPad 上被忽略,并且始终为 false。
QuickPickOptions.matchOnDescriptionmatchOnDescription?: boolean
一个可选标志,用于在过滤选择时包含描述。
QuickPickOptions.matchOnDetailmatchOnDetail?: boolean
一个可选标志,用于在过滤选择时包含详细信息。
QuickPickOptions.placeHolderplaceHolder?: string
一个可选字符串,在输入框中显示为占位符,以指导用户选择什么。
QuickPickOptions.titletitle?: string
一个可选字符串,表示快速选择的标题。
RangeRange
范围表示两个位置的有序对。保证 Range.start.isBeforeOrEqual(Range.end)
Range 对象是不可变的。使用 Range.with、Range.intersection 或 Range.union 方法从现有范围派生新范围。
构造函数
Range.new Rangenew Range(start: Position, end: Position): Range
Range.new Rangenew Range(startLine: number, startCharacter: number, endLine: number, endCharacter: number): Range
从数字坐标创建一个新范围。它是使用 new Range(new Position(startLine, startCharacter), new Position(endLine, endCharacter))
的较短等效方式
参数 | 描述 |
---|---|
startLine: number | 从零开始的行值。 |
startCharacter: number | 从零开始的字符值。 |
endLine: number | 从零开始的行值。 |
endCharacter: number | 从零开始的字符值。 |
返回值 | 描述 |
范围 |
属性
结束位置。它在 Range.start 之后或与其相等。
Range.isEmptyisEmpty: boolean
如果 start
和 end
相等,则为 true
。
Range.isSingleLineisSingleLine: boolean
如果 start.line
和 end.line
相等,则为 true
。
start: Position
起始位置。它早于或等于 end。
方法
contains(positionOrRange: Range | Position): boolean
检查一个位置或范围是否包含在此范围内。
intersection(range: Range): Range
将 range
与此范围相交,并返回一个新的范围;如果范围没有重叠,则返回 undefined
。
isEqual(other: Range): boolean
with(start?: Position, end?: Position): Range
从此范围派生出一个新范围。
with(change: {end: Position, start: Position}): Range
从此范围派生出一个新范围。
ReferenceContext
值对象,用于在请求引用时包含附加信息。
属性
包含当前符号的声明。
ReferenceProvider
引用提供程序接口定义了扩展与 查找引用 功能之间的约定。
方法
provideReferences(document: TextDocument, position: Position, context: ReferenceContext, token: CancellationToken): ProviderResult<Location[]>
为给定的位置和文档提供一组项目范围的引用。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
context: ReferenceContext | 有关引用请求的附加信息。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<Location[]> | 位置数组或解析为此数组的可 Thenable 对象。缺少结果可以通过返回 |
RelativePattern
相对模式是一个辅助工具,用于构造相对于基础文件路径匹配的 glob 模式。基础路径可以是绝对文件路径(字符串或 URI)或 工作区文件夹,这是创建相对模式的首选方式。
构造函数
new RelativePattern(base: string | Uri | WorkspaceFolder, pattern: string): RelativePattern
创建一个新的相对模式对象,其中包含基础文件路径和要匹配的模式。此模式将在相对于基础路径的文件路径上进行匹配。
示例
const folder = vscode.workspace.workspaceFolders?.[0];
if (folder) {
// Match any TypeScript file in the root of this workspace folder
const pattern1 = new vscode.RelativePattern(folder, '*.ts');
// Match any TypeScript file in `someFolder` inside this workspace folder
const pattern2 = new vscode.RelativePattern(folder, 'someFolder/*.ts');
}
参数 | 描述 |
---|---|
base: string | Uri | WorkspaceFolder | 此模式将相对于其进行匹配的基础。如果模式应在工作区内匹配,建议传入 工作区文件夹。否则,只有当模式用于工作区外部的文件路径时,才应使用 URI 或字符串。 |
pattern: string | 文件 glob 模式,例如 |
返回值 | 描述 |
RelativePattern |
属性
此模式将相对于其进行匹配的基础文件路径。
这与 RelativePattern.baseUri 的 fsPath
值匹配。
注意: 更新此值将更新 RelativePattern.baseUri 以使其成为具有 file
方案的 URI。
- 已弃用 - 此属性已弃用,请改用 RelativePattern.baseUri。
baseUri: Uri
此模式将相对于其进行匹配的基础文件路径。文件路径必须是绝对路径,不应包含任何尾部路径分隔符,并且不包含任何相对段(.
或 ..
)。
文件 glob 模式,例如 *.{ts,js}
,它将在相对于基础路径的文件路径上进行匹配。
示例:给定基础路径 /home/work/folder
和文件路径 /home/work/folder/index.js
,文件 glob 模式将在 index.js
上匹配。
RenameProvider
重命名提供程序接口定义了扩展与 重命名符号 功能之间的约定。
方法
prepareRename(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Range | {placeholder: string, range: Range}>
用于在运行重命名前可选解析和验证位置的函数。结果可以是范围,也可以是范围和占位符文本。占位符文本应为正在重命名的符号的标识符 - 如果省略,则使用返回范围中的文本。
注意: 当提供的位置不允许重命名时,此函数应抛出错误或返回被拒绝的 Thenable 对象。
参数 | 描述 |
---|---|
document: TextDocument | 将在其中调用重命名的文档。 |
position: Position | 将在其中调用重命名的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<Range | {placeholder: string, range: Range}> | 要重命名的标识符的范围或范围和占位符文本。缺少结果可以通过返回 |
provideRenameEdits(document: TextDocument, position: Position, newName: string, token: CancellationToken): ProviderResult<WorkspaceEdit>
提供一个编辑,描述为了将符号重命名为不同的名称,必须对一个或多个资源进行的更改。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
newName: string | 符号的新名称。如果给定的名称无效,则提供程序必须返回被拒绝的 Promise 对象。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<WorkspaceEdit> | 工作区编辑或解析为此编辑的可 Thenable 对象。缺少结果可以通过返回 |
RunOptions
任务的运行选项。
属性
控制在重新运行时是否重新评估任务变量。
SaveDialogOptions
用于配置文件保存对话框行为的选项。
属性
defaultUri?: Uri
对话框打开时显示的资源。
对话框使用的一组文件过滤器。每个条目都是人类可读的标签,例如“TypeScript”,以及扩展名数组,例如
{
'Images': ['png', 'jpg'],
'TypeScript': ['ts', 'tsx']
}
保存按钮的人工可读字符串。
对话框标题。
此参数可能会被忽略,因为并非所有操作系统都在保存对话框上显示标题(例如,macOS)。
SecretStorage
表示用于存储加密的密钥(或任何敏感信息)的存储实用程序。密钥存储的实现将在每个平台上有所不同,并且密钥不会跨计算机同步。
事件
onDidChange: Event<SecretStorageChangeEvent>
当密钥被存储或删除时触发。
方法
delete(key: string): Thenable<void>
从存储中删除密钥。
参数 | 描述 |
---|---|
key: string | 存储密钥所使用的键。 |
返回值 | 描述 |
Thenable<void> |
get(key: string): Thenable<string>
检索使用键存储的密钥。如果不存在与该键匹配的密码,则返回 undefined。
参数 | 描述 |
---|---|
key: string | 存储密钥所使用的键。 |
返回值 | 描述 |
Thenable<string> | 存储的值或 |
store(key: string, value: string): Thenable<void>
在给定的键下存储密钥。
参数 | 描述 |
---|---|
key: string | 用于存储密钥的键。 |
value: string | 密钥。 |
返回值 | 描述 |
Thenable<void> |
SecretStorageChangeEvent
当密钥被添加或删除时触发的事件数据。
属性
已更改的密钥的键。
SelectedCompletionInfo
描述当前选定的完成项。
属性
range: Range
如果接受此完成项,将被替换的范围。
如果接受此完成项,范围将被替换为的文本。
Selection
表示编辑器中的文本选择。
构造函数
new Selection(anchor: Position, active: Position): Selection
new Selection(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number): Selection
从四个坐标创建选择。
参数 | 描述 |
---|---|
anchorLine: number | 从零开始的行值。 |
anchorCharacter: number | 从零开始的字符值。 |
activeLine: number | 从零开始的行值。 |
activeCharacter: number | 从零开始的字符值。 |
返回值 | 描述 |
Selection |
属性
active: Position
光标的位置。此位置可能在 anchor 之前或之后。
anchor: Position
选择开始的位置。此位置可能在 active 之前或之后。
end: Position
结束位置。它在 Range.start 之后或与其相等。
如果 start
和 end
相等,则为 true
。
如果 start.line
和 end.line
相等,则为 true
。
start: Position
起始位置。它早于或等于 end。
方法
contains(positionOrRange: Range | Position): boolean
检查一个位置或范围是否包含在此范围内。
intersection(range: Range): Range
将 range
与此范围相交,并返回一个新的范围;如果范围没有重叠,则返回 undefined
。
isEqual(other: Range): boolean
with(start?: Position, end?: Position): Range
从此范围派生出一个新范围。
with(change: {end: Position, start: Position}): Range
从此范围派生出一个新范围。
SelectionRange
选择范围表示选择层次结构的一部分。选择范围可能具有包含它的父选择范围。
构造函数
new SelectionRange(range: Range, parent?: SelectionRange): SelectionRange
创建一个新的选择范围。
参数 | 描述 |
---|---|
range: Range | 选择范围的范围。 |
parent?: SelectionRange | 选择范围的父范围。 |
返回值 | 描述 |
SelectionRange |
属性
parent?: SelectionRange
包含此范围的父选择范围。
range: Range
此选择范围的 Range。
SelectionRangeProvider
选择范围提供程序接口定义了扩展与“展开和收缩选择”功能之间的约定。
方法
provideSelectionRanges(document: TextDocument, positions: readonly Position[], token: CancellationToken): ProviderResult<SelectionRange[]>
为给定的位置提供选择范围。
选择范围应该为每个位置单独且独立地计算。编辑器将合并和去重范围,但提供程序必须返回选择范围的层次结构,以便范围被其父范围 包含。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
positions: readonly Position[] | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<SelectionRange[]> | 选择范围或解析为此范围的可 Thenable 对象。缺少结果可以通过返回 |
SemanticTokens
表示语义标记,可以是在一个范围内,也可以是在整个文档中。
另请参阅
- 有关格式的说明,请参阅 provideDocumentSemanticTokens。
- 有关创建实例的帮助程序,请参阅 SemanticTokensBuilder。
构造函数
new SemanticTokens(data: Uint32Array, resultId?: string): SemanticTokens
创建新的语义标记。
参数 | 描述 |
---|---|
data: Uint32Array | 标记数据。 |
resultId?: string | 结果标识符。 |
返回值 | 描述 |
SemanticTokens |
属性
实际的标记数据。
另请参阅 provideDocumentSemanticTokens 以获取有关格式的说明。
标记的结果 ID。
这是将传递给 DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits
(如果已实现)的 ID。
SemanticTokensBuilder
语义标记构建器可以帮助创建包含增量编码语义标记的 SemanticTokens
实例。
构造函数
new SemanticTokensBuilder(legend?: SemanticTokensLegend): SemanticTokensBuilder
创建一个语义标记构建器。
参数 | 描述 |
---|---|
legend?: SemanticTokensLegend | 语义标记图例。 |
返回值 | 描述 |
SemanticTokensBuilder |
方法
build(resultId?: string): SemanticTokens
完成并创建一个 SemanticTokens
实例。
参数 | 描述 |
---|---|
resultId?: string | |
返回值 | 描述 |
SemanticTokens |
push(line: number, char: number, length: number, tokenType: number, tokenModifiers?: number): void
添加另一个标记。
参数 | 描述 |
---|---|
line: number | 标记起始行号(绝对值)。 |
char: number | 标记起始字符(绝对值)。 |
length: number | 标记长度(字符数)。 |
tokenType: number | 编码的标记类型。 |
tokenModifiers?: number | 编码的标记修饰符。 |
返回值 | 描述 |
void |
push(range: Range, tokenType: string, tokenModifiers?: readonly string[]): void
添加另一个标记。仅在提供图例时使用。
参数 | 描述 |
---|---|
range: Range | 标记的范围。必须是单行。 |
tokenType: string | 标记类型。 |
tokenModifiers?: readonly string[] | 标记修饰符。 |
返回值 | 描述 |
void |
SemanticTokensEdit
表示对语义标记的编辑。
另请参阅 provideDocumentSemanticTokensEdits 以获取有关格式的说明。
构造函数
new SemanticTokensEdit(start: number, deleteCount: number, data?: Uint32Array): SemanticTokensEdit
创建语义标记编辑。
参数 | 描述 |
---|---|
start: number | 起始偏移量 |
deleteCount: number | 要删除的元素数量。 |
data?: Uint32Array | 要插入的元素 |
返回值 | 描述 |
SemanticTokensEdit |
属性
要插入的元素。
要删除的元素计数。
编辑的起始偏移量。
SemanticTokensEdits
表示对语义标记的编辑。
另请参阅 provideDocumentSemanticTokensEdits 以获取有关格式的说明。
构造函数
new SemanticTokensEdits(edits: SemanticTokensEdit[], resultId?: string): SemanticTokensEdits
创建新的语义标记编辑。
参数 | 描述 |
---|---|
edits: SemanticTokensEdit[] | 语义标记编辑数组 |
resultId?: string | 结果标识符。 |
返回值 | 描述 |
SemanticTokensEdits |
属性
edits: SemanticTokensEdit[]
对标记数据的编辑。所有编辑都引用初始数据状态。
标记的结果 ID。
这是将传递给 DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits
(如果已实现)的 ID。
SemanticTokensLegend
语义标记图例包含解密语义标记的整数编码表示形式所需的必要信息。
构造函数
new SemanticTokensLegend(tokenTypes: string[], tokenModifiers?: string[]): SemanticTokensLegend
创建语义标记图例。
参数 | 描述 |
---|---|
tokenTypes: string[] | 标记类型数组。 |
tokenModifiers?: string[] | 标记修饰符数组。 |
返回值 | 描述 |
SemanticTokensLegend |
属性
可能的标记修饰符。
可能的标记类型。
ShellExecution
表示在 shell 内部发生的任务执行。
构造函数
new ShellExecution(commandLine: string, options?: ShellExecutionOptions): ShellExecution
使用完整的命令行创建 shell 执行。
参数 | 描述 |
---|---|
commandLine: string | 要执行的命令行。 |
options?: ShellExecutionOptions | 启动 shell 的可选选项。 |
返回值 | 描述 |
ShellExecution |
new ShellExecution(command: string | ShellQuotedString, args: Array<string | ShellQuotedString>, options?: ShellExecutionOptions): ShellExecution
使用命令和参数创建 shell 执行。对于实际执行,编辑器将从命令和参数构造命令行。这会受到解释,尤其是在涉及引用时。如果需要完全控制命令行,请使用使用完整命令行创建 ShellExecution
的构造函数。
参数 | 描述 |
---|---|
command: string | ShellQuotedString | 要执行的命令。 |
args: Array<string | ShellQuotedString> | 命令参数。 |
options?: ShellExecutionOptions | 启动 shell 的可选选项。 |
返回值 | 描述 |
ShellExecution |
属性
args: Array<string | ShellQuotedString>
shell 参数。如果使用完整命令行创建,则为 undefined
。
command: string | ShellQuotedString
shell 命令。如果使用完整命令行创建,则为 undefined
。
shell 命令行。如果使用命令和参数创建,则为 undefined
。
options?: ShellExecutionOptions
在 shell 中执行命令行时使用的 shell 选项。默认为 undefined。
ShellExecutionOptions
shell 执行的选项
属性
执行的 shell 的当前工作目录。如果省略,则使用工具的当前工作区根目录。
执行的 shell 的附加环境。如果省略,则使用父进程的环境。如果提供,则将其与父进程的环境合并。
shell 可执行文件。
要传递给用于运行任务的 shell 可执行文件的参数。大多数 shell 需要特殊参数来执行命令。例如,bash
需要 -c
参数来执行命令,PowerShell
需要 -Command
,而 cmd
同时需要 /d
和 /c
。
shellQuoting?: ShellQuotingOptions
此 shell 支持的 shell 引用。
ShellQuotedString
一个字符串,将根据使用的 shell 进行引用。
属性
quoting: ShellQuoting
要使用的引用样式。
实际的字符串值。
ShellQuoting
定义如果参数包含空格或不支持的字符时应如何引用。
枚举成员
应使用字符转义。例如,这在 bash 上使用 \,在 PowerShell 上使用 `。
应使用强字符串引用。例如,这在 Windows cmd 上使用 ",在 bash 和 PowerShell 上使用 '。强引用将参数视为文字字符串。在 PowerShell 下,echo 'The value is $(2 * 3)'
将打印 The value is $(2 * 3)
。
应使用弱字符串引用。例如,这在 Windows cmd、bash 和 PowerShell 上使用 "。弱引用仍然在引号字符串内执行某种评估。在 PowerShell 下,echo "The value is $(2 * 3)"
将打印 The value is 6
。
ShellQuotingOptions
shell 引用选项。
属性
escape?: string | {charsToEscape: string, escapeChar: string}
用于进行字符转义的字符。如果提供字符串,则仅转义空格。如果提供 { escapeChar, charsToEscape }
字面量,则使用 escapeChar
转义 charsToEscape
中的所有字符。
用于强引用的字符。字符串的长度必须为 1。
用于弱引用的字符。字符串的长度必须为 1。
SignatureHelp
签名帮助表示可调用对象的签名。可以有多个签名,但只有一个活动签名和一个活动参数。
构造函数
new SignatureHelp(): SignatureHelp
参数 | 描述 |
---|---|
返回值 | 描述 |
SignatureHelp |
属性
活动签名的活动参数。
活动签名。
signatures: SignatureInformation[]
一个或多个签名。
SignatureHelpContext
有关触发 SignatureHelpProvider 的上下文的其他信息。
属性
activeSignatureHelp: SignatureHelp
当前活动的 SignatureHelp。
activeSignatureHelp
的 activeSignature 字段根据用户在可用签名之间箭头导航进行更新。
如果签名帮助在触发时已显示,则为 true
。
当签名帮助已处于活动状态时,会发生重新触发,并且可能是由诸如键入触发字符、光标移动或文档内容更改等操作引起的。
导致触发签名帮助的字符。
当签名帮助不是由键入触发时(例如手动调用签名帮助或移动光标时),此值为 undefined
。
triggerKind: SignatureHelpTriggerKind
导致触发签名帮助的操作。
SignatureHelpProvider
签名帮助提供程序接口定义了扩展程序和 参数提示 功能之间的协定。
方法
provideSignatureHelp(document: TextDocument, position: Position, token: CancellationToken, context: SignatureHelpContext): ProviderResult<SignatureHelp>
为给定位置和文档处的签名提供帮助。
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
context: SignatureHelpContext | 有关如何触发签名帮助的信息。 |
返回值 | 描述 |
ProviderResult<SignatureHelp> | 签名帮助或解析为签名帮助的可 thenable 对象。缺少结果可以通过返回 |
SignatureHelpProviderMetadata
有关已注册 SignatureHelpProvider 的元数据。
属性
retriggerCharacters: readonly string[]
重新触发签名帮助的字符列表。
这些触发字符仅在签名帮助已显示时处于活动状态。所有触发字符也被视为重新触发字符。
triggerCharacters: readonly string[]
触发签名帮助的字符列表。
SignatureHelpTriggerKind
SignatureHelpProvider 的触发方式。
枚举成员
签名帮助由用户手动或通过命令调用。
签名帮助由触发字符触发。
签名帮助由光标移动或文档内容更改触发。
SignatureInformation
表示可调用对象的签名。签名可以具有标签(如函数名称)、文档注释和一组参数。
构造函数
new SignatureInformation(label: string, documentation?: string | MarkdownString): SignatureInformation
创建一个新的签名信息对象。
参数 | 描述 |
---|---|
label: string | 一个标签字符串。 |
documentation?: string | MarkdownString | 文档字符串。 |
返回值 | 描述 |
SignatureInformation |
属性
活动参数的索引。
如果提供,则此项将代替 SignatureHelp.activeParameter 使用。
documentation?: string | MarkdownString
此签名的人类可读文档注释。将在 UI 中显示,但可以省略。
此签名的标签。将显示在 UI 中。
parameters: ParameterInformation[]
此签名的参数。
SnippetString
代码片段字符串是一个模板,允许插入文本并在插入发生时控制编辑器光标。
代码片段可以定义制表位和占位符,例如 $1
、$2
和 ${3:foo}
。$0
定义最终制表位,默认为代码片段的末尾。变量使用 $name
和 ${name:default value}
定义。另请参阅 完整的代码片段语法。
构造函数
new SnippetString(value?: string): SnippetString
创建一个新的代码片段字符串。
参数 | 描述 |
---|---|
value?: string | 一个代码片段字符串。 |
返回值 | 描述 |
SnippetString |
属性
代码片段字符串。
方法
appendChoice(values: readonly string[], number?: number): SnippetString
构建器函数,用于将选择 (${1|a,b,c|}
) 附加到此代码片段字符串的 value。
参数 | 描述 |
---|---|
values: readonly string[] | 选择的值 - 字符串数组 |
number?: number | 此制表位的编号,默认为从 1 开始的自动递增值。 |
返回值 | 描述 |
SnippetString | 此代码片段字符串。 |
appendPlaceholder(value: string | (snippet: SnippetString) => any, number?: number): SnippetString
构建器函数,用于将占位符 (${1:value}
) 附加到此代码片段字符串的 value。
参数 | 描述 |
---|---|
value: string | (snippet: SnippetString) => any | 此占位符的值 - 可以是字符串或函数,使用该函数可以创建嵌套的代码片段。 |
number?: number | 此制表位的编号,默认为从 1 开始的自动递增值。 |
返回值 | 描述 |
SnippetString | 此代码片段字符串。 |
appendTabstop(number?: number): SnippetString
构建器函数,用于将制表位 ($1
、$2
等) 附加到此代码片段字符串的 value。
参数 | 描述 |
---|---|
number?: number | 此制表位的编号,默认为从 1 开始的自动递增值。 |
返回值 | 描述 |
SnippetString | 此代码片段字符串。 |
appendText(string: string): SnippetString
构建器函数,用于将给定的字符串附加到此代码片段字符串的 value。
参数 | 描述 |
---|---|
string: string | 要“按给定”附加的值。字符串将被转义。 |
返回值 | 描述 |
SnippetString | 此代码片段字符串。 |
appendVariable(name: string, defaultValue: string | (snippet: SnippetString) => any): SnippetString
构建器函数,用于将变量 (${VAR}
) 附加到此代码片段字符串的 value。
参数 | 描述 |
---|---|
name: string | 变量的名称 - 不包括 |
defaultValue: string | (snippet: SnippetString) => any | 当变量名称无法解析时使用的默认值 - 可以是字符串或函数,使用该函数可以创建嵌套的代码片段。 |
返回值 | 描述 |
SnippetString | 此代码片段字符串。 |
SnippetTextEdit
代码片段编辑表示由编辑器执行的交互式编辑。
注意,代码片段编辑始终可以作为普通的 文本编辑 执行。当没有匹配的编辑器打开时,或者当 工作区编辑 包含多个文件的代码片段编辑时,就会发生这种情况。在这种情况下,只有那些与活动编辑器匹配的编辑才将作为代码片段编辑执行,而其他的则作为普通的文本编辑执行。
静态
insert(position: Position, snippet: SnippetString): SnippetTextEdit
用于创建插入代码片段编辑的实用程序。
参数 | 描述 |
---|---|
position: Position | 一个位置,将变成一个空范围。 |
snippet: SnippetString | 一个代码片段字符串。 |
返回值 | 描述 |
SnippetTextEdit | 一个新的代码片段编辑对象。 |
replace(range: Range, snippet: SnippetString): SnippetTextEdit
用于创建替换代码片段编辑的实用程序。
参数 | 描述 |
---|---|
range: Range | 一个范围。 |
snippet: SnippetString | 一个代码片段字符串。 |
返回值 | 描述 |
SnippetTextEdit | 一个新的代码片段编辑对象。 |
构造函数
new SnippetTextEdit(range: Range, snippet: SnippetString): SnippetTextEdit
创建一个新的代码片段编辑。
参数 | 描述 |
---|---|
range: Range | 一个范围。 |
snippet: SnippetString | 一个代码片段字符串。 |
返回值 | 描述 |
SnippetTextEdit |
属性
是否应在保留现有空格的情况下应用代码片段编辑。
range: Range
此编辑应用到的范围。
snippet: SnippetString
此编辑将执行的 代码片段。
SourceBreakpoint
由源位置指定的断点。
构造函数
new SourceBreakpoint(location: Location, enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): SourceBreakpoint
为源位置创建一个新的断点。
参数 | 描述 |
---|---|
location: Location | |
enabled?: boolean | |
condition?: string | |
hitCondition?: string | |
logMessage?: string | |
返回值 | 描述 |
SourceBreakpoint |
属性
条件断点的可选表达式。
是否启用断点。
一个可选表达式,用于控制忽略断点的命中次数。
断点的唯一 ID。
location: Location
此断点的源和行位置。
命中此断点时要记录的可选消息。{} 中的嵌入式表达式由调试适配器内插。
SourceControl
源控件能够向编辑器提供 资源状态,并以多种与源控件相关的方式与编辑器交互。
属性
acceptInputCommand?: Command
可选的接受输入命令。
当用户接受源控件输入中的值时,将调用此命令。
可选的提交模板字符串。
源控件视图将在适当的时候使用此值填充源控件输入。
此源控件的 ID。
inputBox: SourceControlInputBox
此源控件的 输入框。
此源控件的人类可读标签。
quickDiffProvider?: QuickDiffProvider
可选的 快速差异提供程序。
rootUri: Uri
此源控件根目录的(可选)Uri。
statusBarCommands?: Command[]
可选的状态栏命令。
这些命令将显示在编辑器的状态栏中。
方法
createResourceGroup(id: string, label: string): SourceControlResourceGroup
创建一个新的资源组。
参数 | 描述 |
---|---|
id: string | |
label: string | |
返回值 | 描述 |
SourceControlResourceGroup |
释放此源代码控制。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
SourceControlInputBox
表示源代码控制视图中的输入框。
属性
控制是否启用输入框(默认为 true
)。
一个字符串,在输入框中显示为占位符以引导用户。
输入框内容的设置器和获取器。
控制输入框是否可见(默认为 true
)。
SourceControlResourceDecorations
源代码控制资源状态的装饰。可以为浅色和深色主题分别指定。
属性
dark?: SourceControlResourceThemableDecorations
深色主题装饰。
源代码控制资源状态是否应在 UI 中淡化显示。
iconPath?: string | Uri | ThemeIcon
特定源代码控制资源状态的图标路径。
light?: SourceControlResourceThemableDecorations
浅色主题装饰。
源代码控制资源状态是否应在 UI 中显示删除线。
特定源代码控制资源状态的工具提示。
SourceControlResourceGroup
源代码控制资源组是源代码控制资源状态的集合。
属性
资源组的上下文值。这可以用于贡献资源组特定的操作。 例如,如果资源组的上下文值为 exportable
,当使用 menus
扩展点向 scm/resourceGroup/context
贡献操作时,您可以在 when
表达式中为键 scmResourceGroupState
指定上下文值,例如 scmResourceGroupState == exportable
。
"contributes": {
"menus": {
"scm/resourceGroup/context": [
{
"command": "extension.export",
"when": "scmResourceGroupState == exportable"
}
]
}
}
这将仅为 contextValue
等于 exportable
的资源组显示操作 extension.export
。
当此源代码控制资源组不包含任何源代码控制资源状态时是否隐藏。
此源代码控制资源组的 ID。
此源代码控制资源组的标签。
resourceStates: SourceControlResourceState[]
此组的源代码控制资源状态集合。
方法
释放此源代码控制资源组。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
SourceControlResourceState
源代码控制资源状态表示特定源代码控制组中底层工作区资源的状态。
属性
command?: Command
当资源状态在源代码控制视图中打开时应运行的 Command。
资源状态的上下文值。 这可以用于贡献资源特定的操作。 例如,如果资源被赋予上下文值 diffable
。 当使用 menus
扩展点向 scm/resourceState/context
贡献操作时,您可以在 when
表达式中为键 scmResourceState
指定上下文值,例如 scmResourceState == diffable
。
"contributes": {
"menus": {
"scm/resourceState/context": [
{
"command": "extension.diff",
"when": "scmResourceState == diffable"
}
]
}
}
这将仅为 contextValue
为 diffable
的资源显示操作 extension.diff
。
decorations?: SourceControlResourceDecorations
此源代码控制资源状态的装饰。
resourceUri: Uri
工作区内底层资源的 Uri。
SourceControlResourceThemableDecorations
源代码控制资源状态的主题感知装饰。
属性
iconPath?: string | Uri | ThemeIcon
特定源代码控制资源状态的图标路径。
StatementCoverage
包含单个语句或行的覆盖率信息。
构造函数
new StatementCoverage(executed: number | boolean, location: Range | Position, branches?: BranchCoverage[]): StatementCoverage
参数 | 描述 |
---|---|
executed: number | boolean | 此语句执行的次数,或者一个布尔值,指示在确切计数未知的情况下是否执行了该语句。 如果为零或 false,则该语句将被标记为未覆盖。 |
location: Range | Position | 语句位置。 |
branches?: BranchCoverage[] | 此行分支的覆盖率。如果不是条件语句,则应省略。 |
返回值 | 描述 |
StatementCoverage |
属性
branches: BranchCoverage[]
此行或语句的分支覆盖率。如果不是条件语句,则为空。
此语句执行的次数,或者一个布尔值,指示在确切计数未知的情况下是否执行了该语句。 如果为零或 false,则该语句将被标记为未覆盖。
语句位置。
StatusBarAlignment
表示状态栏项的对齐方式。
枚举成员
与左侧对齐。
与右侧对齐。
StatusBarItem
状态栏项是一种状态栏贡献,可以显示文本和图标,并在单击时运行命令。
属性
accessibilityInformation: AccessibilityInformation
屏幕阅读器与此状态栏项目交互时使用的辅助功能信息
alignment: StatusBarAlignment
此项的对齐方式。
backgroundColor: ThemeColor
此条目的背景颜色。
注意:仅支持以下颜色
new ThemeColor('statusBarItem.errorBackground')
new ThemeColor('statusBarItem.warningBackground')
将来可能会支持更多背景颜色。
注意:当设置背景颜色时,状态栏可能会覆盖 color
选择,以确保条目在所有主题中都可读。
color: string | ThemeColor
此条目的前景色。
command: string | Command
此项目的标识符。
注意:如果 window.createStatusBarItem 方法未提供标识符,则该标识符将与 扩展标识符 匹配。
条目的名称,例如“Python 语言指示器”、“Git 状态”等。 尽量保持名称简短,但又具有足够的描述性,以便用户可以理解状态栏项的含义。
此项的优先级。 值越高表示该项应更靠左显示。
要为条目显示的文本。您可以通过利用以下语法在文本中嵌入图标
我的文本 $(icon-name) 包含图标,例如 $(icon-name) 这个。
其中 icon-name 取自 ThemeIcon 图标集,例如 light-bulb
、thumbsup
、zap
等。
tooltip: string | MarkdownString
当您将鼠标悬停在此条目上时显示的工具提示文本。
方法
释放并释放相关资源。 调用 hide。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
隐藏状态栏中的条目。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
在状态栏中显示条目。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
SymbolInformation
表示有关编程构造(如变量、类、接口等)的信息。
构造函数
new SymbolInformation(name: string, kind: SymbolKind, containerName: string, location: Location): SymbolInformation
创建新的符号信息对象。
参数 | 描述 |
---|---|
name: string | 符号的名称。 |
kind: SymbolKind | 符号的类型。 |
containerName: string | 包含符号的符号的名称。 |
location: Location | 符号的位置。 |
返回值 | 描述 |
SymbolInformation |
new SymbolInformation(name: string, kind: SymbolKind, range: Range, uri?: Uri, containerName?: string): SymbolInformation
创建新的符号信息对象。
- 已弃用 - 请使用接受 Location 对象的构造函数。
参数 | 描述 |
---|---|
name: string | 符号的名称。 |
kind: SymbolKind | 符号的类型。 |
range: Range | 符号位置的范围。 |
uri?: Uri | 符号位置的资源,默认为当前文档。 |
containerName?: string | 包含符号的符号的名称。 |
返回值 | 描述 |
SymbolInformation |
属性
包含此符号的符号的名称。
kind: SymbolKind
此符号的类型。
location: Location
此符号的位置。
此符号的名称。
tags?: readonly SymbolTag[]
此符号的标签。
SymbolKind
符号种类。
枚举成员
File
符号种类。
Module
符号种类。
Namespace
符号种类。
Package
符号种类。
Class
符号种类。
Method
符号种类。
Property
符号种类。
Field
符号种类。
Constructor
符号种类。
Enum
符号种类。
Interface
符号种类。
Function
符号种类。
Variable
符号种类。
Constant
符号种类。
String
符号种类。
Number
符号种类。
Boolean
符号种类。
Array
符号种类。
Object
符号种类。
Key
符号种类。
Null
符号种类。
EnumMember
符号种类。
Struct
符号种类。
Event
符号种类。
Operator
符号种类。
TypeParameter
符号种类。
SymbolTag
符号标记是调整符号呈现效果的额外注释。
枚举成员
将符号呈现为已过时,通常使用删除线。
SyntaxTokenType
常用语法标记类型枚举。
枚举成员
除了注释、字符串文字和正则表达式之外的所有内容。
注释。
字符串文字。
正则表达式。
Tab
表示 选项卡组 中的选项卡。 选项卡只是编辑器区域中的图形表示。 不保证有后备编辑器。
属性
group: TabGroup
选项卡所属的组。
定义选项卡的结构,即文本、笔记本、自定义等。 资源和其他有用的属性在选项卡种类上定义。
选项卡当前是否处于活动状态。 这由成为组中选定的选项卡决定。
选项卡上是否存在脏指示器。
选项卡是否已固定(存在固定图标)。
选项卡是否处于预览模式。
选项卡上显示的文本。
TabChangeEvent
描述选项卡更改的事件。
属性
changed: readonly Tab[]
已更改的选项卡,例如已更改其 active 状态的选项卡。
closed: readonly Tab[]
已关闭的选项卡。
opened: readonly Tab[]
已打开的选项卡。
TabGroup
表示一组选项卡。 选项卡组本身由多个选项卡组成。
属性
activeTab: Tab
tabs: readonly Tab[]
组内包含的标签列表。如果组没有打开的标签,则可以为空。
viewColumn: ViewColumn
组的视图列。
TabGroupChangeEvent
描述标签组更改的事件。
属性
changed: readonly TabGroup[]
已更改的标签组,例如已更改其活动状态。
closed: readonly TabGroup[]
已关闭的标签组。
opened: readonly TabGroup[]
已打开的标签组。
TabGroups
表示主编辑器区域,该区域由包含标签的多个组组成。
事件
onDidChangeTabGroups: Event<TabGroupChangeEvent>
onDidChangeTabs: Event<TabChangeEvent>
属性
activeTabGroup: TabGroup
当前活动组。
all: readonly TabGroup[]
组容器内的所有组。
方法
close(tab: Tab | readonly Tab[], preserveFocus?: boolean): Thenable<boolean>
关闭标签。这会使标签对象无效,并且该标签不应再用于进一步的操作。注意:如果标签是脏的,将显示一个确认对话框,可能会被取消。如果取消,标签仍然有效
close(tabGroup: TabGroup | readonly TabGroup[], preserveFocus?: boolean): Thenable<boolean>
关闭标签组。这会使标签组对象无效,并且该标签组不应再用于进一步的操作。
TabInputCustom
该标签表示一个自定义编辑器。
构造函数
new TabInputCustom(uri: Uri, viewType: string): TabInputCustom
构造一个自定义编辑器标签输入。
参数 | 描述 |
---|---|
uri: Uri | 标签的 URI。 |
viewType: string | 自定义编辑器的视图类型。 |
返回值 | 描述 |
TabInputCustom |
属性
uri: Uri
标签所代表的 URI。
自定义编辑器的类型。
TabInputNotebook
该标签表示一个笔记本。
构造函数
new TabInputNotebook(uri: Uri, notebookType: string): TabInputNotebook
构造一个新的笔记本标签输入。
参数 | 描述 |
---|---|
uri: Uri | 笔记本的 URI。 |
notebookType: string | 笔记本的类型。映射到 NotebookDocuments 的 notebookType |
返回值 | 描述 |
TabInputNotebook |
属性
笔记本的类型。映射到 NotebookDocuments 的 notebookType
uri: Uri
标签所代表的 URI。
TabInputNotebookDiff
该标签表示在差异配置中的两个笔记本。
构造函数
new TabInputNotebookDiff(original: Uri, modified: Uri, notebookType: string): TabInputNotebookDiff
构造一个笔记本差异标签输入。
参数 | 描述 |
---|---|
original: Uri | 原始未修改笔记本的 URI。 |
modified: Uri | 已修改笔记本的 URI。 |
notebookType: string | 笔记本的类型。映射到 NotebookDocuments 的 notebookType |
返回值 | 描述 |
TabInputNotebookDiff |
属性
modified: Uri
已修改笔记本的 URI。
笔记本的类型。映射到 NotebookDocuments 的 notebookType
original: Uri
原始笔记本的 URI。
TabInputTerminal
该标签表示编辑器区域中的终端。
构造函数
new TabInputTerminal(): TabInputTerminal
构造一个终端标签输入。
参数 | 描述 |
---|---|
返回值 | 描述 |
TabInputTerminal |
TabInputText
该标签表示单个基于文本的资源。
构造函数
new TabInputText(uri: Uri): TabInputText
使用给定的 URI 构造一个文本标签输入。
参数 | 描述 |
---|---|
uri: Uri | 标签的 URI。 |
返回值 | 描述 |
TabInputText |
属性
uri: Uri
标签表示的 URI。
TabInputTextDiff
该标签表示渲染为差异的两个基于文本的资源。
构造函数
new TabInputTextDiff(original: Uri, modified: Uri): TabInputTextDiff
使用给定的 URI 构造一个新的文本差异标签输入。
参数 | 描述 |
---|---|
original: Uri | 原始文本资源的 URI。 |
modified: Uri | 修改后的文本资源的 URI。 |
返回值 | 描述 |
TabInputTextDiff |
属性
modified: Uri
修改后的文本资源的 URI。
original: Uri
原始文本资源的 URI。
TabInputWebview
该标签表示一个 Webview。
构造函数
new TabInputWebview(viewType: string): TabInputWebview
使用给定的视图类型构造一个 Webview 标签输入。
参数 | 描述 |
---|---|
viewType: string | Webview 的类型。映射到 WebviewPanel 的 viewType |
返回值 | 描述 |
TabInputWebview |
属性
Webview 的类型。映射到 WebviewPanel 的 viewType
Task
要执行的任务
构造函数
new Task(taskDefinition: TaskDefinition, scope: WorkspaceFolder | Global | Workspace, name: string, source: string, execution?: ProcessExecution | ShellExecution | CustomExecution, problemMatchers?: string | string[]): Task
创建一个新任务。
参数 | 描述 |
---|---|
taskDefinition: TaskDefinition | 任务定义,如 taskDefinitions 扩展点中所定义。 |
scope: WorkspaceFolder | Global | Workspace | 指定任务的作用域。它可以是全局任务、工作区任务或特定工作区文件夹的任务。目前不支持全局任务。 |
name: string | 任务的名称。在用户界面中显示。 |
source: string | 任务的来源(例如“gulp”、“npm”等)。在用户界面中显示。 |
execution?: ProcessExecution | ShellExecution | CustomExecution | 进程或 shell 执行。 |
problemMatchers?: string | string[] | 要使用的问题匹配器名称,例如“$tsc”或“$eslint”。问题匹配器可以由扩展使用 |
返回值 | 描述 |
Task |
new Task(taskDefinition: TaskDefinition, name: string, source: string, execution?: ProcessExecution | ShellExecution, problemMatchers?: string | string[]): Task
创建一个新任务。
- 已弃用 - 使用允许为任务指定作用域的新构造函数。
参数 | 描述 |
---|---|
taskDefinition: TaskDefinition | 任务定义,如 taskDefinitions 扩展点中所定义。 |
name: string | 任务的名称。在用户界面中显示。 |
source: string | 任务的来源(例如“gulp”、“npm”等)。在用户界面中显示。 |
execution?: ProcessExecution | ShellExecution | 进程或 shell 执行。 |
problemMatchers?: string | string[] | 要使用的问题匹配器名称,例如“$tsc”或“$eslint”。问题匹配器可以由扩展使用 |
返回值 | 描述 |
Task |
属性
definition: TaskDefinition
任务的定义。
一个人类可读的字符串,在显示任务名称的地方,以不太突出的方式在单独的行中呈现。支持通过 $(<name>)
语法渲染主题图标。
execution?: ProcessExecution | ShellExecution | CustomExecution
任务的执行引擎
group?: TaskGroup
此任务所属的任务组。有关预定义的可用组集,请参阅 TaskGroup。默认为 undefined,表示任务不属于任何特殊组。
任务是否为后台任务。
任务的名称
presentationOptions: TaskPresentationOptions
演示选项。默认为空字面量。
附加到任务的问题匹配器。默认为空数组。
runOptions: RunOptions
任务的运行选项
scope: WorkspaceFolder | Global | Workspace
任务的作用域。
描述此 shell 任务来源的人类可读字符串,例如“gulp”或“npm”。支持通过 $(<name>)
语法渲染主题图标。
TaskDefinition
一个结构,用于定义系统中任务的种类。该值必须是可 JSON 字符串化的。
属性
任务定义,描述由扩展提供的任务。通常,任务提供程序定义更多属性来标识任务。它们需要在扩展的 package.json 中的 'taskDefinitions' 扩展点下定义。例如,npm 任务定义如下所示
interface NpmTaskDefinition extends TaskDefinition {
script: string;
}
请注意,以 '$' 开头的类型标识符是为内部使用保留的,不应由扩展使用。
TaskEndEvent
表示已执行任务结束的事件。
此接口不打算被实现。
属性
execution: TaskExecution
表示已完成任务的任务项。
TaskExecution
一个对象,表示已执行的任务。它可以用于终止任务。
此接口不打算被实现。
属性
task: Task
已启动的任务。
方法
终止任务执行。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
TaskFilter
任务过滤器按其版本和类型表示任务
属性
要返回的任务类型;
tasks.json 文件中使用的任务版本。该字符串支持 package.json semver 表示法。
TaskGroup
任务的分组。编辑器默认支持“清理”、“构建”、“全部重新构建”和“测试”组。
静态
Build: TaskGroup
构建任务组;
Clean: TaskGroup
清理任务组;
Rebuild: TaskGroup
全部重新构建任务组;
Test: TaskGroup
全部测试任务组;
构造函数
new TaskGroup(id: string, label: string): TaskGroup
私有构造函数
参数 | 描述 |
---|---|
id: string | 任务组的标识符。 |
label: string | 任务组的人类可读名称。 |
返回值 | 描述 |
TaskGroup |
属性
任务组的 ID。是 TaskGroup.Clean.id、TaskGroup.Build.id、TaskGroup.Rebuild.id 或 TaskGroup.Test.id 之一。
属于此组的任务是否为该组的默认任务。此属性无法通过 API 设置,而是由用户的任务配置控制。
TaskPanelKind
控制任务通道在任务之间的使用方式
枚举成员
与其他任务共享面板。这是默认设置。
为此任务使用专用面板。该面板不与其他任务共享。
每当执行此任务时创建一个新面板。
TaskPresentationOptions
控制任务在 UI 中的呈现方式。
属性
控制在执行任务之前是否清除终端。
控制在执行任务后是否关闭终端。
控制是否在用户界面中回显与任务关联的命令。
控制显示任务输出的面板是否获取焦点。
panel?: TaskPanelKind
控制任务面板是否仅用于此任务(专用)、在任务之间共享(共享)或是否在每次任务执行时创建一个新面板(新建)。默认为 TaskInstanceKind.Shared
reveal?: TaskRevealKind
控制是否在用户界面中显示任务输出。默认为 RevealKind.Always
。
控制是否显示“终端将被任务重用,按任意键关闭它”消息。
TaskProcessEndEvent
表示通过任务触发的进程执行结束的事件
属性
execution: TaskExecution
进程已启动的任务执行。
进程的退出代码。当任务终止时,将为 undefined
。
TaskProcessStartEvent
表示通过任务触发的进程执行开始的事件
属性
execution: TaskExecution
进程已启动的任务执行。
底层进程 ID。
TaskProvider<T>
任务提供程序允许向任务服务添加任务。任务提供程序通过 tasks.registerTaskProvider 注册。
方法
provideTasks(token: CancellationToken): ProviderResult<T[]>
提供任务。
参数 | 描述 |
---|---|
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T[]> | 任务数组 |
resolveTask(task: T, token: CancellationToken): ProviderResult<T>
解析没有设置执行的任务。任务通常从 tasks.json
文件中找到的信息创建。此类任务缺少关于如何执行它们的信息,任务提供程序必须在 resolveTask
方法中填写缺失的信息。此方法不会为从上述 provideTasks
方法返回的任务调用,因为这些任务始终是完全解析的。resolveTask
方法的有效默认实现是返回 undefined
。
请注意,在填写 task
的属性时,您必须确保使用完全相同的 TaskDefinition
,而不是创建一个新的。其他属性可能会更改。
参数 | 描述 |
---|---|
task: T | 要解析的任务。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T> | 已解析的任务 |
TaskRevealKind
控制终端可见性的行为。
枚举成员
如果执行任务,始终将终端置于前台。
仅当在执行任务时检测到问题(例如,由于某种原因任务无法启动)时,才将终端置于前台。
当执行任务时,终端永远不会显示在前台。
TaskScope
任务的作用域。
枚举成员
该任务是一个全局任务。目前不支持全局任务。
任务是一个工作区任务
TaskStartEvent
一个事件,表示任务执行的开始。
此接口不打算被实现。
属性
execution: TaskExecution
表示已启动任务的任务项。
TelemetryLogger
一个遥测记录器,扩展可以使用它来记录使用情况和错误遥测数据。
记录器包装了一个 sender,但它保证
- 用户禁用或调整遥测的设置得到遵守,并且
- 潜在的敏感数据被移除
它还启用了一个“回显 UI”,用于打印发送的任何数据,并允许编辑器将未处理的错误转发到相应的扩展。
要获取 TelemetryLogger
的实例,请使用 createTelemetryLogger
。
事件
onDidChangeEnableStates: Event<TelemetryLogger>
当使用情况或错误遥测的启用状态更改时触发的 Event。
属性
是否为此记录器启用了错误遥测。
是否为此记录器启用了使用情况遥测。
方法
释放此对象并释放资源。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
logError(eventName: string, data?: Record<string, any>): void
记录一个错误事件。
完成清理、遥测设置检查和数据混合调用后,TelemetrySender.sendEventData
用于记录事件。与 logUsage
的不同之处在于,如果遥测设置是 Error+,它将记录事件。自动支持回显到扩展遥测输出通道。
参数 | 描述 |
---|---|
eventName: string | 要记录的事件名称 |
data?: Record<string, any> | 要记录的数据 |
返回值 | 描述 |
void |
logError(error: Error, data?: Record<string, any>): void
记录一个错误事件。
调用 TelemetrySender.sendErrorData
。执行清理、遥测检查和数据混合。自动支持回显到扩展遥测输出通道。还将自动记录扩展主机进程中抛出的任何异常。
参数 | 描述 |
---|---|
error: Error | 包含已清理 PII 的堆栈跟踪的错误对象 |
data?: Record<string, any> | 与堆栈跟踪一起记录的其他数据 |
返回值 | 描述 |
void |
logUsage(eventName: string, data?: Record<string, any>): void
记录一个使用情况事件。
完成清理、遥测设置检查和数据混合调用后,TelemetrySender.sendEventData
用于记录事件。自动支持回显到扩展遥测输出通道。
参数 | 描述 |
---|---|
eventName: string | 要记录的事件名称 |
data?: Record<string, any> | 要记录的数据 |
返回值 | 描述 |
void |
TelemetryLoggerOptions
用于创建 TelemetryLogger 的选项
属性
additionalCommonProperties?: Record<string, any>
应注入到数据对象中的任何其他通用属性。
ignoreBuiltInCommonProperties?: boolean
是否要避免将内置的通用属性(如操作系统、扩展名称等)注入到数据对象中。如果未定义,则默认为 false
。
ignoreUnhandledErrors?: boolean
是否应将扩展主机上由您的扩展引起的未处理错误记录到您的发送器。如果未定义,则默认为 false
。
TelemetrySender
遥测发送器是遥测记录器和某些遥测服务之间的契约。注意 扩展绝不能直接调用其发送器的方法,因为记录器提供了额外的保护和清理。
const sender: vscode.TelemetrySender = {...};
const logger = vscode.env.createTelemetryLogger(sender);
// GOOD - uses the logger
logger.logUsage('myEvent', { myData: 'myValue' });
// BAD - uses the sender directly: no data cleansing, ignores user settings, no echoing to the telemetry output channel etc
sender.logEvent('myEvent', { myData: 'myValue' });
方法
flush(): void | Thenable<void>
可选的刷新功能,它将使此发送器有机会在 TelemetryLogger 被释放时发送任何剩余事件
参数 | 描述 |
---|---|
返回值 | 描述 |
void | Thenable<void> |
sendErrorData(error: Error, data?: Record<string, any>): void
用于发送错误的功能。在 TelemetryLogger 中使用
参数 | 描述 |
---|---|
error: Error | 要记录的错误 |
data?: Record<string, any> | 要与异常一起收集的任何其他数据 |
返回值 | 描述 |
void |
sendEventData(eventName: string, data?: Record<string, any>): void
用于发送不带堆栈跟踪的事件数据的功能。在 TelemetryLogger 中使用
参数 | 描述 |
---|---|
eventName: string | 您要记录的事件的名称 |
data?: Record<string, any> | 正在记录的可序列化键值对 |
返回值 | 描述 |
void |
TelemetryTrustedValue<T>
一个特殊的value包装器,表示一个值可以安全地不进行清理。当您可以保证值中不包含可识别信息,并且清理不正确地编辑它时,可以使用它。
构造函数
new TelemetryTrustedValue<T>(value: T): TelemetryTrustedValue<T>
创建一个新的遥测信任值。
参数 | 描述 |
---|---|
value: T | 要信任的值 |
返回值 | 描述 |
TelemetryTrustedValue<T> |
属性
被信任不包含 PII 的值。
Terminal
集成终端中的单个终端实例。
属性
creationOptions: Readonly<TerminalOptions | ExtensionTerminalOptions>
用于初始化终端的对象,例如,当终端不是由此扩展启动时,或者用于检测 shell 启动的文件夹时,这很有用。
exitStatus: TerminalExitStatus
终端的退出状态,在终端处于活动状态时,这将是未定义的。
示例: 当终端以非零退出代码退出时,显示带有退出代码的通知。
window.onDidCloseTerminal(t => {
if (t.exitStatus && t.exitStatus.code) {
vscode.window.showInformationMessage(`Exit code: ${t.exitStatus.code}`);
}
});
终端的名称。
shell 进程的进程 ID。
shellIntegration: TerminalShellIntegration
一个包含终端 shell 集成 支持的功能的对象。在终端创建后,这将始终为 undefined
。监听 window.onDidChangeTerminalShellIntegration 以在终端的 shell 集成激活时收到通知。
请注意,如果 shell 集成永远不激活,则此对象可能仍然是未定义的。例如,命令提示符不支持 shell 集成,并且用户的 shell 设置可能与自动 shell 集成激活冲突。
state: TerminalState
Terminal 的当前状态。
方法
释放和释放关联的资源。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
如果此终端当前正在显示,则隐藏终端面板。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
sendText(text: string, shouldExecute?: boolean): void
将文本发送到终端。文本被写入终端底层 pty 进程(shell)的标准输入。
参数 | 描述 |
---|---|
text: string | 要发送的文本。 |
shouldExecute?: boolean | 指示发送的文本应被执行,而不仅仅是插入到终端中。添加的字符是 |
返回值 | 描述 |
void |
show(preserveFocus?: boolean): void
显示终端面板并在 UI 中显示此终端。
参数 | 描述 |
---|---|
preserveFocus?: boolean | 当 |
返回值 | 描述 |
void |
TerminalDimensions
表示终端的尺寸。
属性
终端中的列数。
终端中的行数。
TerminalEditorLocationOptions
假定 TerminalLocation 为 editor,并允许指定 ViewColumn 和 preserveFocus 属性
属性
一个可选标志,当为 true
时,将阻止 Terminal 获取焦点。
viewColumn: ViewColumn
应在编辑器区域中显示 terminal 的视图列。默认值为 active。不存在的列将根据需要创建,最多为 ViewColumn.Nine。使用 ViewColumn.Beside 将编辑器在当前活动的编辑器旁边打开。
TerminalExitReason
终端退出原因类型。
枚举成员
未知原因。
窗口已关闭/重新加载。
shell 进程已退出。
用户关闭了终端。
扩展释放了终端。
TerminalExitStatus
表示终端的退出方式。
属性
终端退出的退出代码,它可以具有以下值
- 零:终端进程或自定义执行成功。
- 非零:终端进程或自定义执行失败。
undefined
:用户强制关闭终端或自定义执行退出时未提供退出代码。
reason: TerminalExitReason
触发终端退出的原因。
TerminalLink
终端行上的链接。
构造函数
new TerminalLink(startIndex: number, length: number, tooltip?: string): TerminalLink
创建一个新的终端链接。
参数 | 描述 |
---|---|
startIndex: number | 链接在 TerminalLinkContext.line 上的起始索引。 |
length: number | 链接在 TerminalLinkContext.line 上的长度。 |
tooltip?: string | 当您悬停在此链接上时显示的工具提示文本。 如果提供了工具提示,它将显示在一个字符串中,该字符串包含有关如何触发链接的说明,例如 |
返回值 | 描述 |
TerminalLink |
属性
链接在 TerminalLinkContext.line 上的长度。
链接在 TerminalLinkContext.line 上的起始索引。
当您悬停在此链接上时显示的工具提示文本。
如果提供了工具提示,它将显示在一个字符串中,该字符串包含有关如何触发链接的说明,例如 {0} (ctrl + click)
。 具体说明因操作系统、用户设置和本地化而异。
TerminalLinkContext
提供终端中一行的信息,以便为其提供链接。
属性
这是来自终端中未换行行的文本。
terminal: Terminal
链接所属的终端。
TerminalLinkProvider<T>
一个提供程序,用于启用终端内链接的检测和处理。
方法
handleTerminalLink(link: T): ProviderResult<void>
处理已激活的终端链接。
参数 | 描述 |
---|---|
link: T | 要处理的链接。 |
返回值 | 描述 |
ProviderResult<void> |
provideTerminalLinks(context: TerminalLinkContext, token: CancellationToken): ProviderResult<T[]>
为给定上下文提供终端链接。请注意,即使在先前的调用解决之前,也可以多次调用此方法,请确保不共享全局对象(例如,RegExp
),这些对象在异步使用可能重叠时可能会出现问题。
参数 | 描述 |
---|---|
context: TerminalLinkContext | 有关正在为其提供链接的信息。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T[]> | 给定行的终端链接列表。 |
TerminalLocation
终端的位置。
枚举成员
在终端视图中
在编辑器区域中
TerminalOptions
描述终端应使用的选项的值对象。
属性
color?: ThemeColor
终端的图标 ThemeColor。建议使用 terminal.ansi*
主题键,以获得最佳对比度和跨主题的一致性。
cwd?: string | Uri
要用于终端的当前工作目录的路径或 Uri。
包含将添加到编辑器进程的环境变量的对象。
启用后,终端将正常运行进程,但不会向用户显示,直到调用 Terminal.show
。典型的用法是当您需要运行可能需要交互的内容,但只想在需要交互时告知用户。请注意,终端仍将像往常一样向所有扩展公开。当下次打开工作区时,隐藏的终端将不会恢复。
iconPath?: IconPath
终端的图标路径或 ThemeIcon。
选择退出在重启和重新加载时的默认终端持久化。这仅在启用 terminal.integrated.enablePersistentSessions
时生效。
location?: TerminalEditorLocationOptions | TerminalSplitLocationOptions | TerminalLocation
首次启动时要写入终端的消息,请注意,这不会发送到进程,而是直接写入终端。这支持转义序列,例如设置文本样式。
一个人类可读的字符串,将在 UI 中用于表示终端。
自定义 shell 可执行文件的参数。字符串只能在 Windows 上使用,它允许以 命令行格式 指定 shell 参数。
要在终端中使用的自定义 shell 可执行文件的路径。
终端进程环境是否应与 TerminalOptions.env
中提供的环境完全相同。当此值为 false(默认值)时,环境将基于窗口的环境,并且还会应用配置的平台设置,例如顶部的 terminal.integrated.env.windows
。当此值为 true 时,必须提供完整的环境,因为不会从进程或任何配置继承任何内容。
TerminalProfile
终端配置文件定义了终端的启动方式。
构造函数
new TerminalProfile(options: TerminalOptions | ExtensionTerminalOptions): TerminalProfile
创建一个新的终端配置文件。
参数 | 描述 |
---|---|
options: TerminalOptions | ExtensionTerminalOptions | 终端将使用的选项。 |
返回值 | 描述 |
TerminalProfile |
属性
options: TerminalOptions | ExtensionTerminalOptions
终端将使用的选项。
TerminalProfileProvider
当通过 UI 或命令启动时,为贡献的终端配置文件提供终端配置文件。
方法
provideTerminalProfile(token: CancellationToken): ProviderResult<TerminalProfile>
提供终端配置文件。
参数 | 描述 |
---|---|
token: CancellationToken | 指示不再需要结果的取消令牌。 |
返回值 | 描述 |
ProviderResult<TerminalProfile> | 终端配置文件。 |
TerminalShellExecution
在终端中执行的命令。
属性
commandLine: TerminalShellExecutionCommandLine
已执行的命令行。此值的 confidence 取决于特定 shell 的 shell 集成实现。在 window.onDidEndTerminalShellExecution 触发后,此值可能会变得更准确。
示例
// Log the details of the command line on start and end
window.onDidStartTerminalShellExecution(event => {
const commandLine = event.execution.commandLine;
console.log(`Command started\n${summarizeCommandLine(commandLine)}`);
});
window.onDidEndTerminalShellExecution(event => {
const commandLine = event.execution.commandLine;
console.log(`Command ended\n${summarizeCommandLine(commandLine)}`);
});
function summarizeCommandLine(commandLine: TerminalShellExecutionCommandLine) {
return [
` Command line: ${command.commandLine.value}`,
` Confidence: ${command.commandLine.confidence}`,
` Trusted: ${command.commandLine.isTrusted}
].join('\n');
}
cwd: Uri
当此命令执行时,shell 报告的工作目录。此 Uri 可能表示另一台计算机上的文件(例如,ssh 进入另一台计算机)。这需要 shell 集成支持工作目录报告。
方法
创建写入终端的原始数据流(包括转义序列)。 这将仅包括在首次调用 read
之后写入的数据,即,您必须在通过 TerminalShellIntegration.executeCommand 或 window.onDidStartTerminalShellExecution 执行命令后立即调用 read
,以避免错过任何数据。
示例
// Log all data written to the terminal for a command
const command = term.shellIntegration.executeCommand({ commandLine: 'echo "Hello world"' });
const stream = command.read();
for await (const data of stream) {
console.log(data);
}
参数 | 描述 |
---|---|
返回值 | 描述 |
AsyncIterable<string> |
TerminalShellExecutionCommandLine
终端中执行的命令行。
属性
confidence: TerminalShellExecutionCommandLineConfidence
命令行值的置信度,由获取该值的方式决定。 这取决于 shell 集成脚本的实现。
命令行值是否来自受信任的来源,因此可以安全执行而无需用户额外确认,例如询问“您要执行 (command) 吗?”的通知。 仅当您要再次执行命令时才可能需要此验证。
仅当命令行由 shell 集成脚本显式报告时(即 高置信度),并且它使用了 nonce 进行验证时,此值才为 true
。
已执行的完整命令行,包括命令及其参数。
TerminalShellExecutionCommandLineConfidence
枚举成员
命令行值的置信度低。 这意味着该值是从终端缓冲区中读取的,使用了 shell 集成脚本报告的标记。 此外,将满足以下条件之一
- 命令从最左侧的列开始,这很不寻常,或者
- 命令是多行的,由于行继续符和右侧提示符,因此更难以准确检测。
- shell 集成脚本未报告命令行标记。
命令行值的置信度中等。 这意味着该值是从终端缓冲区中读取的,使用了 shell 集成脚本报告的标记。 该命令是单行的,并且不是从最左侧的列开始(这很不寻常)。
命令行值的置信度高。 这意味着该值是从 shell 集成脚本显式发送的,或者该命令是通过 TerminalShellIntegration.executeCommand API 执行的。
TerminalShellExecutionEndEvent
表示终端中执行已结束的事件。
属性
execution: TerminalShellExecution
已结束的终端 shell 执行。
shell 报告的退出代码。
当此值为 undefined
时,可能意味着以下几种情况
- shell 未报告退出代码(即,shell 集成脚本行为异常)
- shell 报告命令在命令完成之前启动(例如,打开了一个子 shell)。
- 用户通过 ctrl+c 取消了命令。
- 用户在没有输入时按下了 Enter 键。
通常不应发生这种情况。 根据用例,最好将其视为失败。
示例
const execution = shellIntegration.executeCommand({
command: 'echo',
args: ['Hello world']
});
window.onDidEndTerminalShellExecution(event => {
if (event.execution === execution) {
if (event.exitCode === undefined) {
console.log('Command finished but exit code is unknown');
} else if (event.exitCode === 0) {
console.log('Command succeeded');
} else {
console.log('Command failed');
}
}
});
shellIntegration: TerminalShellIntegration
shell 集成对象。
terminal: Terminal
已激活 shell 集成的终端。
TerminalShellExecutionStartEvent
表示终端中执行已开始的事件。
属性
execution: TerminalShellExecution
已结束的终端 shell 执行。
shellIntegration: TerminalShellIntegration
shell 集成对象。
terminal: Terminal
已激活 shell 集成的终端。
TerminalShellIntegration
Shell 集成驱动的终端功能。
属性
cwd: Uri
终端的当前工作目录。 此 Uri 可能表示另一台机器上的文件(例如,ssh 进入另一台机器)。 这需要 shell 集成支持工作目录报告。
方法
executeCommand(commandLine: string): TerminalShellExecution
执行命令,必要时发送 ^C 以中断任何正在运行的命令。
示例
// Execute a command in a terminal immediately after being created
const myTerm = window.createTerminal();
window.onDidChangeTerminalShellIntegration(async ({ terminal, shellIntegration }) => {
if (terminal === myTerm) {
const execution = shellIntegration.executeCommand('echo "Hello world"');
window.onDidEndTerminalShellExecution(event => {
if (event.execution === execution) {
console.log(`Command exited with code ${event.exitCode}`);
}
});
}
}));
// Fallback to sendText if there is no shell integration within 3 seconds of launching
setTimeout(() => {
if (!myTerm.shellIntegration) {
myTerm.sendText('echo "Hello world"');
// Without shell integration, we can't know when the command has finished or what the
// exit code was.
}
}, 3000);
示例
// Send command to terminal that has been alive for a while
const commandLine = 'echo "Hello world"';
if (term.shellIntegration) {
const execution = shellIntegration.executeCommand({ commandLine });
window.onDidEndTerminalShellExecution(event => {
if (event.execution === execution) {
console.log(`Command exited with code ${event.exitCode}`);
}
});
} else {
term.sendText(commandLine);
// Without shell integration, we can't know when the command has finished or what the
// exit code was.
}
参数 | 描述 |
---|---|
commandLine: string | 要执行的命令行,这是将发送到终端的确切文本。 |
返回值 | 描述 |
TerminalShellExecution |
executeCommand(executable: string, args: string[]): TerminalShellExecution
执行命令,必要时发送 ^C 以中断任何正在运行的命令。
注意 不保证此操作有效,因为必须激活 shell 集成。 检查 TerminalShellExecution.exitCode 是否被拒绝以验证是否成功。
示例
// Execute a command in a terminal immediately after being created
const myTerm = window.createTerminal();
window.onDidChangeTerminalShellIntegration(async ({ terminal, shellIntegration }) => {
if (terminal === myTerm) {
const command = shellIntegration.executeCommand({
command: 'echo',
args: ['Hello world']
});
const code = await command.exitCode;
console.log(`Command exited with code ${code}`);
}
}));
// Fallback to sendText if there is no shell integration within 3 seconds of launching
setTimeout(() => {
if (!myTerm.shellIntegration) {
myTerm.sendText('echo "Hello world"');
// Without shell integration, we can't know when the command has finished or what the
// exit code was.
}
}, 3000);
示例
// Send command to terminal that has been alive for a while
const commandLine = 'echo "Hello world"';
if (term.shellIntegration) {
const command = term.shellIntegration.executeCommand({
command: 'echo',
args: ['Hello world']
});
const code = await command.exitCode;
console.log(`Command exited with code ${code}`);
} else {
term.sendText(commandLine);
// Without shell integration, we can't know when the command has finished or what the
// exit code was.
}
参数 | 描述 |
---|---|
executable: string | 要运行的命令。 |
args: string[] | 用于启动可执行文件的参数。 参数将被转义,以便当参数既包含空格又不包含任何单引号、双引号或反引号字符时,它们被解释为单个参数。 请注意,此转义并非旨在作为安全措施,在将不受信任的数据传递给此 API 时要小心,因为像 |
返回值 | 描述 |
TerminalShellExecution |
TerminalShellIntegrationChangeEvent
表示终端的 shell 集成已更改的事件。
属性
shellIntegration: TerminalShellIntegration
shell 集成对象。
terminal: Terminal
已激活 shell 集成的终端。
TerminalSplitLocationOptions
使用父 Terminal 的位置作为终端的位置
属性
parentTerminal: Terminal
用于拆分此终端的父终端。 无论父终端是在面板区域还是编辑器区域中,这都有效。
TerminalState
表示 Terminal 的状态。
属性
是否已与 Terminal 交互。 交互意味着终端已将数据发送到进程,这取决于终端的模式。 默认情况下,当按下键或命令或扩展发送文本时会发送输入,但根据终端的模式,它也可能发生在
- 指针单击事件
- 指针滚动事件
- 指针移动事件
- 终端焦点进入/退出
有关可以发送数据的事件的更多信息,请参阅 https://invisible-island.net/xterm/ctlseqs/ctlseqs.html 上的“DEC Private Mode Set (DECSET)”。
TestController
用于发现和执行测试的入口点。 它包含 TestController.items,用于填充编辑器 UI,并与 运行配置文件关联,以允许执行测试。
属性
在 tests.createTestController 中传递的控制器的 ID。 这必须是全局唯一的。
items: TestItemCollection
“顶级”TestItem 实例的集合,这些实例可以依次拥有自己的 children 以形成“测试树”。
扩展控制何时添加测试。 例如,扩展应在 workspace.onDidOpenTextDocument 触发时为文件添加测试,以便文件内测试的装饰可见。
但是,编辑器有时可能会使用 resolveHandler 显式请求子项。 有关更多详细信息,请参阅该方法的文档。
测试控制器的用户可读标签。
refreshHandler: (token: CancellationToken) => void | Thenable<void>
如果存在此方法,则 UI 中将显示刷新按钮,并且单击该按钮时将调用此方法。 调用时,扩展应扫描工作区以查找任何新的、已更改或已删除的测试。
建议扩展尝试实时更新测试,例如使用 FileSystemWatcher,并将此方法用作后备方案。
参数 | 描述 |
---|---|
token: CancellationToken | |
返回值 | 描述 |
void | Thenable<void> | 在测试刷新后解析的 thenable 对象。 |
resolveHandler?: (item: TestItem) => void | Thenable<void>
编辑器可以调用的扩展提供的函数,以请求测试项的子项,如果 TestItem.canResolveChildren 为 true
。 调用时,项目应发现子项,并在发现子项时调用 TestController.createTestItem。
通常,扩展管理测试项的生命周期,但在某些情况下,编辑器可能会请求加载特定项的子项。 例如,如果用户在重新加载编辑器后请求重新运行测试,则编辑器可能需要调用此方法来解析先前运行的测试。
资源管理器中的项目将自动标记为“忙碌”,直到函数返回或返回的 thenable 对象解析。
方法
createRunProfile(label: string, kind: TestRunProfileKind, runHandler: (request: TestRunRequest, token: CancellationToken) => void | Thenable<void>, isDefault?: boolean, tag?: TestTag, supportsContinuousRun?: boolean): TestRunProfile
创建用于运行测试的配置文件。 扩展必须创建至少一个配置文件才能运行测试。
参数 | 描述 |
---|---|
label: string | 此配置文件的用户可读标签。 |
kind: TestRunProfileKind | 配置此配置文件管理的执行类型。 |
runHandler: (request: TestRunRequest, token: CancellationToken) => void | Thenable<void> | 用于启动测试运行的函数。 |
isDefault?: boolean | 是否是其类型的默认操作。 |
tag?: TestTag | 配置文件测试标签。 |
supportsContinuousRun?: boolean | 配置文件是否支持持续运行。 |
返回值 | 描述 |
TestRunProfile | 一个 TestRunProfile 实例,它会自动与此控制器关联。 |
createTestItem(id: string, label: string, uri?: Uri): TestItem
创建一个新的托管 TestItem 实例。 可以将其添加到现有项目的 TestItem.children 中,或添加到 TestController.items 中。
参数 | 描述 |
---|---|
id: string | TestItem 的标识符。 测试项的 ID 在其添加到的 TestItemCollection 中必须是唯一的。 |
label: string | 测试项的用户可读标签。 |
uri?: Uri | 此 TestItem 关联的 URI。 可以是文件或目录。 |
返回值 | 描述 |
TestItem |
createTestRun(request: TestRunRequest, name?: string, persist?: boolean): TestRun
创建 TestRun。 当请求执行测试时,应由 TestRunProfile 调用此方法,如果在外部检测到测试运行,也可以调用此方法。 创建后,请求中包含的测试将移至排队状态。
使用同一 request
实例创建的所有运行将分组在一起。 例如,如果在一多个平台上运行单个测试套件,这将非常有用。
参数 | 描述 |
---|---|
request: TestRunRequest | 测试运行请求。 只能修改 |
name?: string | 运行的用户可读名称。 这可以用于消除测试运行中多组结果的歧义。 例如,如果测试跨多个平台运行,则此功能很有用。 |
persist?: boolean | 运行创建的结果是否应持久保存在编辑器中。 如果结果来自已在外部保存的文件(例如,覆盖率信息文件),则此值可能为 false。 |
返回值 | 描述 |
TestRun | 一个 TestRun 实例。 从调用此方法的那一刻起,直到调用 TestRun.end 为止,它将被视为“正在运行”。 |
取消注册测试控制器,处置其关联的测试和未持久保存的结果。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
invalidateTestResults(items?: TestItem | readonly TestItem[]): void
将项目的测试结果标记为已过时。 当代码或配置更改且以前的结果不再被认为是相关时,通常会调用此方法。 用于将结果标记为过时的相同逻辑可用于驱动 持续测试运行。
如果将项目传递给此方法,则该项目及其所有子项的测试结果将被标记为已过时。 如果未传递任何项目,则 TestController 拥有的所有测试都将被标记为已过时。
在此方法调用之前启动的任何测试运行,包括可能仍在进行的运行,都将在编辑器的 UI 中标记为已过时并降低优先级。
TestCoverageCount
一个类,其中包含有关覆盖资源的的信息。 可以给出文件中行、分支和声明的计数。
构造函数
new TestCoverageCount(covered: number, total: number): TestCoverageCount
参数 | 描述 |
---|---|
covered: number | |
total: number | |
返回值 | 描述 |
TestCoverageCount |
属性
文件中覆盖的项目数。
文件中覆盖项目的总数。
TestItem
“测试资源管理器”视图中显示的项目。
TestItem
可以表示测试套件或测试本身,因为它们都具有类似的功能。
属性
控制项目是否在测试资源管理器视图中显示为“忙碌”。 这对于在发现子项时显示状态很有用。
默认为 false
。
指示此测试项是否可能具有通过解析发现的子项。
如果为 true,则此项目在测试资源管理器视图中显示为可展开的,并且展开该项目将导致使用该项目调用 TestController.resolveHandler。
默认为 false
。
children: TestItemCollection
此测试项的子项。 对于测试套件,这可能包含各个测试用例或嵌套套件。
显示在标签旁边的可选描述。
error: string | MarkdownString
加载测试时遇到的可选错误。
请注意,这不是测试结果,仅应用于表示测试发现中的错误,例如语法错误。
TestItem
的标识符。 这用于将文档中的测试结果和测试与工作区(测试资源管理器)中的测试相关联。 对于 TestItem
的生命周期,这不能更改,并且在其父项的直接子项中必须是唯一的。
描述测试用例的显示名称。
parent: TestItem
此项目的父项。 它是自动设置的,对于 TestController.items 中的顶级项目以及尚未包含在另一个项目的 children 中的项目,它是未定义的。
range: Range
测试项目在其 uri 中的位置。
仅当 uri
指向文件时,这才有意义。
将此项目与其他项目进行比较时应使用的字符串。 当 falsy
时,将使用 label。
tags: readonly TestTag[]
与此测试项目关联的标签。 可以与 tags 结合使用,或者仅用作组织功能。
uri: Uri
此 TestItem
关联的 URI。 可以是文件或目录。
TestItemCollection
测试项的集合,位于 TestItem.children 和 TestController.items 中。
属性
获取集合中项目的数量。
方法
add(item: TestItem): void
将测试项添加到子项。 如果已存在具有相同 ID 的项目,则会将其替换。
参数 | 描述 |
---|---|
item: TestItem | 要添加的项目。 |
返回值 | 描述 |
void |
从集合中删除单个测试项。
参数 | 描述 |
---|---|
itemId: string | 要删除的项目 ID。 |
返回值 | 描述 |
void |
forEach(callback: (item: TestItem, collection: TestItemCollection) => unknown, thisArg?: any): void
迭代此集合中的每个条目。
参数 | 描述 |
---|---|
callback: (item: TestItem, collection: TestItemCollection) => unknown | 为每个条目执行的函数。 |
thisArg?: any | 调用处理程序函数时使用的 |
返回值 | 描述 |
void |
get(itemId: string): TestItem
如果子项中存在具有此 ID 的测试项,则高效地获取该测试项。
参数 | 描述 |
---|---|
itemId: string | 要获取的项目 ID。 |
返回值 | 描述 |
TestItem | 找到的项目;如果不存在,则为 undefined。 |
replace(items: readonly TestItem[]): void
替换集合存储的项目。
参数 | 描述 |
---|---|
items: readonly TestItem[] | 要存储的项目。 |
返回值 | 描述 |
void |
TestMessage
与测试状态关联的消息。 可以链接到特定的源范围 - 例如,对于断言失败非常有用。
静态
diff(message: string | MarkdownString, expected: string, actual: string): TestMessage
创建一个新的 TestMessage,它将在编辑器中以差异形式呈现。
参数 | 描述 |
---|---|
message: string | MarkdownString | 要向用户显示的消息。 |
expected: string | 期望的输出。 |
actual: string | 实际的输出。 |
返回值 | 描述 |
TestMessage |
构造函数
new TestMessage(message: string | MarkdownString): TestMessage
创建一个新的 TestMessage 实例。
参数 | 描述 |
---|---|
message: string | MarkdownString | 要向用户显示的消息。 |
返回值 | 描述 |
TestMessage |
属性
实际的测试输出。如果与 expectedOutput 一起给出,将显示差异视图。
测试项的上下文值。这可以用于为测试速览视图贡献特定于消息的操作。此处设置的值可以在以下 menus
贡献点中的 testMessage
属性中找到
testing/message/context
- 结果树中消息的上下文菜单testing/message/content
- 覆盖编辑器内容的突出按钮,其中显示消息。
例如
"contributes": {
"menus": {
"testing/message/content": [
{
"command": "extension.deleteCommentThread",
"when": "testMessage == canApplyRichDiff"
}
]
}
}
命令将被调用,并带有一个包含以下内容的对象
test
: 与消息关联的 TestItem,如果它仍然存在于 TestController.items 集合中。message
: TestMessage 实例。
期望的测试输出。如果与 actualOutput 一起给出,将显示差异视图。
location?: Location
关联的文件位置。
message: string | MarkdownString
要显示的人类可读的消息文本。
stackTrace?: TestMessageStackFrame[]
与消息或失败关联的堆栈跟踪。
TestMessageStackFrame
在 TestMessage.stackTrace 中找到的堆栈帧。
构造函数
new TestMessageStackFrame(label: string, uri?: Uri, position?: Position): TestMessageStackFrame
参数 | 描述 |
---|---|
label: string | 堆栈帧的名称 |
uri?: Uri | |
position?: Position | 堆栈帧在文件中的位置 |
返回值 | 描述 |
TestMessageStackFrame |
属性
堆栈帧的名称,通常是方法或函数名称。
position?: Position
堆栈帧在文件中的位置。
uri?: Uri
此堆栈帧的位置。如果编辑器可以访问调用帧的位置,则应将其作为 URI 提供。
TestRun
TestRun 表示正在进行中或已完成的测试运行,并提供报告运行中各个测试状态的方法。
事件
onDidDispose: Event<void>
当编辑器不再对与测试运行关联的数据感兴趣时触发的事件。
属性
测试运行是否会被编辑器跨重载持久化。
运行的用户可读名称。 这可以用于消除测试运行中多组结果的歧义。 例如,如果测试跨多个平台运行,则此功能很有用。
token: CancellationToken
取消令牌,当从 UI 取消测试运行时,将触发该令牌。
方法
addCoverage(fileCoverage: FileCoverage): void
为运行中的文件添加覆盖率。
参数 | 描述 |
---|---|
fileCoverage: FileCoverage | |
返回值 | 描述 |
void |
appendOutput(output: string, location?: Location, test?: TestItem): void
追加来自测试运行器的原始输出。根据用户的请求,输出将显示在终端中。支持 ANSI 转义序列,例如颜色和文本样式。换行符必须以 CRLF (\r\n
) 而不是 LF (\n
) 给出。
表示测试运行结束的信号。运行中包含的任何状态尚未更新的测试将重置其状态。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
enqueued(test: TestItem): void
指示测试已排队等待稍后执行。
参数 | 描述 |
---|---|
test: TestItem | 要更新的测试项。 |
返回值 | 描述 |
void |
errored(test: TestItem, message: TestMessage | readonly TestMessage[], duration?: number): void
指示测试已出错。您应该传递一个或多个 TestMessage 来描述失败。这与“失败”状态不同,因为它指示一个根本无法执行的测试,例如来自编译错误。
参数 | 描述 |
---|---|
test: TestItem | 要更新的测试项。 |
message: TestMessage | readonly TestMessage[] | 与测试失败关联的消息。 |
duration?: number | 测试执行花费的时间,以毫秒为单位。 |
返回值 | 描述 |
void |
failed(test: TestItem, message: TestMessage | readonly TestMessage[], duration?: number): void
指示测试已失败。您应该传递一个或多个 TestMessage 来描述失败。
参数 | 描述 |
---|---|
test: TestItem | 要更新的测试项。 |
message: TestMessage | readonly TestMessage[] | 与测试失败关联的消息。 |
duration?: number | 测试执行花费的时间,以毫秒为单位。 |
返回值 | 描述 |
void |
passed(test: TestItem, duration?: number): void
指示测试已通过。
参数 | 描述 |
---|---|
test: TestItem | 要更新的测试项。 |
duration?: number | 测试执行花费的时间,以毫秒为单位。 |
返回值 | 描述 |
void |
skipped(test: TestItem): void
指示测试已被跳过。
参数 | 描述 |
---|---|
test: TestItem | 要更新的测试项。 |
返回值 | 描述 |
void |
started(test: TestItem): void
指示测试已开始运行。
参数 | 描述 |
---|---|
test: TestItem | 要更新的测试项。 |
返回值 | 描述 |
void |
TestRunProfile
TestRunProfile 描述了在 TestController 中执行测试的一种方式。
事件
onDidChangeDefault: Event<boolean>
当用户更改此配置文件是否为默认配置文件时触发。事件包含 isDefault 的新值
属性
如果此方法存在,则 UI 中将显示一个配置齿轮,并且单击该齿轮时将调用此方法。调用时,您可以执行其他编辑器操作,例如显示快速选择或打开配置文件。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
控制此配置文件是否是其类型被操作时将采取的默认操作。例如,如果用户单击通用的“全部运行”按钮,则将执行 TestRunProfileKind.Run 的默认配置文件,尽管用户可以配置此项。
用户在其默认配置文件中所做的更改将在 onDidChangeDefault 事件之后反映在此属性中。
kind: TestRunProfileKind
配置此配置文件控制的执行类型。如果某种类型没有配置文件,它将不会在 UI 中可用。
在 UI 中向用户显示的标签。
请注意,如果用户请求以某种方式重新运行测试,则标签具有一定的意义。例如,如果测试正常运行,并且用户请求在调试模式下重新运行它们,则编辑器将尝试使用具有与 Debug
类型相同标签的配置。如果没有这样的配置,将使用默认配置。
loadDetailedCoverage?: (testRun: TestRun, fileCoverage: FileCoverage, token: CancellationToken) => Thenable<FileCoverageDetail[]>
扩展提供的函数,用于为文件提供详细的语句和函数级覆盖率。当需要文件的更多详细信息时,例如当文件在编辑器中打开或在测试覆盖率视图中展开时,编辑器将调用此函数。
传递给此函数的 FileCoverage 对象与与此配置文件关联的 TestRun.addCoverage 调用中发出的实例相同。
参数 | 描述 |
---|---|
testRun: TestRun | |
fileCoverage: FileCoverage | |
token: CancellationToken | |
返回值 | 描述 |
Thenable<FileCoverageDetail[]> |
loadDetailedCoverageForTest?: (testRun: TestRun, fileCoverage: FileCoverage, fromTestItem: TestItem, token: CancellationToken) => Thenable<FileCoverageDetail[]>
扩展提供的函数,用于为文件中单个测试提供详细的语句和函数级覆盖率。这是 TestRunProfile.loadDetailedCoverage 的每个测试的同级方法,仅当 FileCoverage.includesTests 中提供了测试项时,并且仅适用于报告此类数据的文件时才调用。
通常,当用户打开文件时,将首先调用 TestRunProfile.loadDetailedCoverage,然后,如果他们深入查看特定的每个测试的覆盖率信息,则将调用此方法。然后,此方法应仅返回运行期间由特定测试执行的语句和声明的覆盖率数据。
传递给此函数的 FileCoverage 对象与与此配置文件关联的 TestRun.addCoverage 调用中发出的实例相同。
参数 | 描述 |
---|---|
testRun: TestRun | 生成覆盖率数据的测试运行。 |
fileCoverage: FileCoverage | 要加载详细覆盖率的文件覆盖率对象。 |
fromTestItem: TestItem | 要请求覆盖率信息的测试项。 |
token: CancellationToken | 指示操作应取消的取消令牌。 |
返回值 | 描述 |
Thenable<FileCoverageDetail[]> |
runHandler: (request: TestRunRequest, token: CancellationToken) => void | Thenable<void>
调用以启动测试运行的处理程序。调用时,该函数应至少调用一次 TestController.createTestRun,并且与请求关联的所有测试运行都应在函数返回或返回的 Promise 被解析之前创建。
如果设置了 supportsContinuousRun,则 TestRunRequest.continuous 可能为 true
。在这种情况下,配置文件应观察源代码的更改,并通过调用 TestController.createTestRun 来创建新的测试运行,直到在 token
上请求取消。
参数 | 描述 |
---|---|
request: TestRunRequest | 测试运行的请求信息。 |
token: CancellationToken | |
返回值 | 描述 |
void | Thenable<void> |
supportsContinuousRun: boolean
此配置文件是否支持持续运行请求。如果是,则 TestRunRequest.continuous 可以设置为 true
。默认为 false。
tag: TestTag
配置文件的关联标签。如果设置了此项,则只有在其 TestItem.tags 数组中包含相同标签的 TestItem 实例才有资格在此配置文件中执行。
方法
删除运行配置文件。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
TestRunProfileKind
TestRunProfile 控制的执行类型。
枚举成员
Run
测试配置文件类型。
Debug
测试配置文件类型。
Coverage
测试配置文件类型。
TestRunRequest
TestRunRequest 是 TestRun 的前身,而 TestRun 又通过将请求传递给 TestController.createTestRun 来创建。 TestRunRequest 包含有关应运行哪些测试、不应运行哪些测试以及它们如何运行(通过 profile)的信息。
通常,TestRunRequest 由编辑器创建并传递给 TestRunProfile.runHandler,但是您也可以在 runHandler
之外创建测试请求和运行。
构造函数
new TestRunRequest(include?: readonly TestItem[], exclude?: readonly TestItem[], profile?: TestRunProfile, continuous?: boolean, preserveFocus?: boolean): TestRunRequest
参数 | 描述 |
---|---|
include?: readonly TestItem[] | 要运行的特定测试的数组,如果未定义,则运行所有测试 |
exclude?: readonly TestItem[] | 要从运行中排除的测试数组。 |
profile?: TestRunProfile | 用于此请求的运行配置文件。 |
continuous?: boolean | 是否在源代码更改时持续运行测试。 |
preserveFocus?: boolean | 在运行开始时是否保留用户的焦点 |
返回值 | 描述 |
TestRunRequest |
属性
配置文件是否应在源代码更改时持续运行。仅与设置了 TestRunProfile.supportsContinuousRun 的配置文件相关。
exclude: readonly TestItem[]
用户标记为从本次运行中包含的测试中排除的测试数组;排除应在包含之后应用。
如果未请求排除,则可以省略。测试控制器不应运行排除的测试或任何排除的测试的子项。
include: readonly TestItem[]
要运行的特定测试的过滤器。如果给定,扩展应运行所有包含的测试及其所有子项,排除 TestRunRequest.exclude 中出现的任何测试。如果未定义此属性,则扩展应仅运行所有测试。
运行测试的过程应解析尚未解析的任何测试项的子项。
控制如何聚焦测试结果视图。如果为 true,编辑器将保持用户的焦点。如果为 false,编辑器将优先将焦点移动到测试结果视图中,尽管用户可以配置此项。
profile: TestRunProfile
用于此请求的配置文件。对于从编辑器 UI 发出的请求,此项将始终定义,尽管扩展可以以编程方式创建与任何配置文件都不关联的请求。
TestTag
标签可以与 TestItem 和 TestRunProfile 关联。带有标签的配置文件只能执行在其 TestItem.tags 数组中包含该标签的测试。
构造函数
new TestTag(id: string): TestTag
创建一个新的 TestTag 实例。
参数 | 描述 |
---|---|
id: string | 测试标签的 ID。 |
返回值 | 描述 |
TestTag |
属性
测试标签的 ID。具有相同 ID 的 TestTag
实例被认为是相同的。
TextDocument
表示文本文档,例如源文件。文本文档具有 行 以及关于底层资源(如文件)的知识。
属性
eol: EndOfLine
此文档中主要使用的行尾序列。
关联资源的文件系统路径。 TextDocument.uri.fsPath 的简写符号。独立于 uri 方案。
如果文档已关闭,则为 true
。关闭的文档不再同步,并且当再次打开相同的资源时,将不会重复使用。
如果存在未持久化的更改,则为 true
。
此文档是否表示尚未保存的未命名文件。 注意,这并不意味着文档将保存到磁盘,请使用 Uri.scheme 来确定文档将保存到的位置,例如 file
,ftp
等。
与此文档关联的语言的标识符。
此文档中的行数。
uri: Uri
此文档关联的 uri。
注意,大多数文档使用 file
方案,这意味着它们是磁盘上的文件。但是,并非所有文档都保存在磁盘上,因此在尝试访问基础文件或磁盘上的同级文件之前,必须检查 scheme
。
另请参阅
此文档的版本号(在每次更改(包括撤消/重做)后,它将严格增加)。
方法
getText(range?: Range): string
getWordRangeAtPosition(position: Position, regex?: RegExp): Range
在给定位置获取单词范围。默认情况下,单词由常见分隔符(如空格、-、_ 等)定义。此外,可以为每种语言定义自定义[单词定义]。也可以提供自定义正则表达式。
- 注意 1:自定义正则表达式不得匹配空字符串,如果匹配,则会被忽略。
- 注意 2:自定义正则表达式将无法匹配多行字符串,并且为了提高速度,正则表达式不应匹配带有空格的单词。对于更复杂的、非单词的场景,请使用 TextLine.text。
位置将调整。
lineAt(line: number): TextLine
返回由行号表示的文本行。请注意,返回的对象是非实时的,并且对文档的更改不会反映出来。
lineAt(position: Position): TextLine
offsetAt(position: Position): number
positionAt(offset: number): Position
保存底层文件。
参数 | 描述 |
---|---|
返回值 | 描述 |
Thenable<boolean> | 一个 Promise,当文件已保存时将解析为 |
validatePosition(position: Position): Position
validateRange(range: Range): Range
TextDocumentChangeEvent
描述事务性 文档 更改的事件。
属性
contentChanges: readonly TextDocumentContentChangeEvent[]
内容更改的数组。
document: TextDocument
受影响的文档。
reason: TextDocumentChangeReason
文档更改的原因。如果原因未知,则为 undefined
。
TextDocumentChangeReason
文本文档更改的原因。
枚举成员
文本更改是由撤消操作引起的。
文本更改是由重做操作引起的。
TextDocumentContentChangeEvent
描述 文档 文本中单个更改的事件。
属性
range: Range
被替换的范围。
被替换范围的长度。
被替换范围的偏移量。
该范围的新文本。
TextDocumentContentProvider
文本文档内容提供程序允许向编辑器添加只读文档,例如来自 dll 的源代码或来自 md 生成的 html。
事件
用于发出资源已更改信号的事件。
方法
provideTextDocumentContent(uri: Uri, token: CancellationToken): ProviderResult<string>
参数 | 描述 |
---|---|
uri: Uri | 其方案与此提供程序注册的方案匹配的 uri。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<string> | 字符串或解析为此的 thenable。 |
TextDocumentSaveReason
表示文本文档被保存的原因。
枚举成员
手动触发,例如,用户按下保存按钮、开始调试或通过 API 调用。
延迟后自动保存。
当编辑器失去焦点时。
TextDocumentShowOptions
属性
一个可选标志,当为 true
时,将阻止 编辑器 获取焦点。
一个可选标志,用于控制 编辑器-选项卡是否显示为预览。预览选项卡将被替换和重用,直到设置为保留 - 无论是显式设置还是通过编辑设置。
注意,如果用户在设置中禁用了预览编辑器,则该标志将被忽略。
selection?: Range
要应用于 编辑器 中文档的可选选择范围。
viewColumn?: ViewColumn
一个可选的视图列,应在其中显示 编辑器。默认值为 active。不存在的列将根据需要创建,最多为 ViewColumn.Nine。使用 ViewColumn.Beside 在当前活动编辑器的侧面打开编辑器。
TextDocumentWillSaveEvent
属性
document: TextDocument
即将被保存的文档。
reason: TextDocumentSaveReason
触发保存的原因。
方法
waitUntil(thenable: Thenable<readonly TextEdit[]>): void
允许暂停事件循环并应用 预保存编辑。 对此函数的后续调用的编辑将按顺序应用。 如果文档同时发生修改,则编辑将被忽略。
注意: 此函数只能在事件分发期间调用,而不能以异步方式调用
workspace.onWillSaveTextDocument(event => {
// async, will *throw* an error
setTimeout(() => event.waitUntil(promise));
// sync, OK
event.waitUntil(promise);
});
waitUntil(thenable: Thenable<any>): void
允许暂停事件循环,直到提供的 thenable 解析。
注意: 此函数只能在事件分发期间调用。
参数 | 描述 |
---|---|
thenable: Thenable<any> | 一个延迟保存的 thenable。 |
返回值 | 描述 |
void |
TextEdit
文本编辑表示应应用于文档的编辑。
静态
delete(range: Range): TextEdit
insert(position: Position, newText: string): TextEdit
用于创建插入编辑的实用程序。
replace(range: Range, newText: string): TextEdit
setEndOfLine(eol: EndOfLine): TextEdit
构造函数
new TextEdit(range: Range, newText: string): TextEdit
属性
newEol?: EndOfLine
文档中使用的 eol 序列。
注意,eol 序列将应用于整个文档。
此编辑将插入的字符串。
range: Range
此编辑应用到的范围。
TextEditor
表示附加到 文档 的编辑器。
属性
document: TextDocument
与此文本编辑器关联的文档。 该文档在此文本编辑器的整个生命周期内都将是相同的。
options: TextEditorOptions
文本编辑器选项。
selection: Selection
此文本编辑器上的主选择范围。 TextEditor.selections[0]
的简写。
selections: readonly Selection[]
此文本编辑器中的选择范围。 主选择范围始终位于索引 0 处。
viewColumn: ViewColumn
此编辑器显示的列。 如果这不是主编辑器之一(例如,嵌入式编辑器),或者当编辑器列大于 3 时,将为 undefined
。
visibleRanges: readonly Range[]
编辑器中当前可见的范围(垂直方向)。 这仅考虑垂直滚动,而不考虑水平滚动。
方法
edit(callback: (editBuilder: TextEditorEdit) => void, options?: {undoStopAfter: boolean, undoStopBefore: boolean}): Thenable<boolean>
对与此文本编辑器关联的文档执行编辑。
使用 编辑构建器 调用给定的回调函数,必须使用该构建器进行编辑。 请注意,编辑构建器仅在回调执行时有效。
参数 | 描述 |
---|---|
callback: (editBuilder: TextEditorEdit) => void | 可以使用 编辑构建器 创建编辑的函数。 |
options?: {undoStopAfter: boolean, undoStopBefore: boolean} | 此编辑周围的撤消/重做行为。 默认情况下,将在此编辑之前和之后创建撤消停止点。 |
返回值 | 描述 |
Thenable<boolean> | 一个 Promise,解析为一个值,指示是否可以应用编辑。 |
隐藏文本编辑器。
- 已弃用 - 请改用命令
workbench.action.closeActiveEditor
。 此方法显示意外行为,将在下一个主要更新中删除。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
insertSnippet(snippet: SnippetString, location?: Range | Position | readonly Range[] | readonly Position[], options?: {keepWhitespace: boolean, undoStopAfter: boolean, undoStopBefore: boolean}): Thenable<boolean>
插入一个 代码片段 并将编辑器置于代码片段模式。“代码片段模式”意味着编辑器添加占位符和额外的光标,以便用户可以完成或接受代码片段。
参数 | 描述 |
---|---|
snippet: SnippetString | 要在此编辑中插入的代码片段。 |
location?: Range | Position | readonly Range[] | readonly Position[] | 插入代码片段的位置或范围,默认为当前编辑器选择或多个选择。 |
options?: {keepWhitespace: boolean, undoStopAfter: boolean, undoStopBefore: boolean} | 此编辑周围的撤消/重做行为。 默认情况下,将在此编辑之前和之后创建撤消停止点。 |
返回值 | 描述 |
Thenable<boolean> | 一个 Promise,解析为一个值,指示是否可以插入代码片段。 请注意,该 Promise 不会指示代码片段已完全填写或接受。 |
revealRange(range: Range, revealType?: TextEditorRevealType): void
按照 revealType
的指示滚动,以显示给定的范围。
参数 | 描述 |
---|---|
range: Range | 一个范围。 |
revealType?: TextEditorRevealType | 用于显示 |
返回值 | 描述 |
void |
setDecorations(decorationType: TextEditorDecorationType, rangesOrOptions: readonly Range[] | readonly DecorationOptions[]): void
参数 | 描述 |
---|---|
decorationType: TextEditorDecorationType | 一种装饰类型。 |
rangesOrOptions: readonly Range[] | readonly DecorationOptions[] | |
返回值 | 描述 |
void |
show(column?: ViewColumn): void
显示文本编辑器。
- 已弃用 - 请改用 window.showTextDocument。
参数 | 描述 |
---|---|
column?: ViewColumn | 要在其中显示此编辑器的 列。 此方法显示意外行为,将在下一个主要更新中删除。 |
返回值 | 描述 |
void |
TextEditorCursorStyle
光标的渲染样式。
枚举成员
将光标渲染为垂直粗线。
将光标渲染为实心块。
将光标渲染为水平粗线。
将光标渲染为垂直细线。
将光标渲染为轮廓块。
将光标渲染为水平细线。
TextEditorDecorationType
表示指向一组装饰的句柄,这些装饰在 文本编辑器 中共享相同的 样式选项。
要获取 TextEditorDecorationType
的实例,请使用 createTextEditorDecorationType。
属性
句柄的内部表示形式。
方法
删除此装饰类型以及所有文本编辑器上使用它的所有装饰。
参数 | 描述 |
---|---|
返回值 | 描述 |
void |
TextEditorEdit
方法
delete(location: Range | Selection): void
insert(location: Position, value: string): void
在某个位置插入文本。 您可以在 value
中使用 \r\n
或 \n
,它们将被规范化为当前的 文档。 尽管可以使用 replace 进行等效的文本编辑,但 insert
将产生不同的结果选择(它将被移动)。
参数 | 描述 |
---|---|
location: Position | 应在其中插入新文本的位置。 |
value: string | 此操作应插入的新文本。 |
返回值 | 描述 |
void |
replace(location: Range | Position | Selection, value: string): void
将某个文本区域替换为新值。 您可以在 value
中使用 \r\n
或 \n
,它们将被规范化为当前的 文档。
setEndOfLine(endOfLine: EndOfLine): void
TextEditorLineNumbersStyle
行号的渲染样式。
枚举成员
不渲染行号。
渲染行号。
使用相对于主光标位置的值渲染行号。
每隔 10 行渲染行号。
TextEditorOptions
属性
cursorStyle?: TextEditorCursorStyle
此编辑器中光标的渲染样式。 获取文本编辑器的选项时,此属性将始终存在。 设置文本编辑器的选项时,此属性是可选的。
当 insertSpaces 为 true 时要插入的空格数。
获取文本编辑器的选项时,此属性将始终是一个数字(已解析)。 设置文本编辑器的选项时,此属性是可选的,它可以是数字或 "tabSize"
。
insertSpaces?: string | boolean
按下 Tab 键时,插入 n 个空格。 获取文本编辑器的选项时,此属性将始终是一个布尔值(已解析)。 设置文本编辑器的选项时,此属性是可选的,它可以是布尔值或 "auto"
。
lineNumbers?: TextEditorLineNumbersStyle
相对于当前行号渲染相对行号。 获取文本编辑器的选项时,此属性将始终存在。 设置文本编辑器的选项时,此属性是可选的。
制表符占用的空格大小。 这用于两个目的
- 制表符的渲染宽度;
- 当 insertSpaces 为 true 且
indentSize
设置为"tabSize"
时要插入的空格数。
获取文本编辑器的选项时,此属性将始终是一个数字(已解析)。 设置文本编辑器的选项时,此属性是可选的,它可以是数字或 "auto"
。
TextEditorOptionsChangeEvent
表示描述 文本编辑器的选项 更改的事件。
属性
options: TextEditorOptions
文本编辑器的选项 的新值。
textEditor: TextEditor
选项已更改的 文本编辑器。
TextEditorRevealType
表示文本编辑器中不同的 reveal 策略。
枚举成员
将以尽可能少的滚动显示范围。
范围将始终在视口的中心显示。
如果范围在视口之外,则它将在视口的中心显示。否则,它将以尽可能少的滚动显示。
范围将始终在视口的顶部显示。
TextEditorSelectionChangeEvent
表示描述 文本编辑器的选择范围 更改的事件。
属性
kind: TextEditorSelectionChangeKind
触发此事件的 更改类型。 可以是 undefined
。
selections: readonly Selection[]
文本编辑器的选择范围 的新值。
textEditor: TextEditor
选择范围已更改的 文本编辑器。
TextEditorSelectionChangeKind
表示可能导致 选择范围更改事件 的来源。
枚举成员
由于在编辑器中键入而导致选择范围更改。
Selection change due to clicking in the editor.
Selection changed because a command ran.
TextEditorViewColumnChangeEvent
Represents an event describing the change of a text editor's view column.
属性
textEditor: TextEditor
The text editor for which the view column has changed.
viewColumn: ViewColumn
The new value for the text editor's view column.
TextEditorVisibleRangesChangeEvent
Represents an event describing the change in a text editor's visible ranges.
属性
textEditor: TextEditor
The text editor for which the visible ranges have changed.
visibleRanges: readonly Range[]
The new value for the text editor's visible ranges.
TextLine
Represents a line of text, such as a line of source code.
TextLine objects are immutable. When a document changes, previously retrieved lines will not represent the latest state.
属性
firstNonWhitespaceCharacterIndex: number
The offset of the first character which is not a whitespace character as defined by /\s/
. Note that if a line is all whitespace the length of the line is returned.
Whether this line is whitespace only, shorthand for TextLine.firstNonWhitespaceCharacterIndex === TextLine.text.length.
The zero-based line number.
range: Range
The range this line covers without the line separator characters.
rangeIncludingLineBreak: Range
The range this line covers with the line separator characters.
The text of this line without the line separator characters.
ThemableDecorationAttachmentRenderOptions
属性
backgroundColor?: string | ThemeColor
CSS styling property that will be applied to the decoration attachment.
CSS styling property that will be applied to the decoration attachment.
borderColor?: string | ThemeColor
将应用于由装饰括起来的文本的 CSS 样式属性。
color?: string | ThemeColor
CSS styling property that will be applied to the decoration attachment.
contentIconPath?: string | Uri
An absolute path or an URI to an image to be rendered in the attachment. Either an icon or a text can be shown, but not both.
Defines a text content that is shown in the attachment. Either an icon or a text can be shown, but not both.
CSS styling property that will be applied to the decoration attachment.
CSS styling property that will be applied to the decoration attachment.
CSS styling property that will be applied to the decoration attachment.
CSS styling property that will be applied to the decoration attachment.
CSS styling property that will be applied to the decoration attachment.
CSS styling property that will be applied to the decoration attachment.
ThemableDecorationInstanceRenderOptions
Represents themable render options for decoration instances.
属性
after?: ThemableDecorationAttachmentRenderOptions
定义插入到装饰文本之后的附件的渲染选项。
before?: ThemableDecorationAttachmentRenderOptions
定义插入到装饰文本之前的附件的渲染选项。
ThemableDecorationRenderOptions
Represents theme specific rendering styles for a text editor decoration.
属性
after?: ThemableDecorationAttachmentRenderOptions
定义插入到装饰文本之后的附件的渲染选项。
backgroundColor?: string | ThemeColor
装饰的背景颜色。使用 rgba() 并定义透明背景颜色以与其他装饰良好配合。或者,可以 引用 颜色注册表中的颜色。
before?: ThemableDecorationAttachmentRenderOptions
定义插入到装饰文本之前的附件的渲染选项。
将应用于由装饰括起来的文本的 CSS 样式属性。
borderColor?: string | ThemeColor
将应用于由装饰括起来的文本的 CSS 样式属性。最好使用 'border' 来设置一个或多个单独的边框属性。
将应用于由装饰括起来的文本的 CSS 样式属性。最好使用 'border' 来设置一个或多个单独的边框属性。
将应用于由装饰括起来的文本的 CSS 样式属性。最好使用 'border' 来设置一个或多个单独的边框属性。
将应用于由装饰括起来的文本的 CSS 样式属性。最好使用 'border' 来设置一个或多个单独的边框属性。
将应用于由装饰括起来的文本的 CSS 样式属性。最好使用 'border' 来设置一个或多个单独的边框属性。
color?: string | ThemeColor
将应用于由装饰括起来的文本的 CSS 样式属性。
将应用于由装饰括起来的文本的 CSS 样式属性。
将应用于由装饰括起来的文本的 CSS 样式属性。
将应用于由装饰括起来的文本的 CSS 样式属性。
gutterIconPath?: string | Uri
一个绝对路径或一个URI,指向要在边槽中渲染的图像。
指定边槽图标的大小。可用值包括 'auto'、'contain'、'cover' 和任何百分比值。更多信息请参考:https://msdn.microsoft.com/en-us/library/jj127316(v=vs.85).aspx
将应用于由装饰括起来的文本的 CSS 样式属性。
将应用于由装饰括起来的文本的 CSS 样式属性。
将应用于由装饰括起来的文本的 CSS 样式属性。
outlineColor?: string | ThemeColor
将应用于装饰所包围文本的 CSS 样式属性。最好使用 'outline' 来设置一个或多个单独的轮廓属性。
将应用于装饰所包围文本的 CSS 样式属性。最好使用 'outline' 来设置一个或多个单独的轮廓属性。
将应用于装饰所包围文本的 CSS 样式属性。最好使用 'outline' 来设置一个或多个单独的轮廓属性。
overviewRulerColor?: string | ThemeColor
概览标尺中装饰的颜色。使用 rgba() 并定义透明颜色以便与其他装饰良好配合。
将应用于由装饰括起来的文本的 CSS 样式属性。
ThemeColor
A reference to one of the workbench colors as defined in https://vscode.js.cn/api/references/theme-color. Using a theme color is preferred over a custom color as it gives theme authors and users the possibility to change the color.
构造函数
new ThemeColor(id: string): ThemeColor
Creates a reference to a theme color.
参数 | 描述 |
---|---|
id: string | of the color. The available colors are listed in https://vscode.js.cn/api/references/theme-color. |
返回值 | 描述 |
ThemeColor |
属性
The id of this color.
ThemeIcon
A reference to a named icon. Currently, File, Folder, and ThemeIcon ids are supported. Using a theme icon is preferred over a custom icon as it gives product theme authors the possibility to change the icons.
Note that theme icons can also be rendered inside labels and descriptions. Places that support theme icons spell this out and they use the $(<name>)
-syntax, for instance quickPick.label = "Hello World $(globe)"
.
静态
File: ThemeIcon
Reference to an icon representing a file. The icon is taken from the current file icon theme or a placeholder icon is used.
Folder: ThemeIcon
Reference to an icon representing a folder. The icon is taken from the current file icon theme or a placeholder icon is used.
构造函数
new ThemeIcon(id: string, color?: ThemeColor): ThemeIcon
Creates a reference to a theme icon.
参数 | 描述 |
---|---|
id: string | id of the icon. The available icons are listed in https://vscode.js.cn/api/references/icons-in-labels#icon-listing. |
color?: ThemeColor | optional |
返回值 | 描述 |
ThemeIcon |
属性
color?: ThemeColor
The optional ThemeColor of the icon. The color is currently only used in TreeItem.
The id of the icon. The available icons are listed in https://vscode.js.cn/api/references/icons-in-labels#icon-listing.
TreeCheckboxChangeEvent<T>
An event describing the change in a tree item's checkbox state.
属性
items: ReadonlyArray<[T, TreeItemCheckboxState]>
The items that were checked or unchecked.
TreeDataProvider<T>
A data provider that provides tree data
事件
onDidChangeTreeData?: Event<void | T | T[]>
An optional event to signal that an element or root has changed. This will trigger the view to update the changed element/root and its children recursively (if shown). To signal that root has changed, do not pass any argument or pass undefined
or null
.
方法
getChildren(element?: T): ProviderResult<T[]>
Get the children of element
or root if no element is passed.
参数 | 描述 |
---|---|
element?: T | The element from which the provider gets children. Can be |
返回值 | 描述 |
ProviderResult<T[]> | Children of |
getParent(element: T): ProviderResult<T>
Optional method to return the parent of element
. Return null
or undefined
if element
is a child of root.
NOTE: This method should be implemented in order to access reveal API.
参数 | 描述 |
---|---|
element: T | The element for which the parent has to be returned. |
返回值 | 描述 |
ProviderResult<T> | Parent of |
getTreeItem(element: T): TreeItem | Thenable<TreeItem>
Get TreeItem representation of the element
resolveTreeItem(item: TreeItem, element: T, token: CancellationToken): ProviderResult<TreeItem>
Called on hover to resolve the TreeItem property if it is undefined. Called on tree item click/open to resolve the TreeItem property if it is undefined. Only properties that were undefined can be resolved in resolveTreeItem
. Functionality may be expanded later to include being called to resolve other missing properties on selection and/or on open.
Will only ever be called once per TreeItem.
onDidChangeTreeData should not be triggered from within resolveTreeItem.
Note that this function is called when tree items are already showing in the UI. Because of that, no property that changes the presentation (label, description, etc.) can be changed.
参数 | 描述 |
---|---|
item: TreeItem | Undefined properties of |
element: T | The object associated with the TreeItem. |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<TreeItem> | The resolved tree item or a thenable that resolves to such. It is OK to return the given |
TreeDragAndDropController<T>
Provides support for drag and drop in TreeView
.
属性
dragMimeTypes: readonly string[]
The mime types that the handleDrag
method of this TreeDragAndDropController
may add to the tree data transfer. This could be well-defined, existing, mime types, and also mime types defined by the extension.
The recommended mime type of the tree (application/vnd.code.tree.<treeidlowercase>
) will be automatically added.
dropMimeTypes: readonly string[]
The mime types that the handleDrop
method of this DragAndDropController
supports. This could be well-defined, existing, mime types, and also mime types defined by the extension.
To support drops from trees, you will need to add the mime type of that tree. This includes drops from within the same tree. The mime type of a tree is recommended to be of the format application/vnd.code.tree.<treeidlowercase>
.
Use the special files
mime type to support all types of dropped files files, regardless of the file's actual mime type.
To learn the mime type of a dragged item
- Set up your
DragAndDropController
- Use the Developer: Set Log Level... command to set the level to "Debug"
- Open the developer tools and drag the item with unknown mime type over your tree. The mime types will be logged to the developer console
Note that mime types that cannot be sent to the extension will be omitted.
方法
handleDrag(source: readonly T[], dataTransfer: DataTransfer, token: CancellationToken): void | Thenable<void>
When the user starts dragging items from this DragAndDropController
, handleDrag
will be called. Extensions can use handleDrag
to add their DataTransferItem
items to the drag and drop.
When the items are dropped on another tree item in the same tree, your DataTransferItem
objects will be preserved. Use the recommended mime type for the tree (application/vnd.code.tree.<treeidlowercase>
) to add tree objects in a data transfer. See the documentation for DataTransferItem
for how best to take advantage of this.
To add a data transfer item that can be dragged into the editor, use the application specific mime type "text/uri-list". The data for "text/uri-list" should be a string with toString()
ed Uris separated by \r\n
. To specify a cursor position in the file, set the Uri's fragment to L3,5
, where 3 is the line number and 5 is the column number.
参数 | 描述 |
---|---|
source: readonly T[] | The source items for the drag and drop operation. |
dataTransfer: DataTransfer | The data transfer associated with this drag. |
token: CancellationToken | A cancellation token indicating that drag has been cancelled. |
返回值 | 描述 |
void | Thenable<void> |
handleDrop(target: T, dataTransfer: DataTransfer, token: CancellationToken): void | Thenable<void>
Called when a drag and drop action results in a drop on the tree that this DragAndDropController
belongs to.
Extensions should fire onDidChangeTreeData for any elements that need to be refreshed.
参数 | 描述 |
---|---|
target: T | The target tree element that the drop is occurring on. When undefined, the target is the root. |
dataTransfer: DataTransfer | The data transfer items of the source of the drag. |
token: CancellationToken | A cancellation token indicating that the drop has been cancelled. |
返回值 | 描述 |
void | Thenable<void> |
TreeItem
A tree item is an UI element of the tree. Tree items are created by the data provider.
构造函数
new TreeItem(label: string | TreeItemLabel, collapsibleState?: TreeItemCollapsibleState): TreeItem
参数 | 描述 |
---|---|
label: string | TreeItemLabel | A human-readable string describing this item |
collapsibleState?: TreeItemCollapsibleState | TreeItemCollapsibleState of the tree item. Default is TreeItemCollapsibleState.None |
返回值 | 描述 |
TreeItem |
new TreeItem(resourceUri: Uri, collapsibleState?: TreeItemCollapsibleState): TreeItem
参数 | 描述 |
---|---|
resourceUri: Uri | The Uri of the resource representing this item. |
collapsibleState?: TreeItemCollapsibleState | TreeItemCollapsibleState of the tree item. Default is TreeItemCollapsibleState.None |
返回值 | 描述 |
TreeItem |
属性
accessibilityInformation?: AccessibilityInformation
Accessibility information used when screen reader interacts with this tree item. Generally, a TreeItem has no need to set the role
of the accessibilityInformation; however, there are cases where a TreeItem is not displayed in a tree-like way where setting the role
may make sense.
checkboxState?: TreeItemCheckboxState | {accessibilityInformation: AccessibilityInformation, state: TreeItemCheckboxState, tooltip: string}
TreeItemCheckboxState of the tree item. onDidChangeTreeData should be fired when checkboxState changes.
collapsibleState?: TreeItemCollapsibleState
TreeItemCollapsibleState of the tree item.
command?: Command
The Command that should be executed when the tree item is selected.
Please use vscode.open
or vscode.diff
as command IDs when the tree item is opening something in the editor. Using these commands ensures that the resulting editor will appear consistent with how other built-in trees open editors.
Context value of the tree item. This can be used to contribute item specific actions in the tree. For example, a tree item is given a context value as folder
. When contributing actions to view/item/context
using menus
extension point, you can specify context value for key viewItem
in when
expression like viewItem == folder
.
"contributes": {
"menus": {
"view/item/context": [
{
"command": "extension.deleteFolder",
"when": "viewItem == folder"
}
]
}
}
This will show action extension.deleteFolder
only for items with contextValue
is folder
.
description?: string | boolean
A human-readable string which is rendered less prominent. When true
, it is derived from resourceUri and when falsy
, it is not shown.
iconPath?: string | IconPath
The icon path or ThemeIcon for the tree item. When falsy
, Folder Theme Icon is assigned, if item is collapsible otherwise File Theme Icon. When a file or folder ThemeIcon is specified, icon is derived from the current file icon theme for the specified theme icon using resourceUri (if provided).
Optional id for the tree item that has to be unique across tree. The id is used to preserve the selection and expansion state of the tree item.
If not provided, an id is generated using the tree item's label. Note that when labels change, ids will change and that selection and expansion state cannot be kept stable anymore.
label?: string | TreeItemLabel
A human-readable string describing this item. When falsy
, it is derived from resourceUri.
resourceUri?: Uri
tooltip?: string | MarkdownString
当您悬停在此项目上时显示的工具提示文本。
TreeItemCheckboxState
Checkbox state of the tree item
枚举成员
Determines an item is unchecked
Determines an item is checked
TreeItemCollapsibleState
Collapsible state of the tree item
枚举成员
Determines an item can be neither collapsed nor expanded. Implies it has no children.
确定项目是否折叠
确定项目是否展开
可折叠树项状态.已展开
属性
描述 树项 的标签
标签中要高亮显示的范围。范围定义为两个数字的元组,其中第一个是包含的起始索引,第二个是排除的结束索引
描述 树项 的人类可读字符串。
事件
表示树视图
onDidChangeCheckboxState: Event<TreeCheckboxChangeEvent<T>>
表示元素或根节点已被选中或取消选中的事件信号。
onDidChangeSelection: Event<TreeViewSelectionChangeEvent<T>>
当 selection 发生更改时触发的事件
onDidChangeVisibility: Event<TreeViewVisibilityChangeEvent>
当 visibility 发生更改时触发的事件
onDidCollapseElement: Event<TreeViewExpansionEvent<T>>
当元素被折叠时触发的事件
onDidExpandElement: Event<TreeViewExpansionEvent<T>>
属性
当元素被展开时触发的事件
badge?: ViewBadge
要为此 TreeView 显示的徽章。要移除徽章,请设置为 undefined。
一个可选的人类可读的描述,在视图的标题中以不太突出的方式呈现。将标题描述设置为 null、undefined 或空字符串将从视图中移除描述。
一个可选的人类可读的消息,将在视图中呈现。将消息设置为 null、undefined 或空字符串将从视图中移除消息。
当前选定的元素。
树视图标题最初取自扩展 package.json。对标题属性的更改将正确反映在 UI 视图的标题中。
方法
如果 树视图 可见,则为 true
,否则为 false
。
释放此对象。
参数 | 描述 |
---|---|
返回值 | 描述 |
any |
reveal(element: T, options?: {expand: number | boolean, focus: boolean, select: boolean}): Thenable<void>
在树视图中显示给定的元素。如果树视图不可见,则显示树视图并显示元素。
- 默认情况下,显示的元素会被选中。为了不选择,请将选项
select
设置为false
。为了聚焦,请将选项focus
设置为true
。为了展开显示的元素,请将选项expand
设置为true
。要递归展开,请将expand
设置为要展开的级别数。 - 注意: 您最多只能展开 3 个级别。
参数 | 描述 |
---|---|
element: T | |
注意: 使用 TreeView 注册的 TreeDataProvider 必须实现 getParent 方法才能访问此 API。 | |
返回值 | 描述 |
Thenable<void> |
options?: {expand: number | boolean, focus: boolean, select: boolean}
属性
当 TreeView 中的元素被展开或折叠时触发的事件
被展开或折叠的元素。
属性
用于创建 TreeView 的选项
树是否支持多选。当树支持多选并且从树执行命令时,命令的第一个参数是执行命令的树项,第二个参数是包含所有选定树项的数组。
dragAndDropController?: TreeDragAndDropController<T>
一个可选的接口,用于在树视图中实现拖放功能。
manageCheckboxStateManually?: boolean
默认情况下,当树项的子项已被获取时,子复选框会根据父树项的选中状态自动管理。如果树项默认折叠(意味着子项尚未被获取),则子复选框将不会被更新。要覆盖此行为并在扩展中手动管理子复选框和父复选框状态,请将其设置为 true
。
以下是 TreeViewOptions.manageCheckboxStateManually 为 false 时的示例,即默认行为
一个树项被选中,然后获取其子项。子项将被选中。
- 一个树项的父项被选中。该树项及其所有兄弟项都将被选中。
- 父项
- 子项 1
- 一个树项的父项被选中。该树项及其所有兄弟项都将被选中。
- 父项
- 子项 2 当用户选中“父项”时,树将如下所示
- 子项 2
- 一个树项的父项被选中。该树项及其所有兄弟项都将被选中。
- 父项
- 一个树项及其所有兄弟项都被选中。父项将被选中。
- 一个树项的父项被选中。该树项及其所有兄弟项都将被选中。
- 父项
- 子项 2 当用户选中“父项”时,树将如下所示
- 子项 2 当用户选中“子项 1”和“子项 2”时,树将如下所示
- 一个树项的父项被选中。该树项及其所有兄弟项都将被选中。
- 父项
- 一个树项被取消选中。父项将被取消选中。
- 一个树项的父项被选中。该树项及其所有兄弟项都将被选中。
- 父项
- 子项 2 当用户选中“父项”时,树将如下所示
子项 2 当用户取消选中“子项 1”时,树将如下所示
是否显示全部折叠操作。
treeDataProvider: TreeDataProvider<T>
提供树数据的 data provider。
属性
当 树视图的选择 发生更改时触发的事件
选定的元素。
属性
当 树视图的可见性 发生更改时触发的事件
visible: boolean
方法
类型定义提供程序定义了扩展和转到类型定义功能之间的契约。
provideTypeDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | LocationLink[]>
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<Definition | LocationLink[]> | 一个定义或一个可以解析为此定义的 thenable 对象。缺少结果可以通过返回 |
提供给定位置和文档处符号的类型定义。
构造函数
表示类型层次结构的项目,例如类或接口。
new TypeHierarchyItem(kind: SymbolKind, name: string, detail: string, uri: Uri, range: Range, selectionRange: Range): TypeHierarchyItem
参数 | 描述 |
---|---|
kind: SymbolKind | 创建一个新的类型层次结构项。 |
name: string | 项的种类。 |
detail: string | 项的名称。 |
uri: Uri | 项的详细信息。 |
range: Range | 项的 Uri。 |
selectionRange: Range | 项的完整范围。 |
返回值 | 描述 |
项的选择范围。 |
属性
TypeHierarchyItem
此项的更多详细信息,例如函数的签名。
此项的种类。
kind: SymbolKind
此项的名称。
包含此符号的范围,不包括前导/尾随空格,但包括所有其他内容,例如注释和代码。
range: Range
selectionRange: Range
当此符号被选取时,应选择和显示的范围,例如类的名称。必须包含在 range 属性中。
此项的标签。
tags?: readonly SymbolTag[]
此项的资源标识符。
uri: Uri
方法
类型层次结构提供程序接口描述了扩展和类型层次结构功能之间的契约。
prepareTypeHierarchy(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<TypeHierarchyItem | TypeHierarchyItem[]>
参数 | 描述 |
---|---|
document: TextDocument | 调用命令所在的文档。 |
position: Position | 调用命令的位置。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
通过返回给定文档和位置表示的项来引导类型层次结构。此项将用作类型图的入口。当给定位置没有项时,提供程序应返回 undefined 或 null 。 |
一个或多个类型层次结构项或解析为此项的可 thenable 对象。缺少结果可以通过返回 undefined
、null
或空数组来表示。
provideTypeHierarchySubtypes(item: TypeHierarchyItem, token: CancellationToken): ProviderResult<TypeHierarchyItem[]>
参数 | 描述 |
---|---|
为项提供所有子类型,例如从给定项派生/继承的所有类型。在图论术语中,这描述了类型图内部的有向和带注释的边,例如,给定项是起始节点,结果是可以到达的节点。 | item: TypeHierarchyItem |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
应计算子类型的层次结构项。 |
一组直接子类型或解析为此类型的可 thenable 对象。缺少结果可以通过返回 undefined
或 null
来表示。
provideTypeHierarchySupertypes(item: TypeHierarchyItem, token: CancellationToken): ProviderResult<TypeHierarchyItem[]>
参数 | 描述 |
---|---|
为项提供所有子类型,例如从给定项派生/继承的所有类型。在图论术语中,这描述了类型图内部的有向和带注释的边,例如,给定项是起始节点,结果是可以到达的节点。 | 为项提供所有超类型,例如从中派生/继承类型的所有类型。在图论术语中,这描述了类型图内部的有向和带注释的边,例如,给定项是起始节点,结果是可以到达的节点。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
应计算子类型的层次结构项。 | 应计算超类型的层次结构项。 |
一组直接超类型或解析为此类型的可 thenable 对象。缺少结果可以通过返回 undefined
或 null
来表示。
枚举成员
可以使用扩展的 UI 的可能种类。
从桌面应用程序访问扩展。
从 Web 浏览器访问扩展。
静态
一个通用资源标识符,表示磁盘上的文件或其他资源,例如未命名的资源。
file(path: string): Uri
从文件系统路径创建 URI。scheme 将为 file
。
const good = URI.file('/coding/c#/project1');
good.scheme === 'file';
good.path === '/coding/c#/project1';
good.fragment === '';
const bad = URI.parse('file://' + '/coding/c#/project1');
bad.scheme === 'file';
bad.path === '/coding/c'; // path is now broken
bad.fragment === '/project1';
一个新的 Uri 实例。
from(components: {authority: string, fragment: string, path: string, query: string, scheme: string}): Uri
从其组成部分创建 URI
参数 | 描述 |
---|---|
另请参阅 Uri.toString | components: {authority: string, fragment: string, path: string, query: string, scheme: string} |
返回值 | 描述 |
Uri | 文件系统或 UNC 路径。 |
Uri 的组成部分。
一个新的 uri,其路径与给定的片段连接
parse(value: string, strict?: boolean): Uri
从字符串创建 URI,例如 http://www.example.com/some/path
、file:///usr/home
或 scheme:with/path
。
从其组成部分创建 URI
参数 | 描述 |
---|---|
value: string | 注意,一段时间以来,接受没有 |
Uri 的字符串值。 | strict?: boolean |
返回值 | 描述 |
Uri | 文件系统或 UNC 路径。 |
构造函数
当 value
为空或无法解析 scheme
时抛出错误。
new Uri(scheme: string, authority: string, path: string, query: string, fragment: string): Uri
参数 | 描述 |
---|---|
scheme: string | |
使用 file 和 parse 工厂函数创建新的 Uri 对象。 | |
path: string | |
authority: string | |
query: string | |
返回值 | 描述 |
Uri |
属性
fragment: string
Authority 是 http://www.example.com/some/path?query#fragment
中的 www.example.com
部分。第一个双斜杠和下一个斜杠之间的部分。
Fragment 是 http://www.example.com/some/path?query#fragment
中的 fragment
部分。
表示此 Uri 的相应文件系统路径的字符串。
- 将处理 UNC 路径并将 windows 驱动器号规范化为小写。还使用平台特定的路径分隔符。
- 不会验证路径是否包含无效字符和语义。
- 不会查看此 Uri 的 scheme。
结果字符串不应用于显示目的,而是用于磁盘操作,例如 readFile
等。
const u = URI.parse('file://server/c$/folder/file.txt');
u.authority === 'server';
u.path === '/c$/folder/file.txt';
u.fsPath === '\\serverc$\folder\file.txt';
path 属性的区别在于使用了平台特定的路径分隔符以及 UNC 路径的处理。以下示例概述了区别
Path 是 http://www.example.com/some/path?query#fragment
中的 /some/path
部分。
Query 是 http://www.example.com/some/path?query#fragment
中的 query
部分。
方法
Scheme 是 http://www.example.com/some/path?query#fragment
中的 http
部分。第一个冒号之前的部分。
一个对象。
toString(skipEncoding?: boolean): string
- 返回此 Uri 的字符串表示形式。URI 的表示形式和规范化取决于 scheme。
- 结果字符串可以安全地与 Uri.parse 一起使用。
结果字符串不应用于显示目的。
参数 | 描述 |
---|---|
注意,该实现将积极编码,这通常会导致意外但并非不正确的结果。例如,冒号被编码为 %3A ,这在 file-uri 中可能是意外的。此外,& 和 = 将被编码,这对于 http-uris 可能是意外的。出于稳定性原因,这无法再更改。如果您因过于积极的编码而受到影响,则应使用 skipEncoding 参数:uri.toString(true) 。 | skipEncoding?: boolean |
返回值 | 描述 |
string | 不要对结果进行百分比编码,默认为 |
此 Uri 的字符串表示形式。
with(change: {authority: string, fragment: string, path: string, query: string, scheme: string}): Uri
let file = Uri.parse('before:some/file/path');
let other = file.with({ scheme: 'after' });
assert.ok(other.toString() === 'after:some/file/path');
参数 | 描述 |
---|---|
从此 Uri 派生一个新的 Uri。 | change: {authority: string, fragment: string, path: string, query: string, scheme: string} |
返回值 | 描述 |
Uri | 一个描述对此 Uri 进行更改的对象。要取消设置组件,请使用 |
反映给定更改的新 Uri。如果更改未更改任何内容,则将返回 this
Uri。
uri 处理程序负责处理系统范围的 uris。
方法
另请参阅 window.registerUriHandler。
handleUri(uri: Uri): ProviderResult<void>
uri 处理程序负责处理系统范围的 uris。
参数 | 描述 |
---|---|
uri: Uri | |
返回值 | 描述 |
ProviderResult<void> |
处理提供的系统范围的 Uri。
属性
徽章,用于呈现视图的值
要在徽章的工具提示中显示的标签。
要在徽章中呈现的值。
枚举成员
表示编辑器在窗口中的位置。编辑器可以排列在网格中,每列通过按编辑器出现的顺序计数来表示该网格中的一个编辑器位置。
一个符号编辑器列,表示活动列旁边的列。此值可以在打开编辑器时使用,但编辑器的已解析 viewColumn 值将始终为 One
、Two
、Three
,... 或 undefined
,但永远不会为 Beside
。
一个符号编辑器列,表示当前活动列。此值可以在打开编辑器时使用,但编辑器的已解析 viewColumn 值将始终为 One
、Two
、Three
,... 或 undefined
,但永远不会为 Active
。
第一个编辑器列。
第二个编辑器列。
第三个编辑器列。
第四个编辑器列。
第五个编辑器列。
第六个编辑器列。
第七个编辑器列。
第八个编辑器列。
第九个编辑器列。
事件
显示 html 内容,类似于 iframe。
onDidReceiveMessage: Event<any>
Webview 内容可以向扩展程序回传字符串或 JSON 可序列化对象。它们不能回传 Blob
、File
、ImageData
和其他 DOM 特定的对象,因为接收消息的扩展程序不在浏览器环境中运行。
属性
Webview 资源的内容安全策略源。
这是应该在内容安全策略规则中使用的源。
`img-src https: ${webview.cspSource} ...;`;
Webview 的 HTML 内容。
这应该是一个完整的、有效的 HTML 文档。更改此属性会导致 webview 重新加载。
Webview 与正常的扩展进程沙盒隔离,因此与 webview 的所有通信都必须使用消息传递。要从扩展程序向 webview 发送消息,请使用 postMessage。要从 webview 向扩展程序回传消息,请在 webview 内部使用 acquireVsCodeApi
函数获取编辑器 API 的句柄,然后调用 .postMessage()
。
<script>
const vscode = acquireVsCodeApi(); // acquireVsCodeApi can only be invoked once
vscode.postMessage({ message: 'hello!' });
</script>
要从 webview 内部加载工作区中的资源,请使用 asWebviewUri 方法,并确保资源的目录已在 WebviewOptions.localResourceRoots 中列出。
请记住,即使 webview 是沙盒隔离的,它们仍然允许运行脚本和加载任意内容,因此扩展程序在使用 webview 时必须遵循所有标准的 Web 安全最佳实践。这包括正确地清理所有不受信任的输入(包括来自工作区的内容)以及设置 内容安全策略。
options: WebviewOptions
Webview 的内容设置。
方法
asWebviewUri(localResource: Uri): Uri
将本地文件系统的 URI 转换为可在 webview 内部使用的 URI。
Webview 无法使用 file:
URI 直接从工作区或本地文件系统加载资源。asWebviewUri
函数接受本地 file:
URI,并将其转换为可在 webview 内部用于加载相同资源的 URI。
webview.html = `<img src="${webview.asWebviewUri(
vscode.Uri.file('/Users/codey/workspace/cat.gif')
)}">`;
postMessage(message: any): Thenable<boolean>
向 webview 内容发送消息。
只有在 webview 处于活动状态(可见或在后台且具有 retainContextWhenHidden
)时,消息才会被传递。
参数 | 描述 |
---|---|
message: any | 消息的主体。这必须是字符串或其他 JSON 可序列化对象。 对于旧版本的 VS Code,如果 但是,如果您的扩展程序在 |
返回值 | 描述 |
Thenable<boolean> | 当消息发布到 webview 或由于消息无法传递而被丢弃时,Promise 将会解析。 如果消息已发布到 webview,则返回
如果您想确认消息是否实际被接收,您可以尝试让您的 webview 向您的扩展程序回传确认消息。 |
WebviewOptions
webview 的内容设置。
属性
enableCommandUris?: boolean | readonly string[]
控制是否在 webview 内容中启用命令 URI。
默认为 false
(禁用命令 URI)。
如果您传入一个数组,则仅允许数组中的命令。
控制是否在 webview 内容中启用表单。
如果 脚本已启用,则默认为 true。否则默认为 false。显式地将此属性设置为 true 或 false 将覆盖默认值。
控制是否在 webview 内容中启用脚本。
默认为 false(禁用脚本)。
localResourceRoots?: readonly Uri[]
Webview 可以使用来自 asWebviewUri
的 URI 从中加载本地(文件系统)资源的根路径。
默认为当前工作区的根文件夹加上扩展程序的安装目录。
传入一个空数组以禁止访问任何本地资源。
portMapping?: readonly WebviewPortMapping[]
在 webview 内部使用的 localhost 端口的映射。
端口映射允许 webview 透明地定义 localhost 端口的解析方式。这可用于允许在 webview 内部使用静态 localhost 端口,该端口被解析为服务正在运行的随机端口。
如果 webview 访问 localhost 内容,我们建议您指定端口映射,即使 webviewPort
和 extensionHostPort
端口相同也是如此。
注意:端口映射仅适用于 http
或 https
URL。WebSocket URL(例如 ws://127.0.0.1:3000
)无法映射到另一个端口。
WebviewPanel
包含 webview 的面板。
事件
onDidChangeViewState: Event<WebviewPanelOnDidChangeViewStateEvent>
当面板的视图状态更改时触发。
onDidDispose: Event<void>
当面板被释放时触发。
这可能是因为用户关闭了面板,或者是因为在其上调用了 .dispose()
。
尝试在面板释放后使用它会引发异常。
属性
面板是否处于活动状态(被用户聚焦)。
iconPath?: Uri | {dark: Uri, light: Uri}
面板在 UI 中显示的图标。
options: WebviewPanelOptions
webview 面板的内容设置。
面板在 UI 中显示的标题。
viewColumn: ViewColumn
面板的编辑器位置。仅当 webview 位于编辑器视图列之一时,才设置此属性。
标识 webview 面板的类型,例如 'markdown.preview'
。
面板是否可见。
webview: Webview
Webview 属于该面板。
方法
释放 webview 面板。
这将关闭面板(如果正在显示)并释放 webview 拥有的资源。当用户关闭 webview 面板时,webview 面板也会被释放。两种情况都会触发 onDispose
事件。
参数 | 描述 |
---|---|
返回值 | 描述 |
any |
reveal(viewColumn?: ViewColumn, preserveFocus?: boolean): void
在给定的列中显示 webview 面板。
一个 webview 面板一次只能在一个列中显示。如果它已经显示,此方法会将其移动到新列。
参数 | 描述 |
---|---|
viewColumn?: ViewColumn | 要在其中显示面板的视图列。如果未定义,则在当前的 |
preserveFocus?: boolean | 当为 |
返回值 | 描述 |
void |
WebviewPanelOnDidChangeViewStateEvent
当 webview 面板的视图状态更改时触发的事件。
属性
webviewPanel: WebviewPanel
视图状态已更改的 Webview 面板。
WebviewPanelOptions
webview 面板的内容设置。
属性
控制是否在面板中启用查找小部件。
默认为 false
。
retainContextWhenHidden?: boolean
控制即使面板不再可见,webview 面板的内容 (iframe) 是否保留。
通常,webview 面板的 HTML 上下文在面板变为可见时创建,并在面板隐藏时销毁。具有复杂状态或 UI 的扩展程序可以设置 retainContextWhenHidden
,使编辑器保持 webview 上下文,即使 webview 移动到后台选项卡也是如此。当使用 retainContextWhenHidden
的 webview 变为隐藏时,其脚本和其他动态内容将被暂停。当面板再次变为可见时,上下文将自动恢复到其原始状态。即使启用了 retainContextWhenHidden
,您也无法向隐藏的 webview 发送消息。
retainContextWhenHidden
具有较高的内存开销,仅当您的面板的上下文无法快速保存和恢复时才应使用。
WebviewPanelSerializer<T>
恢复在 VS Code 关闭时已持久化的 webview 面板。
有两种类型的 webview 持久化
- 会话内的持久化。
- 跨会话的持久化(跨编辑器重启)。
WebviewPanelSerializer
仅在第二种情况下是必需的:跨会话持久化 webview。
会话内的持久化允许 webview 在变为隐藏时保存其状态,并在再次变为可见时从该状态恢复其内容。它完全由 webview 内容本身驱动。要保存持久化状态,请使用任何 JSON 可序列化对象调用 acquireVsCodeApi().setState()
。要再次恢复状态,请调用 getState()
。
// Within the webview
const vscode = acquireVsCodeApi();
// Get existing state
const oldState = vscode.getState() || { value: 0 };
// Update state
setState({ value: oldState.value + 1 });
WebviewPanelSerializer
将此持久化扩展到编辑器重启。当编辑器关闭时,它将保存来自所有具有序列化程序的 webview 的 setState
的状态。当 webview 在重启后首次变为可见时,此状态将传递给 deserializeWebviewPanel
。然后,扩展程序可以从此状态恢复旧的 WebviewPanel
。
方法
deserializeWebviewPanel(webviewPanel: WebviewPanel, state: T): Thenable<void>
从其序列化的 state
恢复 webview 面板。
当序列化的 webview 首次变为可见时调用。
参数 | 描述 |
---|---|
webviewPanel: WebviewPanel | 要恢复的 Webview 面板。序列化程序应取得此面板的所有权。序列化程序必须恢复 webview 的 |
state: T | 来自 webview 内容的持久化状态。 |
返回值 | 描述 |
Thenable<void> | 指示 webview 已完全恢复的 Thenable。 |
WebviewPortMapping
定义用于 webview 内部 localhost 的端口映射。
属性
目标端口。webviewPort
解析为此端口。
要在 webview 内部重新映射的 localhost 端口。
WebviewView
基于 webview 的视图。
事件
onDidChangeVisibility: Event<void>
当视图的可见性更改时触发的事件。
触发可见性更改的操作
- 视图已折叠或展开。
- 用户切换到侧边栏或面板中的不同视图组。
请注意,使用上下文菜单隐藏视图反而会释放视图并触发 onDidDispose
。
onDidDispose: Event<void>
当视图被释放时触发的事件。
当用户显式隐藏视图时(当用户在视图中单击鼠标右键并取消选中 webview 视图时,会发生这种情况),视图将被释放。
尝试在视图释放后使用它会引发异常。
属性
badge?: ViewBadge
要为此 webview 视图显示的徽章。要删除徽章,请设置为 undefined。
人类可读的字符串,在标题中以不太突出的方式呈现。
在 UI 中显示的视图标题。
视图标题最初取自扩展程序的 package.json
贡献。
标识 webview 视图的类型,例如 'hexEditor.dataView'
。
跟踪 webview 当前是否可见。
当视图在屏幕上且已展开时,视图是可见的。
webview: Webview
视图的底层 webview。
方法
show(preserveFocus?: boolean): void
在 UI 中显示视图。
如果视图已折叠,这将展开它。
参数 | 描述 |
---|---|
preserveFocus?: boolean | 当为 |
返回值 | 描述 |
void |
WebviewViewProvider
用于创建 WebviewView
元素的提供程序。
方法
resolveWebviewView(webviewView: WebviewView, context: WebviewViewResolveContext<unknown>, token: CancellationToken): void | Thenable<void>
解析 webview 视图。
当视图首次变为可见时,将调用 resolveWebviewView
。这可能发生在首次加载视图时,或者当用户隐藏然后再次显示视图时。
参数 | 描述 |
---|---|
webviewView: WebviewView | 要恢复的 Webview 视图。提供程序应取得此视图的所有权。提供程序必须设置 webview 的 |
context: WebviewViewResolveContext<unknown> | 有关正在解析的视图的其他元数据。 |
token: CancellationToken | 指示不再需要提供的视图的取消令牌。 |
返回值 | 描述 |
void | Thenable<void> | 可选的 Thenable,指示视图已完全解析。 |
WebviewViewResolveContext<T>
正在解析的 webview 视图的其他信息。
属性
来自 webview 内容的持久化状态。
为了节省资源,编辑器通常会释放不可见的 webview 文档(iframe 内容)。例如,当用户折叠视图或切换到侧边栏中的另一个顶级活动时,WebviewView
本身会保持活动状态,但 webview 的底层文档会被释放。当视图再次变为可见时,它会被重新创建。
您可以通过在 WebviewOptions
中设置 retainContextWhenHidden
来防止此行为。但是,这会增加资源使用量,应尽可能避免。相反,您可以使用持久化状态来保存 webview 的状态,以便可以根据需要快速重新创建它。
要保存持久化状态,请在 webview 内部使用任何 JSON 可序列化对象调用 acquireVsCodeApi().setState()
。要再次恢复状态,请调用 getState()
。例如
// Within the webview
const vscode = acquireVsCodeApi();
// Get existing state
const oldState = vscode.getState() || { value: 0 };
// Update state
setState({ value: oldState.value + 1 });
编辑器确保在 webview 隐藏时以及跨编辑器重启时正确保存持久化状态。
WindowState
表示窗口的状态。
属性
窗口最近是否被交互过。这将在活动时立即更改,或在用户不活动一小段时间后更改。
当前窗口是否具有焦点。
WorkspaceConfiguration
表示配置。它是以下项的合并视图:
- 默认设置
- 全局(用户)设置
- 工作区设置
- 工作区文件夹设置 - 来自请求资源所属的 工作区文件夹 之一。
- 语言设置 - 在请求的语言下定义的设置。
有效值(由 get 返回)通过以下顺序覆盖或合并值来计算:
defaultValue
(如果在package.json
中定义,否则从值的类型派生)globalValue
(如果已定义)workspaceValue
(如果已定义)workspaceFolderValue
(如果已定义)defaultLanguageValue
(如果已定义)globalLanguageValue
(如果已定义)workspaceLanguageValue
(如果已定义)workspaceFolderLanguageValue
(如果已定义)
注意: 仅合并 object
值类型,所有其他值类型都被覆盖。
示例 1:覆盖
defaultValue = 'on';
globalValue = 'relative';
workspaceFolderValue = 'off';
value = 'off';
示例 2:语言值
defaultValue = 'on';
globalValue = 'relative';
workspaceFolderValue = 'off';
globalLanguageValue = 'on';
value = 'on';
示例 3:对象值
defaultValue = { a: 1, b: 2 };
globalValue = { b: 3, c: 4 };
value = { a: 1, b: 3, c: 4 };
注意: 工作区和工作区文件夹配置包含 launch
和 tasks
设置。它们的 basename 将是节标识符的一部分。以下代码片段显示了如何从 launch.json
中检索所有配置:
// launch.json configuration
const config = workspace.getConfiguration(
'launch',
vscode.workspace.workspaceFolders[0].uri
);
// retrieve values
const values = config.get('configurations');
有关更多信息,请参阅 设置。
方法
从此配置返回一个值。
参数 | 描述 |
---|---|
section: string | 配置名称,支持点分隔名称。 |
返回值 | 描述 |
T | 值 |
get<T>(section: string, defaultValue: T): T
从此配置返回一个值。
参数 | 描述 |
---|---|
section: string | 配置名称,支持点分隔名称。 |
defaultValue: T | 当找不到值时,应该返回一个值,为 |
返回值 | 描述 |
T | 值 |
检查此配置是否具有特定值。
参数 | 描述 |
---|---|
section: string | 配置名称,支持点分隔名称。 |
返回值 | 描述 |
boolean | 如果 section 未解析为 |
inspect<T>(section: string): {defaultLanguageValue: T, defaultValue: T, globalLanguageValue: T, globalValue: T, key: string, languageIds: string[], workspaceFolderLanguageValue: T, workspaceFolderValue: T, workspaceLanguageValue: T, workspaceValue: T}
检索有关配置设置的所有信息。配置值通常由默认值、全局或安装范围的值、工作区特定的值、文件夹特定的值和语言特定的值(如果 WorkspaceConfiguration 的范围限定为语言)组成。
还提供定义给定配置设置的所有语言 ID。
注意: 配置名称必须表示配置树中的叶节点(editor.fontSize
与 editor
),否则不会返回任何结果。
参数 | 描述 |
---|---|
section: string | 配置名称,支持点分隔名称。 |
返回值 | 描述 |
{defaultLanguageValue: T, defaultValue: T, globalLanguageValue: T, globalValue: T, key: string, languageIds: string[], workspaceFolderLanguageValue: T, workspaceFolderValue: T, workspaceLanguageValue: T, workspaceValue: T} | 有关配置设置的信息或 |
update(section: string, value: any, configurationTarget?: boolean | ConfigurationTarget, overrideInLanguage?: boolean): Thenable<void>
更新配置值。更新后的配置值将被持久化。
可以在以下位置更改值:
- 全局设置:更改编辑器所有实例的值。
- 工作区设置:更改当前工作区的值(如果可用)。
- 工作区文件夹设置:更改来自请求资源所属的 工作区文件夹 之一的设置值。
- 语言设置:更改请求的 languageId 的值。
注意: 要删除配置值,请使用 undefined
,例如:config.update('somekey', undefined)
。
- 抛出 - 更新时出错
- 未注册的配置。
- 窗口配置到工作区文件夹
- 在未打开任何工作区时,配置到工作区或工作区文件夹。
- 当没有工作区文件夹设置时,配置到工作区文件夹。
- 当 WorkspaceConfiguration 的范围未限定为资源时,配置到工作区文件夹。
参数 | 描述 |
---|---|
section: string | 配置名称,支持点分隔名称。 |
value: any | 新值。 |
configurationTarget?: boolean | ConfigurationTarget | |
overrideInLanguage?: boolean | 是否在请求的 languageId 的范围内更新值。 - 如果为 |
返回值 | 描述 |
Thenable<void> |
WorkspaceEdit
工作区编辑是针对多个资源和文档的文本和文件更改的集合。
使用 applyEdit 函数来应用工作区编辑。
构造函数
new WorkspaceEdit(): WorkspaceEdit
参数 | 描述 |
---|---|
返回值 | 描述 |
WorkspaceEdit |
属性
文本或资源更改的受影响资源数。
方法
createFile(uri: Uri, options?: {contents: Uint8Array | DataTransferFile, ignoreIfExists: boolean, overwrite: boolean}, metadata?: WorkspaceEditEntryMetadata): void
创建常规文件。
参数 | 描述 |
---|---|
uri: Uri | 新文件的 URI。 |
options?: {contents: Uint8Array | DataTransferFile, ignoreIfExists: boolean, overwrite: boolean} | 定义是否应覆盖现有文件或忽略现有文件。当 |
metadata?: WorkspaceEditEntryMetadata | 条目的可选元数据。 |
返回值 | 描述 |
void |
delete(uri: Uri, range: Range, metadata?: WorkspaceEditEntryMetadata): void
删除给定范围的文本。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
range: Range | 一个范围。 |
metadata?: WorkspaceEditEntryMetadata | 条目的可选元数据。 |
返回值 | 描述 |
void |
deleteFile(uri: Uri, options?: {ignoreIfNotExists: boolean, recursive: boolean}, metadata?: WorkspaceEditEntryMetadata): void
删除文件或文件夹。
参数 | 描述 |
---|---|
uri: Uri | 要删除的文件的 URI。 |
options?: {ignoreIfNotExists: boolean, recursive: boolean} | |
metadata?: WorkspaceEditEntryMetadata | 条目的可选元数据。 |
返回值 | 描述 |
void |
entries(): Array<[Uri, TextEdit[]]>
has(uri: Uri): boolean
检查资源是否存在文本编辑。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
返回值 | 描述 |
boolean | 如果给定资源将由此编辑修改,则返回 |
insert(uri: Uri, position: Position, newText: string, metadata?: WorkspaceEditEntryMetadata): void
在给定位置插入给定文本。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
position: Position | 一个位置。 |
newText: string | 一个字符串。 |
metadata?: WorkspaceEditEntryMetadata | 条目的可选元数据。 |
返回值 | 描述 |
void |
renameFile(oldUri: Uri, newUri: Uri, options?: {ignoreIfExists: boolean, overwrite: boolean}, metadata?: WorkspaceEditEntryMetadata): void
重命名文件或文件夹。
参数 | 描述 |
---|---|
oldUri: Uri | 现有文件。 |
newUri: Uri | 新位置。 |
options?: {ignoreIfExists: boolean, overwrite: boolean} | 定义是否应覆盖或忽略现有文件。当同时设置 overwrite 和 ignoreIfExists 时,overwrite 优先。 |
metadata?: WorkspaceEditEntryMetadata | 条目的可选元数据。 |
返回值 | 描述 |
void |
replace(uri: Uri, range: Range, newText: string, metadata?: WorkspaceEditEntryMetadata): void
对于给定资源,用给定文本替换给定范围。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
range: Range | 一个范围。 |
newText: string | 一个字符串。 |
metadata?: WorkspaceEditEntryMetadata | 条目的可选元数据。 |
返回值 | 描述 |
void |
set(uri: Uri, edits: ReadonlyArray<TextEdit | SnippetTextEdit>): void
为资源设置(和替换)文本编辑或代码片段编辑。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
edits: ReadonlyArray<TextEdit | SnippetTextEdit> | 编辑数组。 |
返回值 | 描述 |
void |
set(uri: Uri, edits: ReadonlyArray<[TextEdit | SnippetTextEdit, WorkspaceEditEntryMetadata]>): void
为资源设置(和替换)带有元数据的文本编辑或代码片段编辑。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
edits: ReadonlyArray<[TextEdit | SnippetTextEdit, WorkspaceEditEntryMetadata]> | 编辑数组。 |
返回值 | 描述 |
void |
set(uri: Uri, edits: readonly NotebookEdit[]): void
为资源设置(和替换)笔记本编辑。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
edits: readonly NotebookEdit[] | 编辑数组。 |
返回值 | 描述 |
void |
set(uri: Uri, edits: ReadonlyArray<[NotebookEdit, WorkspaceEditEntryMetadata]>): void
为资源设置(和替换)带有元数据的笔记本编辑。
参数 | 描述 |
---|---|
uri: Uri | 资源标识符。 |
edits: ReadonlyArray<[NotebookEdit, WorkspaceEditEntryMetadata]> | 编辑数组。 |
返回值 | 描述 |
void |
WorkspaceEditEntryMetadata
工作区编辑条目的附加数据。支持标记条目和将条目标记为需要用户确认。编辑器将具有相同标签的编辑分组到树节点中,例如,所有标记为“字符串中的更改”的编辑将是一个树节点。
属性
人类可读的字符串,在同一行上以较不突出的方式呈现。
iconPath?: IconPath
编辑的图标路径或 ThemeIcon。
人类可读的字符串,以突出的方式呈现。
指示是否需要用户确认的标志。
WorkspaceEditMetadata
关于工作区编辑的附加数据。
属性
向编辑器发出此编辑是重构的信号。
WorkspaceFolder
工作区文件夹是编辑器打开的可能多个根目录之一。所有工作区文件夹都是相等的,这意味着没有活动或主工作区文件夹的概念。
属性
此工作区文件夹的序号。
此工作区文件夹的名称。默认为其 uri 路径 的基本名称
uri: Uri
此工作区文件夹的关联 uri。
注意: 选择 Uri 类型是故意的,这样编辑器的未来版本可以支持不存储在本地磁盘上的工作区文件夹,例如 ftp://server/workspaces/foo
。
WorkspaceFolderPickOptions
用于配置 工作区文件夹 选择 UI 行为的选项。
属性
设置为 true
以在焦点移动到编辑器的另一部分或另一个窗口时保持选择器打开。此设置在 iPad 上被忽略,并且始终为 false。
一个可选字符串,在输入框中显示为占位符,以指导用户选择什么。
WorkspaceFoldersChangeEvent
描述 工作区文件夹 集合更改的事件。
属性
added: readonly WorkspaceFolder[]
已添加的工作区文件夹。
removed: readonly WorkspaceFolder[]
已移除的工作区文件夹。
WorkspaceSymbolProvider<T>
工作区符号提供程序接口定义了扩展与 符号搜索 功能之间的约定。
方法
provideWorkspaceSymbols(query: string, token: CancellationToken): ProviderResult<T[]>
在整个项目中搜索与给定查询字符串匹配的符号。
query
参数应以宽松的方式解释,因为编辑器将在结果上应用其自己的突出显示和评分。一个好的经验法则是进行不区分大小写的匹配,并简单地检查 query 的字符是否按顺序出现在候选符号中。不要使用前缀、子字符串或类似的严格匹配。
为了提高性能,实现者可以实现 resolveWorkspaceSymbol
,然后提供带有部分 位置 对象的符号,而无需定义 range
。然后,编辑器将仅针对选定的符号调用 resolveWorkspaceSymbol
,例如,在打开工作区符号时。
参数 | 描述 |
---|---|
authority: string | 查询字符串,可以是空字符串,在这种情况下,应返回所有符号。 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T[]> | 文档高亮的数组或一个可解析为此的 thenable 对象。 缺少结果可以通过返回 |
resolveWorkspaceSymbol(symbol: T, token: CancellationToken): ProviderResult<T>
给定一个符号,填充其 位置。每当在 UI 中选择符号时,都会调用此方法。提供程序可以实现此方法,并从 provideWorkspaceSymbols 返回不完整的符号,这通常有助于提高性能。
参数 | 描述 |
---|---|
symbol: T | 要解析的符号。保证是先前调用 |
token: CancellationToken | 取消令牌。 |
返回值 | 描述 |
ProviderResult<T> | 已解析的符号或解析为该符号的 thenable。当没有返回结果时,将使用给定的 |
API 模式
这些是我们在 VS Code API 中使用的一些常见模式。
Promises(承诺)
VS Code API 使用 promises 表示异步操作。从扩展程序中,可以返回任何类型的 promise,例如 ES6、WinJS、A+ 等。
API 中的 Thenable
类型表示独立于特定 promise 库。Thenable
表示共同的最小公分母,即 then 方法。
在大多数情况下,promise 的使用是可选的,当 VS Code 调用扩展程序时,它可以处理结果类型以及结果类型的 Thenable
。当 promise 的使用是可选的时,API 通过返回 or
类型来指示这一点。
provideNumber(): number | Thenable<number>
Cancellation Tokens(取消令牌)
通常,操作在易失状态下启动,这种状态在操作完成之前会发生变化。例如,智能感知计算开始,用户继续键入,导致该操作的结果过时。
暴露于此类行为的 API 将传递一个 CancellationToken
,您可以在其上检查取消(isCancellationRequested
)或在发生取消时获得通知(onCancellationRequested
)。取消令牌通常是函数调用的最后一个参数,并且是可选的。
Disposables(可释放对象)
VS Code API 对从 VS Code 获取的资源使用 dispose 模式。这适用于事件监听、命令、与 UI 交互以及各种语言贡献。
例如,setStatusBarMessage(value: string)
函数返回一个 Disposable
,调用 dispose
后,它会再次删除消息。
事件
VS Code API 中的事件作为函数公开,您可以调用这些函数并传入侦听器函数以进行订阅。订阅调用返回一个 Disposable
,在释放时会删除事件侦听器。
var listener = function(event) {
console.log('It happened', event);
};
// start listening
var subscription = fsWatcher.onDidDelete(listener);
// do more stuff
subscription.dispose(); // stop listening
事件的名称遵循 on[Will|Did]VerbNoun?
模式。名称表示事件是即将发生(onWill) 还是已经发生(onDid),发生了什么(verb),以及上下文(noun),除非从上下文中显而易见。
VS Code API 的一个示例是 window.onDidChangeActiveTextEditor
,这是一个在活动文本编辑器(noun) 已(onDid)更改(verb)时触发的事件。
Strict null(严格空值)
VS Code API 在适当的地方使用 undefined
和 null
TypeScript 类型来支持 严格的 null 检查。
身份验证的命名空间。