配置高级特性

基础配置项之外，scope、deprecationMessage、markdownDescription 等高级字段让配置体系更完整、更专业。

scope 配置作用域

scope 决定配置值能写在哪个层级、影响范围多大：

{
  "mylinter.enable": {
    "type": "boolean",
    "default": true,
    "scope": "window",
    "description": "启用检查"
  }
}

五种作用域

scope	存储位置	适用场景
application	用户全局（所有窗口）	插件安装目录、全局开关
window	当前窗口	大多数插件配置（默认值）
resource	工作区/文件夹/文件级	与具体文件或文件夹相关的配置
machine	机器级（机器 + 用户覆盖）	无法跨机器同步的配置
machine-overridable	机器级（可被用户/工作区覆盖）	需要机器默认但允许覆盖
language-overridable	语言级覆盖	可按语言覆盖的配置

作用域详解

{
  "mylinter.path": {
    "type": "string",
    "scope": "machine",
    "description": "检查器路径（机器级，不同机器可不同）"
  },
  "mylinter.tabSize": {
    "type": "number",
    "scope": "resource",
    "description": "缩进宽度（可按文件夹/文件设置）"
  },
  "mylinter.semanticErrors": {
    "type": "boolean",
    "scope": "language-overridable",
    "description": "显示语义错误（可针对 JavaScript 单独设置）"
  }
}

作用域与 UI

设置界面会根据作用域显示对应位置的写入按钮：

scope	设置 UI 按钮
window	"用户" / "工作区"
resource	"用户" / "工作区" / "文件夹"
machine	"机器"（受限）
application	仅"用户"

deprecationMessage 废弃提示

配置废弃后，用 deprecationMessage 引导用户迁移：

{
  "mylinter.oldRule": {
    "type": "string",
    "default": "",
    "deprecationMessage": "此配置已废弃，请改用 #mylinter.rules# 的 #no-console# 规则",
    "markdownDeprecationMessage": "此配置已废弃，请改用 [`mylinter.rules`](#mylinter.rules) 的 `no-console` 规则"
  }
}

字段	说明
deprecationMessage	废弃提示（纯文本，# 渲染为代码）
markdownDeprecationMessage	废弃提示（完整 Markdown）

设置了废弃消息的配置在设置界面会显示删除线与警告样式，用户仍可使用，但会收到提示。

迁移示例

{
  "mylinter.oldIgnorePattern": {
    "type": "string",
    "deprecationMessage": "已废弃：请使用 #mylinter.ignoreFiles#（数组类型）",
    "markdownDeprecationMessage": "已废弃：请使用 [`mylinter.ignoreFiles`](#mylinter.ignoreFiles)"
  },
  "mylinter.ignoreFiles": {
    "type": "array",
    "items": { "type": "string" },
    "default": []
  }
}

markdownDescription Markdown 说明

markdownDescription 支持完整 Markdown 渲染，比 description 更丰富：

{
  "mylinter.rules": {
    "type": "object",
    "markdownDescription": "规则配置对象。每条规则的值可以是：\n\n- `\"error\"` — 错误级别\n- `\"warning\"` — 警告级别\n- `\"off\"` — 关闭\n\n示例：\n\n```json\n{\n  \"mylinter.rules\": {\n    \"no-console\": \"warning\"\n  }\n}\n```",
    "default": {}
  }
}

Markdown 特性

语法	效果
[链接](https://...)	外链
#配置名#	渲染为可点击的配置引用
代码块 ```json	展示示例
列表/表格	结构化说明

markdownDescription 与 description 同时存在时，Markdown 版本优先显示。

配置分组与排序

title 分组

contributes.configuration 的 title 是分组名，同 title 的配置项在设置界面聚在同一分组：

{
  "contributes": {
    "configuration": [
      {
        "title": "MyLinter: 基础",
        "properties": {
          "mylinter.enable": { "type": "boolean", "default": true }
        }
      },
      {
        "title": "MyLinter: 规则",
        "properties": {
          "mylinter.rules": { "type": "object", "default": {} }
        }
      }
    ]
  }
}

configuration 支持对象或数组形式，数组可声明多个分组。

order 排序

order 控制设置界面中的展示顺序：

{
  "mylinter.enable": {
    "type": "boolean",
    "default": true,
    "order": 1,
    "description": "启用检查"
  },
  "mylinter.rules": {
    "type": "object",
    "default": {},
    "order": 2,
    "description": "规则配置"
  }
}

order 数字越小越靠前。不设置 order 的配置排在设置了 order 的之后。

$ref 复用配置结构

用 $ref 复用 JSON Schema 定义，避免重复：

{
  "contributes": {
    "configuration": {
      "title": "MyLinter",
      "properties": {
        "mylinter.directories": {
          "type": "array",
          "items": { "$ref": "#/definitions/ruleSetting" },
          "default": [],
          "description": "目录级规则设置"
        }
      },
      "definitions": {
        "ruleSetting": {
          "type": "object",
          "properties": {
            "path": { "type": "string" },
            "rules": { "type": "object" }
          }
        }
      }
    }
  }
}

配置的校验与提示

校验消息

配置值不满足约束时，设置界面显示错误：

{
  "mylinter.maxWarnings": {
    "type": "number",
    "default": 100,
    "minimum": 1,
    "maximum": 10000,
    "errorMessage": "值必须在 1 到 10000 之间"
  }
}

模式约束（pattern）

{
  "mylinter.pattern": {
    "type": "string",
    "default": "*.{ts,js}",
    "pattern": "^[a-zA-Z0-9*?.{}]+$",
    "description": "文件匹配模式"
  }
}

配置与命令的联动

配置项可关联命令按钮（settings 界面的齿轮菜单）：

{
  "contributes": {
    "configuration": {
      "properties": {
        "mylinter.configFile": {
          "type": "string",
          "default": ".mylinter.json"
        }
      }
    },
    "commands": [
      { "command": "mylinter.resetConfig", "title": "重置配置" }
    ],
    "menus": {
      "configuration/title": [
        {
          "command": "mylinter.resetConfig",
          "when": "config.mylinter.enable"
        }
      ]
    }
  }
}

高级配置特性让插件配置具备企业级体验：作用域精细控制、废弃平滑迁移、文档丰富呈现。下一步学习代码中如何读取与修改配置。