💻 欢迎参加 6 月 3 日 MS Build 上的 VS Code 直播活动。

自定义编辑器 API

自定义编辑器允许扩展创建完全可定制的读/写编辑器，用于代替 VS Code 标准文本编辑器来处理特定类型的资源。它们具有广泛的应用场景，例如：

  • 直接在 VS Code 中预览着色器或 3D 模型等资源。
  • 为 Markdown 或 XAML 等语言创建所见即所得 (WYSIWYG) 编辑器。
  • 为 CSV、JSON 或 XML 等数据文件提供替代的可视化渲染。
  • 为二进制或文本文件构建完全可定制的编辑体验。

本文档概述了自定义编辑器 API 和实现自定义编辑器的基础知识。我们将研究两种类型的自定义编辑器及其区别，以及哪一种适合您的用例。然后，针对每种自定义编辑器类型，我们将涵盖构建表现良好的自定义编辑器的基础知识。

尽管自定义编辑器是一个强大的新扩展点，但实现一个基本的自定义编辑器实际上并不难！不过，如果您正在开发第一个 VS Code 扩展，您可能需要考虑在熟悉 VS Code API 的基础知识之后再深入研究自定义编辑器。自定义编辑器构建在许多 VS Code 概念之上（例如网页视图 (Webviews) 和文本文档），因此如果您同时学习所有这些新概念，可能会感到不知所措。

但是，如果您已经准备好，并且正在构思要构建哪些炫酷的自定义编辑器，那么让我们开始吧！请务必下载自定义编辑器扩展示例，以便您可以跟随文档进行学习，并了解自定义编辑器 API 是如何组合在一起的。

VS Code API 使用

自定义编辑器 API 基础

自定义编辑器是一种替代视图，用于代替 VS Code 的标准文本编辑器来显示特定资源。自定义编辑器由两部分组成：用户交互的视图，以及您的扩展用于与底层资源交互的文档模型。

自定义编辑器的视图侧是使用网页视图 (Webview) 实现的。这让您可以使用标准的 HTML、CSS 和 JavaScript 来构建自定义编辑器的用户界面。网页视图不能直接访问 VS Code API，但它们可以通过来回传递消息与扩展进行通信。请查阅我们的网页视图文档，以获取有关网页视图及使用它们的最佳实践的更多信息。

自定义编辑器的另一部分是文档模型。此模型是您的扩展理解其正在处理的资源（文件）的方式。CustomTextEditorProvider 使用 VS Code 的标准 TextDocument 作为其文档模型，对文件的所有更改都使用 VS Code 的标准文本编辑 API 来表示。另一方面，CustomReadonlyEditorProvider 和 CustomEditorProvider 允许您提供自己的文档模型，这使它们可以用于非文本文件格式。

自定义编辑器每个资源对应一个文档模型，但该文档可能有多个编辑器实例（视图）。例如，想象一下您打开了一个带有 CustomTextEditorProvider 的文件，然后运行了视图：拆分编辑器命令。在这种情况下，仍然只有一个 TextDocument，因为工作区中仍然只有一个资源副本，但现在该资源有两个网页视图。

CustomEditor 与 CustomTextEditor

自定义编辑器分为两类：自定义文本编辑器和自定义编辑器。它们之间的主要区别在于它们如何定义其文档模型。

CustomTextEditorProvider 使用 VS Code 的标准 TextDocument 作为其数据模型。您可以将 CustomTextEditor 用于任何基于文本的文件类型。CustomTextEditor 的实现要容易得多，因为 VS Code 已经知道如何处理文本文件，因此可以实现保存和备份文件以进行热退出的操作。

另一方面，对于 CustomEditorProvider，您的扩展会引入自己的文档模型。这意味着您可以将 CustomEditor 用于图像等二进制格式，但也意味着您的扩展需要承担更多责任，包括实现保存和备份。如果您的自定义编辑器是只读的（例如用于预览的自定义编辑器），您可以跳过大部分复杂性。

在试图决定使用哪种类型的自定义编辑器时，决策通常很简单：如果您正在处理基于文本的文件格式，请使用 CustomTextEditorProvider；对于二进制文件格式，请使用 CustomEditorProvider。

贡献点

customEditors 贡献点是您的扩展告诉 VS Code 其提供的自定义编辑器的方式。例如，VS Code 需要知道您的自定义编辑器处理哪些类型的文件，以及如何在任何 UI 中识别您的自定义编辑器。

这是自定义编辑器扩展示例的一个基本 customEditor 贡献：

"contributes": {
  "customEditors": [
    {
      "viewType": "catEdit.catScratch",
      "displayName": "Cat Scratch",
      "selector": [
        {
          "filenamePattern": "*.cscratch"
        }
      ],
      "priority": "default"
    }
  ]
}

customEditors 是一个数组，因此您的扩展可以贡献多个自定义编辑器。让我们拆解自定义编辑器条目本身：

  • viewType - 自定义编辑器的唯一标识符。

    这是 VS Code 将 package.json 中的自定义编辑器贡献与代码中自定义编辑器实现相关联的方式。这在所有扩展中必须是唯一的，因此请确保使用对于您的扩展唯一的名称，例如 "viewType": "myAmazingExtension.svgPreview"，而不是通用的 "viewType": "preview"。

  • displayName - 在 VS Code UI 中标识自定义编辑器的名称。

    显示名称会在 VS Code UI（如视图：重新打开方式下拉菜单）中向用户展示。

  • selector - 指定自定义编辑器对哪些文件有效。

    selector 是一个或多个全局匹配模式 (glob patterns) 组成的数组。这些匹配模式将与文件名进行匹配，以确定自定义编辑器是否可以用于它们。诸如 *.png 之类的 filenamePattern 将为所有 PNG 文件启用该自定义编辑器。

    您还可以创建更具体的模式来匹配文件或目录名，例如 **/translations/*.json。

  • priority - （可选）指定何时使用自定义编辑器。

    priority 控制打开资源时何时使用自定义编辑器。可能的值为：

    • "default" - 尝试为每个匹配自定义编辑器 selector 的文件使用自定义编辑器。如果给定文件有多个自定义编辑器，用户将不得不选择他们想要使用的编辑器。
    • "option" - 默认不使用该自定义编辑器，但允许用户切换到它或将其配置为默认编辑器。

自定义编辑器激活

当用户打开您的自定义编辑器之一时，VS Code 会触发 onCustomEditor:VIEW_TYPE 激活事件。在激活期间，您的扩展必须调用 registerCustomEditorProvider 来注册具有预期 viewType 的自定义编辑器。

需要注意的是，onCustomEditor 仅在 VS Code 需要创建自定义编辑器实例时才会被调用。如果 VS Code 只是向用户显示有关可用自定义编辑器的一些信息（例如使用视图：重新打开方式命令），则不会激活您的扩展。

自定义文本编辑器

自定义文本编辑器允许您为文本文件创建自定义编辑器。这可以是任何内容，从纯非结构化文本到 CSV、JSON 或 XML。自定义文本编辑器使用 VS Code 的标准 TextDocument 作为其文档模型。

自定义编辑器扩展示例包含一个用于 cat scratch 文件的简单自定义文本编辑器示例（这些文件只是以 .cscratch 文件扩展名结尾的 JSON 文件）。让我们看看实现自定义文本编辑器的一些重要部分。

自定义文本编辑器生命周期

VS Code 处理自定义文本编辑器视图组件（网页视图）和模型组件 (TextDocument) 的生命周期。当需要创建新的自定义编辑器实例时，VS Code 会调用您的扩展；当用户关闭标签页时，它会清理编辑器实例和文档模型。

为了理解这一切在实践中是如何工作的，让我们从扩展的角度梳理一下用户打开自定义文本编辑器时会发生什么，以及用户关闭自定义文本编辑器时会发生什么。

打开自定义文本编辑器

使用自定义编辑器扩展示例，当用户首次打开 .cscratch 文件时会发生以下情况：

  1. VS Code 触发 onCustomEditor:catCustoms.catScratch 激活事件。

    如果我们的扩展尚未激活，它将激活。在激活期间，我们的扩展必须确保通过调用 registerCustomEditorProvider 为 catCustoms.catScratch 注册一个 CustomTextEditorProvider。

  2. VS Code 然后在为 catCustoms.catScratch 注册的 CustomTextEditorProvider 上调用 resolveCustomTextEditor。

    此方法接收正在打开的资源的 TextDocument 和一个 WebviewPanel。扩展必须为该网页视图面板填充初始 HTML 内容。

一旦 resolveCustomTextEditor 返回，我们的自定义编辑器就会显示给用户。网页视图中绘制的内容完全由我们的扩展决定。

每次打开自定义编辑器时，即使拆分自定义编辑器，也会发生同样的流程。每个自定义编辑器实例都有自己的 WebviewPanel，尽管如果是同一个资源，多个自定义文本编辑器将共享同一个 TextDocument。记住：将 TextDocument 视为资源的模型，而网页视图面板是该模型的视图。

关闭自定义文本编辑器

当用户关闭自定义文本编辑器时，VS Code 会在 WebviewPanel 上触发 WebviewPanel.onDidDispose 事件。此时，您的扩展应该清理与该编辑器关联的任何资源（事件订阅、文件监视器等）。

当给定资源的最后一个自定义编辑器关闭时，如果该资源没有其他编辑器在使用，且没有其他扩展持有它，则该资源的 TextDocument 也将被释放。您可以检查 TextDocument.isClosed 属性以查看 TextDocument 是否已关闭。一旦 TextDocument 关闭，使用自定义编辑器打开同一资源将导致打开一个新的 TextDocument。

与 TextDocument 同步更改

由于自定义文本编辑器使用 TextDocument 作为其文档模型，因此它们负责在自定义编辑器中发生编辑时更新 TextDocument，以及在 TextDocument 发生更改时更新自身。

从网页视图到 TextDocument

自定义文本编辑器中的编辑可以采取多种不同的形式——点击按钮、更改某些文本、拖动某些项目。每当用户在自定义文本编辑器内编辑文件本身时，扩展必须更新 TextDocument。以下是 cat scratch 扩展实现此操作的方式：

  1. 用户点击网页视图中的 Add scratch 按钮。这会从网页视图向扩展发送一条消息。

  2. 扩展接收消息。然后它更新其内部文档模型（在 cat scratch 示例中，它只是向 JSON 添加一个新条目）。

  3. 扩展创建一个将更新后的 JSON 写入文档的 WorkspaceEdit。此编辑使用 vscode.workspace.applyEdit 应用。

尽量使您的工作区编辑保持更新文档所需的最小更改。还要记住，如果您正在处理 JSON 等语言，您的扩展应该尽量遵守用户现有的格式约定（空格 vs 制表符、缩进大小等）。

从 TextDocument 到网页视图

当 TextDocument 发生更改时，您的扩展还需要确保其网页视图反映了文档的新状态。文本文档可以通过用户操作（如撤消、重做或还原文件）、其他使用 WorkspaceEdit 的扩展，或者用户在 VS Code 的默认文本编辑器中打开文件来更改。以下是 cat scratch 扩展实现此操作的方式：

  1. 在扩展中，我们订阅 vscode.workspace.onDidChangeTextDocument 事件。此事件针对 TextDocument 的每一次更改都会触发（包括我们自定义编辑器所做的更改！）。

  2. 当文档发生我们有编辑器处理的更改时，我们会向网页视图发送一条包含其新文档状态的消息。然后，网页视图更新自身以呈现更新后的文档。

请务必记住，自定义编辑器触发的任何文件编辑都会导致 onDidChangeTextDocument 触发。确保您的扩展不会陷入更新循环，即用户在网页视图中进行编辑，触发了 onDidChangeTextDocument，导致网页视图更新，导致网页视图在您的扩展上触发另一次更新，进而触发 onDidChangeTextDocument，依此类推。

还要记住，如果您正在处理 JSON 或 XML 等结构化语言，文档可能并不总是处于有效状态。您的扩展必须能够妥善处理错误，或者向用户显示错误消息，以便他们了解出了什么问题以及如何修复它。

最后，如果更新您的网页视图非常耗时，请考虑对网页视图的更新进行防抖 (debouncing) 处理。

自定义编辑器

CustomEditorProvider 和 CustomReadonlyEditorProvider 允许您为二进制文件格式创建自定义编辑器。此 API 使您可以完全控制文件如何显示给用户、如何对其进行编辑，并允许您的扩展挂钩到 save 和其他文件操作中。同样，如果您正在为基于文本的文件格式构建编辑器，请强烈考虑改用 CustomTextEditor，因为它们的实现要简单得多。

自定义编辑器扩展示例包含一个用于 paw draw 文件的简单自定义二进制编辑器示例（这些文件只是以 .pawdraw 文件扩展名结尾的 jpeg 文件）。让我们看看构建二进制文件的自定义编辑器需要什么。

CustomDocument

对于自定义编辑器，您的扩展负责使用 CustomDocument 接口实现其自己的文档模型。这使您的扩展可以自由地在 CustomDocument 上存储与您的自定义编辑器交互所需的任何数据，但也意味着您的扩展必须实现基本的文档操作，例如保存和备份文件数据以进行热退出。

每个打开的文件对应一个 CustomDocument。用户可以为一个资源打开多个编辑器（例如通过拆分当前的自定义编辑器），但所有这些编辑器都将由同一个 CustomDocument 提供支持。

自定义编辑器生命周期

supportsMultipleEditorsPerDocument

默认情况下，VS Code 只允许每个自定义文档有一个编辑器。这种限制使得正确实现自定义编辑器变得更容易，因为您不必担心将多个自定义编辑器实例彼此同步。

但是，如果您的扩展可以支持，我们建议在注册自定义编辑器时设置 supportsMultipleEditorsPerDocument: true，以便可以为同一文档打开多个编辑器实例。这将使您的自定义编辑器表现得更像 VS Code 的普通文本编辑器。

打开自定义编辑器：当用户打开与 customEditor 贡献点匹配的文件时，VS Code 会触发 onCustomEditor 激活事件，然后调用为提供的 viewType 注册的提供程序。CustomEditorProvider 扮演两个角色：为自定义编辑器提供文档，然后提供编辑器本身。以下是 自定义编辑器扩展示例中 catCustoms.pawDraw 编辑器所发生事件的有序列表：

  1. VS Code 触发 onCustomEditor:catCustoms.pawDraw 激活事件。

    如果我们的扩展尚未激活，它将激活。我们还必须确保我们的扩展在激活期间为 catCustoms.pawDraw 注册了 CustomReadonlyEditorProvider 或 CustomEditorProvider。

  2. VS Code 调用为 catCustoms.pawDraw 编辑器注册的 CustomReadonlyEditorProvider 或 CustomEditorProvider 上的 openCustomDocument。

    在这里，我们的扩展获得了一个资源 URI，并且必须为该资源返回一个新的 CustomDocument。这是我们的扩展应该为该资源创建其文档内部模型的时候。这可能涉及从磁盘读取和解析初始资源状态或初始化我们的新 CustomDocument。

    我们的扩展可以通过创建一个实现 CustomDocument 的新类来定义此模型。请记住，此初始化阶段完全由扩展决定；VS Code 不关心扩展在 CustomDocument 上存储的任何额外信息。

  3. VS Code 使用第 2 步中的 CustomDocument 和一个新的 WebviewPanel 调用 resolveCustomEditor。

    在这里，我们的扩展必须填充自定义编辑器的初始 HTML。如果需要，我们还可以持有对 WebviewPanel 的引用，以便以后可以引用它，例如在命令内部。

一旦 resolveCustomEditor 返回，我们的自定义编辑器就会显示给用户。

如果用户在另一个编辑器组中使用我们的自定义编辑器打开同一个资源（例如通过拆分第一个编辑器），扩展的工作就会简化。在这种情况下，VS Code 只是使用我们在打开第一个编辑器时创建的同一个 CustomDocument 调用 resolveCustomEditor。

关闭自定义编辑器

假设我们为同一个资源打开了两个自定义编辑器实例。当用户关闭这些编辑器时，VS Code 会向我们的扩展发送信号，以便它可以清理与该编辑器关联的任何资源。

当第一个编辑器实例关闭时，VS Code 会在已关闭编辑器的 WebviewPanel 上触发 WebviewPanel.onDidDispose 事件。此时，我们的扩展必须清理与该特定编辑器实例关联的任何资源。

当第二个编辑器关闭时，VS Code 再次触发 WebviewPanel.onDidDispose。但是现在我们也关闭了与 CustomDocument 关联的所有编辑器。当 CustomDocument 不再有任何编辑器时，VS Code 会调用它上面的 CustomDocument.dispose。我们扩展对 dispose 的实现必须清理与文档关联的任何资源。

如果用户随后使用我们的自定义编辑器重新打开同一个资源，我们将带着一个新的 CustomDocument 重新经历整个 openCustomDocument、resolveCustomEditor 流程。

只读自定义编辑器

以下许多部分仅适用于支持编辑的自定义编辑器，虽然听起来可能自相矛盾，但许多自定义编辑器根本不需要编辑功能。例如，考虑图像预览，或者内存转储的可视化渲染。两者都可以使用自定义编辑器实现，但都不需要可编辑。这就是 CustomReadonlyEditorProvider 的用武之地。

CustomReadonlyEditorProvider 允许您创建不支持编辑的自定义编辑器。它们仍然可以是交互式的，但不支持撤消和保存等操作。与完全可编辑的自定义编辑器相比，实现只读自定义编辑器也要简单得多。

可编辑自定义编辑器基础

可编辑的自定义编辑器允许您挂钩到标准的 VS Code 操作，例如撤消和重做、保存以及热退出。这使得可编辑的自定义编辑器非常强大，但也意味着正确实现一个编辑器比实现可编辑的自定义文本编辑器或只读的自定义编辑器要复杂得多。

可编辑的自定义编辑器由 CustomEditorProvider 实现。此接口扩展了 CustomReadonlyEditorProvider，因此您将必须实现基本操作（如 openCustomDocument 和 resolveCustomEditor），以及一组编辑特定的操作。让我们看看 CustomEditorProvider 中编辑特定的部分。

编辑 (Edits)

对可编辑自定义文档的更改通过编辑来表示。编辑可以是任何内容，从文本更改、图像旋转到列表重排序。VS Code 将编辑的具体作用完全留给您的扩展，但 VS Code 确实需要知道何时发生编辑。编辑是 VS Code 将文档标记为“脏”状态（即已更改）的方式，这反过来又启用了自动保存和备份。

每当用户在您的自定义编辑器的任何网页视图中进行编辑时，您的扩展都必须从其 CustomEditorProvider 触发 onDidChangeCustomDocument 事件。根据您的自定义编辑器实现，onDidChangeCustomDocument 事件可以触发两种事件类型：CustomDocumentContentChangeEvent 和 CustomDocumentEditEvent。

CustomDocumentContentChangeEvent

CustomDocumentContentChangeEvent 是一种极简的编辑。它的唯一功能是告诉 VS Code 文档已被编辑。

当扩展从 onDidChangeCustomDocument 触发 CustomDocumentContentChangeEvent 时，VS Code 会将关联的文档标记为脏状态。此时，文档变为非脏状态的唯一方法是用户保存或还原它。使用 CustomDocumentContentChangeEvent 的自定义编辑器不支持撤消/重做。

CustomDocumentEditEvent

CustomDocumentEditEvent 是一种更复杂的编辑，允许撤消/重做。您应该始终尝试使用 CustomDocumentEditEvent 实现您的自定义编辑器，仅在无法实现撤消/重做时才回退到使用 CustomDocumentContentChangeEvent。

CustomDocumentEditEvent 具有以下字段：

  • document — 编辑所针对的 CustomDocument。
  • label — 描述所做编辑类型的可选文本（例如：“裁剪”、“插入”……）
  • undo — 需要撤消编辑时由 VS Code 调用的函数。
  • redo — 需要重做编辑时由 VS Code 调用的函数。

当扩展从 onDidChangeCustomDocument 触发 CustomDocumentEditEvent 时，VS Code 会将关联的文档标记为脏状态。为了使文档不再处于脏状态，用户可以保存或还原文档，或者撤消/重做回文档上次保存的状态。

编辑器上的 undo 和 redo 方法在需要撤消或重新应用特定编辑时由 VS Code 调用。VS Code 维护一个内部编辑堆栈，因此如果您的扩展使用三个编辑（我们称之为 a、b、c）触发了 onDidChangeCustomDocument：

onDidChangeCustomDocument(a);
onDidChangeCustomDocument(b);
onDidChangeCustomDocument(c);

以下用户操作序列会导致这些调用：

undo — c.undo()
undo — b.undo()
redo — b.redo()
redo — c.redo()
redo — no op, no more edits

为了实现撤消/重做，您的扩展必须更新其关联自定义文档的内部状态，并更新所有关联的网页视图，以便它们反映文档的新状态。请记住，单个资源可能有多个网页视图。这些网页视图必须始终显示相同的文档数据。例如，图像编辑器的多个实例必须始终显示相同的像素数据，但可以允许每个编辑器实例拥有自己的缩放级别和 UI 状态。

保存

当用户保存自定义编辑器时，您的扩展负责将当前状态下的保存资源写入磁盘。您的自定义编辑器如何执行此操作在很大程度上取决于您的扩展的 CustomDocument 类型以及您的扩展如何在内部跟踪编辑。

保存的第一步是获取要写入磁盘的数据流。常见的做法包括：

  • 跟踪资源的状态，以便可以快速序列化。

    例如，一个基本的图像编辑器可能会维护一个像素数据缓冲区。

  • 重放自上次保存以来的编辑以生成新文件。

    例如，一个更高效的图像编辑器可能会跟踪自上次保存以来的编辑，如 crop（裁剪）、rotate（旋转）、scale（缩放）。保存时，它会将这些编辑应用于文件的上次保存状态以生成新文件。

  • 请求自定义编辑器的 WebviewPanel 以获取要保存的文件数据。

    但请记住，自定义编辑器即使在不可见时也可以保存。因此，建议您的扩展对 save 的实现不依赖于 WebviewPanel。如果这不可能，您可以使用 WebviewPanelOptions.retainContextWhenHidden 设置，以便即使在隐藏时网页视图也保持活跃。retainContextWhenHidden 具有显著的内存开销，因此请谨慎使用。

获取资源数据后，您通常应该使用 工作区 FS API 将其写入磁盘。FS API 接收 UInt8Array 数据，并且可以写入二进制和基于文本的文件。对于二进制文件数据，只需将二进制数据放入 UInt8Array 即可。对于文本文件数据，请使用 Buffer 将字符串转换为 UInt8Array。

const writeData = Buffer.from('my text data', 'utf8');
vscode.workspace.fs.writeFile(fileUri, writeData);

后续步骤

如果您想了解更多关于 VS Code 可扩展性的信息，请尝试以下主题：

5/28/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.