全栈攻城狮

Appearance

contributes.configuration 配置定义 ​

配置是插件与用户交互的基础：用户通过设置界面调整插件行为，插件读取配置驱动功能。本文从 package.json 的配置声明开始。

配置的声明位置 ​

配置在 package.json 的 contributes.configuration 中声明：

json
{
  "contributes": {
    "configuration": {
      "title": "MyLinter",
      "properties": {
        "mylinter.enable": {
          "type": "boolean",
          "default": true,
          "description": "是否启用检查"
        }
      }
    }
  }
}
字段作用
title设置页中的分组标题
properties全部配置项定义

配置项的完整键名是 mylinter.enable 这种 插件名.配置名 形式，必须用点号分隔，插件名建议与扩展名一致。

配置类型 ​

type 定义配置的数据类型，支持五种基础类型：

string 字符串 ​

json
{
  "mylinter.executablePath": {
    "type": "string",
    "default": "mylinter",
    "description": "检查器可执行文件路径"
  }
}

number 数字 ​

json
{
  "mylinter.maxWarnings": {
    "type": "number",
    "default": 100,
    "minimum": 0,
    "maximum": 10000,
    "description": "允许的最大警告数"
  }
}

数字类型支持 minimum、maximum 范围约束，设置界面会自动限制输入。

boolean 布尔 ​

json
{
  "mylinter.autoFixOnSave": {
    "type": "boolean",
    "default": false,
    "description": "保存时自动修复"
  }
}

array 数组 ​

json
{
  "mylinter.ignoreRules": {
    "type": "array",
    "items": { "type": "string" },
    "default": ["no-unused-vars"],
    "description": "忽略的规则列表"
  }
}

数组必须指定 items 类型。数组设置项在 UI 中显示为可增删的列表。

object 对象 ​

json
{
  "mylinter.ruleSettings": {
    "type": "object",
    "properties": {
      "no-console": { "type": "boolean" }
    },
    "additionalProperties": { "type": "boolean" },
    "default": {},
    "description": "每条规则的开关"
  }
}

对象类型可用 properties 描述已知字段，用 additionalProperties 约束未知字段。

default 默认值 ​

default 定义配置的初始值，应尽量与"开箱即用的合理行为"一致：

json
{
  "mylinter.enable": {
    "type": "boolean",
    "default": true
  },
  "mylinter.tabSize": {
    "type": "number",
    "default": 4
  }
}

注意：没有 default 的配置项，get() 返回 undefined。读取时应做兜底处理。

description 描述 ​

description 是设置界面显示的说明文字，支持富文本：

json
{
  "mylinter.timeout": {
    "type": "number",
    "default": 5000,
    "description": "检查超时时间（毫秒）"
  }
}

命令行参数格式化 ​

用 # 包裹的命令在设置界面会渲染成可点击的代码样式：

json
{
  "mylinter.args": {
    "type": "array",
    "items": { "type": "string" },
    "default": [],
    "description": "传给检查器的命令行参数，如 #--fix#"
  }
}

enum 枚举 ​

enum 限制配置的可选值，配合 enumDescriptions 给出每个选项的解释：

json
{
  "mylinter.outputLevel": {
    "type": "string",
    "enum": ["info", "warning", "error", "silent"],
    "enumDescriptions": [
      "输出所有信息",
      "仅输出警告与错误",
      "仅输出错误",
      "不输出"
    ],
    "default": "warning",
    "description": "日志输出级别"
  }
}

枚举在设置界面渲染为下拉选择框，用户只能从候选中选择。

多选枚举 ​

json
{
  "mylinter.plugins": {
    "type": "array",
    "items": {
      "type": "string",
      "enum": ["react", "vue", "svelte"]
    },
    "default": ["react"],
    "description": "启用的框架插件"
  }
}

完整配置定义示例 ​

综合前面所有特性的一个完整配置块：

json
{
  "contributes": {
    "configuration": {
      "title": "MyLinter",
      "properties": {
        "mylinter.enable": {
          "type": "boolean",
          "default": true,
          "description": "启用 MyLinter 代码检查"
        },
        "mylinter.executablePath": {
          "type": "string",
          "default": "mylinter",
          "description": "检查器路径"
        },
        "mylinter.maxWarnings": {
          "type": "number",
          "default": 100,
          "minimum": 0,
          "description": "最大警告数"
        },
        "mylinter.outputLevel": {
          "type": "string",
          "enum": ["info", "warning", "error"],
          "enumDescriptions": ["全部", "警告及以上", "仅错误"],
          "default": "warning"
        },
        "mylinter.ignoreRules": {
          "type": "array",
          "items": { "type": "string" },
          "default": [],
          "description": "忽略的规则"
        },
        "mylinter.autoFixOnSave": {
          "type": "boolean",
          "default": false
        }
      }
    }
  }
}

设置界面呈现 ​

声明完成后，设置界面自动生成：

text
扩展 → MyLinter
 ├─ 启用 MyLinter 代码检查        [✓]
 ├─ 检查器路径                    [mylinter____]
 ├─ 最大警告数                    [100________]
 ├─ 日志输出级别                  [警告及以上 ▼]
 ├─ 忽略的规则                    [添加项...]
 └─ 保存时自动修复                [   ]

配置的智能提示 ​

配置声明后，用户在 settings.json 中编写时会获得：

  • 自动补全：输入 mylinter. 提示全部配置项
  • 类型校验：错误类型（如把 boolean 写为字符串）会标红
  • 描述展示：悬停显示 description
  • 枚举提示：枚举值自动补全

常见的配置错误 ​

错误后果修复
键名缺少插件前缀与其他插件冲突使用 插件名.配置名
数组未定义 items设置界面无法编辑补充 items
默认值与类型不符配置失效核对类型
枚举没有默认值读取 undefined设置 default

配置声明是配置体系的基石。接下来了解高级特性：作用域、废弃提示与 Markdown 描述。