VS Code 插件配置篇

JQ_Chan酱
1,376 阅读6分钟

插件可以使用contributes.configuration设置特定于插件的配置信息，并使用workspace.getConfigurationAPI来读取它们。

contributes.configuration

提供向用户公开的配置信息。用户可以将这些配置选项设置为用户设置或工作区设置，方法是使用设置编辑器或直接编辑JSON设置文件（即.vscode文件夹中的setting.json）。

contributes.configuration可以是单个对象，代表耽搁设置类别，也可以是对象数组，代表多个设置类别。如果有多个设置类别，设置编辑器将在该插件的目录中显示一个字菜单，类别key将用于子菜单条目名称，如下面例子中有两个设置，一个为typescript.useCodeSnippetsOnMethodSuggest，另一个为typescript.tsdk。

{
  "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.png

读取配置信息

你可以在插件中通过代码来读取上面这些配置，其中myExtension为你插件的名称。

获取工作区配置对象getConfiguration(section?: string, scope?: ConfigurationScope): WorkspaceConfiguration

// { myExtension: { setting: { doIt: true }}}

const settings = vscode.workspace.getConfiguration('myExtension')；

// vscode.workspace.getConfiguration('myExtension.setting').get('doIt') === true

配置语法

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

settings-ui.png

{
  "configuration": {
    "title": "GitMagic",
    "properties": {
      "gitMagic.blame.dateFormat": {
        "type": "string",
        "default": "",
        "mardownDescription": "Specifies how to format absolute dates (e.g. using the `${date}` token) in gutter blame annotations. See the [Moment.js docs](https://momentjs.com/docs/#/displaying/format/) for valid formats"
      },
      "gitMagic.blame.heatMap.enabled": {
        "type": "boolean",
        "default": true,
        "description": "Specifies whether to provide a heatmap indicator in the gutter blame annotations"
      },
      "gitMagic.views.pageItemLimit": {
          "type": "number",
          "default": 20,
          " description": "Specifies the number of items to show in each page when paginating a view list. Use 0 to specify no limit"
      },
      "gitMagic.blame.compact": {
        "type": "boolean",
        "default": true,
        "description": "Specifies whether to compact (deduplicate) matching adjacent gutter blame annotations"
      },
      "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"
        ]
      }
    }
  }
}
  • title 用于类别的标题，如图中1⃣️所示；
  • properties 配置属性的字典，如图中2⃣️所示；

    在设置UI中，你的配置key将用于命名空间和构建标题，虽然插件可以包含多个类别的设置，但插件的每个设置必须有自己唯一的key。key中的大写字母用于指示单词中断。例如，

gitMagic.blame.dateFormat

gitMagic.blame.format

gitMagic.blame.heatMap.enabled

gitMagic.blame.heatMap.location

生成的标题为：

如果没有明确的顺序字段的属性按字母顺序显示

Blame: Date Format

Blame: Format

Blame > HeatMap: Enabled

Blame > HeatMap: Location

property语法

  • description / mardownDescription

配置条目的描述图中3⃣️出现在标题之后和输入字段之前，布尔值除外，其中图中6⃣️描述用作复选框的标签。如果你使用markdownDescription而不是description，你的配置条目描述将在设置UI中呈现为Markdown。

对于markdownDescription，为了添加换行符或多个段落，请使用\n\n，而不仅仅是\n

  • type

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

如果在设置条目上设置"editPresentation": "multilineText"，则可以使用多行文本输入呈现字符串设置

对于布尔值，description或markdownDescription将用作复选框的标签

此外，一些object、array类型的设置将在设置UI中呈现。数字、字符串或布尔值的简单数组将呈现为可编辑列表。具有字符串、数字、整数或布尔类型属性的对象将呈现为键和值的可编辑表格。对象设置还应将addtionnalProperties设置为false或具有适当type属性的对象，以在UI中呈现。

如果object、array设置还可以包含其他类型，如嵌套对象，数组或null，则该值不会在设置中呈现，只能通过直接编辑JSON进行设置。用户将看到一个指向编辑setting.json的链接，如图中8⃣️所示

  • order

类别和这些类别中的设置都可以采用整数的order属性。该属性提供了它们相对于其他类别或其他设置应如何排序的参考。

  • enum / enumDescriptions / enumItemLabels

如果你在enum属性提供一组选项，设置UI将呈现一个下拉菜单，如图7⃣️所示。

你还可以提供一个enumDescriptions属性，在下拉列表底部呈现选项描述。

settings-ui-enum.png

要自定义下拉选项，你可以使用enumItemLabels属性.workbench.iconTheme设置同时使用enumDescriptions和enumItemLabels。在下面截图中，悬浮选项的label为"None", 描述为"No file icons", enum值为null

settings-ui-icon-theme.png

  • deprecationMessage / markdownDeprecationMessage

如果你设置deprecationMessage或markdownDeprecationMessage，该设置将在你指定的消息中添加警告下划线。它不会显示在设置UI中，除非它是由用户配置的。

如果只设置markdownDeprecationMessage，markdown将不会在设置悬停或问题视图中呈现。

如果同时设置这两个属性，deprecationMessage将显示在悬停和问题视图中，而markdownDeprecationMessage将在设置UI中呈现为Markdown

  • scope

配置scope确定用于何时可以通过设置编辑器使用某个设置以及该设置是否适用。如果没有声明scope，则默认window

配置设置生效的可能范围：

  1. application 适用于所有VS Code实例且只能在用户设置中配置的设置
  2. machine 只能在用户设置或远程设置中设置的机器特定设置，例如，不应跨机器共享的安装路径
  3. machine- overridable 可以被工作区或文件夹设置覆盖的机器特定设置
  4. window 可以在用户、工作区或远程设置中配置的 Windows（实例）特定设置
  5. resource 资源设置，适用于文件和文件夹，可以在所有设置级别进行配置，甚至文件夹设置
  6. language-overridable 可以在语言级别覆盖的资源设置

其它JSON属性

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

链接到settings

你可以插入指向另一个设置的链接，该链接在设置UI中呈现为可点击链接，方法是在markdown类型的属性中使用以下特殊语法：#target.setting.id#，这可以在markdownDescription，markdownEnumDescriptions，markdownDeprecationMessage中生效，例如：

"files.autoSaveDelay": {
  "markdownDescription": "Controls the delay in ms after which a dirty editor is saved automatically. Only applies when `#files.autoSave#` is set to `afterDelay`.",
  // ...
}

setting-link.png

默认配置contributes.configurationDefaults

为其它注册配置提供默认值并覆盖它们的默认值。例如，将files.autoSave设置的默认行为覆盖为在焦点更改时自动保存文件：

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

此外，还可以为所提供的语言提供默认的编辑器设置，例如，为markdown语言提供默认的编辑器配置：

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