从零开始编写VSCODE插件3-配置篇

风风吹
553 阅读5分钟

发布内容配置（即VS Code为插件扩展提供的配置项）是pacakge.json插件清单的contributes字段，你可以在其中注册各种配置项扩展VS Code的能力。下面是目前可用的配置项列表：

由于可配置项非常多，下面只介绍常用的configuration和configurationDefaults。

contributes.configuration

在configuration中配置的内容会暴露给用户，用户可以从“用户设置”和“工作区设置”中修改你暴露的选项。 configuration是JSON格式的键值对，用户会在修改设置时获得对应的提示和更好的体验。 你可以用vscode.workspace.getConfiguration('myExtension')读取配置值。

示例

{
  "contributes": {
    "configuration": {
      "title": "TypeScript",
      "properties": {
        "typescript.useCodeSnippetsOnMethodSuggest": {
          "type": "boolean",
          "default": false,
          "description": "Complete functions with their parameter signature."
        },
        "typescript.tsdk": {
          "type": ["string", "null"],
          "default": null,
          "description": "Specifies the folder path containing the tsserver and lib*.d.ts files to use."
        }
      }
    }
  }
}

configuration

配置语法

您的配置项既用于在 JSON 编辑器中编辑设置时提供智能提示，也用于定义它们在设置 UI 中的显示方式。

image.png

标题

类别的标题 1️⃣ 是用于该类别的标题。

{
  "configuration": {
    "title": "GitMagic"
  }
}

属性

在设置 UI 中，您的配置键将用于命名空间和构建标题。尽管一个扩展可以包含多个设置类别，但扩展的每个设置仍必须拥有自己的唯一键。键中的大写字母用于指示单词间的分隔。例如，如果您的键是 gitMagic.blame.dateFormat，该设置的生成标题将如下所示：

Blame: Date Format

条目将根据您键中建立的层次结构进行分组。因此，例如，这些条目

gitMagic.blame.dateFormat
gitMagic.blame.format
gitMagic.blame.heatMap.enabled
gitMagic.blame.heatMap.location

将像这样出现在一个单独的组中：

Blame: Date Format

Blame: Format

Blame › Heat Map: Enabled

Blame › Heat Map: Location

配置属性语法

配置键是使用 JSON Schema 的超集来定义的。

description / markdownDescription

您的描述 3️⃣ 出现在标题之后和输入字段之前，布尔值除外，在布尔值中，描述用作复选框的标签。6️⃣

{
  "gitMagic.blame.heatMap.enabled": {
    "description": "Specifies whether to provide a heatmap indicator in the gutter blame annotations"
  }
}

类型

数字类型 4️⃣ 、字符串类型 5️⃣ 、布尔类型 6️⃣ 的条目可以直接在设置 UI 中编辑。

{
  "gitMagic.views.pageItemLimit": {
    "type": "number",
    "default": 20,
    "markdownDescription": "Specifies the number of items to show in each page when paginating a view list. Use 0 to specify no limit"
  }
}

如果字符串设置在配置项上设置了 "editPresentation": "multilineText"，则可以使用多行文本输入来渲染。

对于布尔条目，描述（或 markdownDescription）将用作复选框的标签

{
  "gitMagic.blame.compact": {
    "type": "boolean",
    "description": "Specifies whether to compact (deduplicate) matching adjacent gutter blame annotations"
  }
}

一些对象和数组类型的设置将在设置 UI 中渲染。简单的数字、字符串或布尔值数组将被渲染为可编辑列表。具有类型为字符串、数字、整数和/或布尔值的属性的对象将被渲染为可编辑的键值网格。对象设置还应该将 additionalProperties 设置为 false，或者设置为具有适当类型属性的对象，以在 UI 中渲染。

如果对象或数组类型的设置还可以包含其他类型，如嵌套对象、数组或 null，则该值不会在设置 UI 中渲染，只能通过直接编辑 JSON 来修改。用户将看到一个链接到 settings.json 的编辑，如上面的截图所示。8️⃣

顺序

类别及其内部的设置都可以采用整数顺序类型属性，这提供了一个参考，说明它们相对于其他类别和/或设置应该如何排序。

如果两个类别具有顺序属性，顺序号较低的类别排在前面。如果一个类别没有给定顺序属性，它将出现在那些被赋予该属性的类别之后。

如果同一类别内的两个设置具有顺序属性，顺序号较低的设置排在前面。如果该类别内的另一个设置没有给定顺序属性，它将出现在该类别中被赋予该属性的设置之后。

如果两个类别具有相同的顺序属性值，或者同一类别内的两个设置具有相同的顺序属性值，则它们将在设置 UI 中按字母顺序递增排序。

枚举 / 枚举描述 / 枚举项标签

如果您在 enum 7️⃣ 属性下提供了一个项目数组，设置 UI 将渲染一个下拉菜单。

image.png

您还可以提供一个 enumDescriptions 属性，它提供了在下拉菜单底部渲染的描述性文本：

{
  "gitMagic.blame.heatMap.location": {
    "type": "string",
    "default": "right",
    "enum": ["left", "right"],
    "enumDescriptions": [
      "Adds a heatmap indicator on the left edge of the gutter blame annotations",
      "Adds a heatmap indicator on the right edge of the gutter blame annotations"
    ]
  }
}

您还可以使用 markdownEnumDescriptions，您的描述将以 Markdown 的形式渲染。

要自定义下拉选项，您可以使用 enumItemLabels。workbench.iconTheme 设置同时使用了 enumDescriptions 和 enumItemLabels。在下面的截图中，悬停的选项的项目标签为“None”，枚举描述为“No file icons”，枚举值为 null。

image.png

其他 JSON Schema 属性

您可以使用任何验证 JSON Schema 属性来描述配置值的其他约束：

  • default 用于定义属性的默认值
  • minimum 和 maximum 用于限制数字值
  • maxLength, minLength 用于限制字符串长度
  • pattern 用于将字符串限制为给定的正则表达式
  • patternErrorMessage 用于在模式不匹配时给出定制的错误信息
  • format 用于将字符串限制为众所周知的格式，如 date、time、ipv4、email 和 uri
  • maxItems, minItems 用于限制数组长度
  • editPresentation 用于控制在设置编辑器中为字符串设置渲染单行输入框还是多行文本区

contributes.configurationDefaults

image.png 为特定的语言配置编辑器的默认值，修改这个配置会覆盖编辑器已经为语言提供的默认配置。

以下示例覆盖了 files.autoSave 设置的默认行为，将其改为在焦点变化时自动保存文件。

"configurationDefaults": {
      "files.autoSave": "onFocusChange"
}

下面的示例是修改markdown语言的默认配置。

示例

{
  "contributes": {
    "configurationDefaults": {
      "[markdown]": {
        "editor.wordWrap": "on",
        "editor.quickSuggestions": {
          "comments": "off",
          "strings": "off",
          "other": "off"
        }
      }
    }
  }
}
avatar
文章
阅读
粉丝