跳到主要内容

配置怎么声明类型、默认值和范围？

结论​

配置在 contributes.configuration 里用 JSON Schema 声明。type 和 default 决定设置界面和缺省值，scope 决定这值能写到用户、工作区、文件夹还是按语言覆盖。

展开​

{
  "contributes": {
    "configuration": {
      "title": "我的插件",
      "properties": {
        "myext.enable": {
          "type": "boolean",
          "default": true,
          "description": "是否启用检查",
          "scope": "resource"
        },
        "myext.mode": {
          "type": "string",
          "enum": ["fast", "full"],
          "default": "fast",
          "scope": "window"
        }
      }
    }
  }
}

键名用 插件短名.配置名，避免和别人冲突。

scope 常见值：

  • window：用户或工作区，窗口内一份，不随单个文件变化
  • resource：可以写到某个文件夹，甚至某份资源相关的设置
  • language-overridable：设置界面里能按语言覆盖，例如格式化开关
  • machine：只留在本机，不进设置同步

有默认值时，get 在用户没写过的情况下拿到 default。不要在代码里再写一套不同的默认值。

枚举、最小值、markdownDescription 都会反映到设置界面。改配置贡献后要重载窗口，宿主才会重新读清单。

容易讲错的点​

  • scope 写错不会在运行时抛错，但设置会写到错误的层级，多根工作区里表现为「改了不生效」。
  • 不要用配置存令牌或体积大的缓存。
  • 数组和对象类型要写清 items 或 properties，否则设置界面只能当自由 JSON，容易配坏。