Contributes Points
contributes points
是在package.json
中的一组JSON
声明
configuration
:设置configurationDefaults
commands
:命令menus
:菜单keybindings
:快捷键绑定languages
:语言支持debuggers
:调试breakpoints
:断点grammars
:themes
:主题iconThemes
:图标主题productIconThemes
:snippets
:代码片段jsonValidation
:自定义JSON
校验views
:左侧侧边栏视图viewsWelcome
:viewsContainers
:自定义activitybar
walkthroughs
problemMatchers
problemPatterns
taskDefinitions
colors
typescriptServerPlugins
resourceLabelFormatters
customEditors
1、configuration
配置
{
"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."
}
}
}
}
}
可以使用 vscode.workspace.getConfiguration('myExtension')
从插件中读取这些值。
1. title
标题
标题应该是您的插件的确切名称。
- ✅
"title": "GitMagic"
- ❌
"title": "GitMagic Extension"
- ❌
"title": "GitMagic Configuration"
- ❌
"title": "GitMagic Extension Configuration Settings"
2. properties
属性
配置的 key
将用于命名空间和构造标题。key
的大写字母用于表示分词。
例如,如果您的 key
是 gitMagic.blame.dateFormat
,则为该设置生成的标题将如下所示:
Blame: Date Format
会将根据 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
否则,属性按照字母顺序出现
1. description / markdownDescription
描述
描述出现在标题之后和输入字段之前,布尔值除外,其中描述用作复选框的标签。
{
"gitMagic.blame.heatmap.enabled": {
"description": "Specifies whether to provide a heatmap indicator in the gutter blame annotations"
}
}
如果您使用 markdownDescription
而不是 description
,您的设置描述将在 settings UI
中呈现为 Markdown
模式。
{
"gitMagic.blame.dateFormat": {
"markdownDescription": "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"
}
}
2. type
类型:[number
, string
, boolean
, object
, array
, …]
number
、string
、boolean
可以直接在 settings UI
中编辑,boolean
将会作为复选框的标签
{
"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"
}
}
{
"gitMagic.blame.compact": {
"type": "boolean",
"description": "Specifies whether to compact (deduplicate) matching adjacent gutter blame annotations"
}
}
object
、array
等不能在 settings UI
中展示,只能在 JSON
进行修改。
3. enum
/ enumDescriptions
/ markdownEnumDescriptions
enum
:枚举:如果提供一个数组,则会展示下拉选项
enumDescriptions
:枚举描述
markdownEnumDescriptions
:将呈现为 markdown
模式。
{
"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"
]
}
}
4. deprecationMessage
/ markdownDeprecationMessage
{
"json.colorDecorators.enable": {
"type": "boolean",
"description": "Enables or disables color decorators",
"markdownDeprecationMessage": "**Deprecated**: Please use `#editor.colorDecorators#` instead.",
"deprecationMessage": "Deprecated: Please use editor.colorDecorators instead."
}
}
5. default
定义属性的默认值
6. minimum
/ maximum
限制数值的最大值和最小值
7. maxLength
/ minLength
限制字符串长度
8. pattern
使用正则限制字符串
9. format
限制字符串的格式:date
、time
、ipv4
、email
、uri
10. maxItems
/ minItems
限制数组长度
11. scope
范围
属性值:
application
:适用于所有VScode
实例的设置,只能在用户设置中设置machine
:在用户或远程设置中设置的机器特定设置machine-overridable
:可以被工作区或者文件夹设置的机器特定设置window
:可以在用户、工作区或远程设置中配置的windows
特定设置resource
:适用于文件和文件夹的资源设置,可以在所有设置级别进行设置,甚至文件夹设置language-overridable
:可以在语言级别覆盖的资源设置
如果未声明范围,则默认为窗口。
12. Linking to settings
指向另一个设置的链接
在 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`.",
// ...
}
在 settings UI
界面展示为:
2、configurationDefaults
默认配置
{
"contributes": {
"configurationDefaults": {
"[markdown]": {
"editor.wordWrap": "on",
"editor.quickSuggestions": false
}
}
}
}
3、commands
命令
由 title
、icon
(可选)、category
、command
命令组成。默认情况下,命令显示在命令面板 (⇧⌘P
) 中,但它们也可以显示在其他菜单中。
当调用命令时,VS Code 将发出 activationEvent onCommand:${command}
{
"contributes": {
"commands": [
{
"command": "extension.sayHello",
"title": "Hello World",
"category": "Hello",
"icon": {
"light": "path/to/light/icon.svg",
"dark": "path/to/dark/icon.svg"
}
}
]
}
}
command
icon
的规格
- 尺寸:图标应为 16x16,内边距为 1 像素(图像为 14x14)并居中。
- 颜色:图标应使用单一颜色。
- 格式:建议图标为 SVG,但可以接受任何图像文件类型。
4、menus
菜单项
1. 可以选择的拓展项
- 全局命令面板 -
commandPalette
- 资源管理器上下文菜单 -
explorer/context
- 编辑器上下文菜单 -
editor/context
- 编辑器标题菜单栏 -
editor/title
- 编辑器标题上下文菜单 -
editor/title/context
- 调试调用堆栈视图上下文菜单 -
debug/callstack/context
- 调试调用堆栈视图内联操作 -
debug/callstack/context group inline
- 调试变量视图上下文菜单 -
debug/variables/context
- 调试工具栏 -
debug/toolbar
SCM
标题菜单 -scm/title
SCM
资源组菜单 -scm/resourceGroup/context
SCM
资源文件夹菜单 -scm/resourceFolder/context
SCM
资源菜单 -scm/resourceState/context
SCM
更改标题菜单 -scm/change/title
SCM
源代码控制菜单 -scm/sourceControl
- 视图标题菜单 -
view/title
- 查看项目菜单 -
view/item/context
macOS
触控栏 -touchBar
- 注释线程标题菜单栏 -
comments/commentThread/title
- 注释线程上下文菜单 -
comments/commentThread/context
- 注释标题菜单栏 -
comments/comment/title
- 注释上下文菜单 -
comments/comment/context
- 时间线视图标题菜单栏 -
timeline/title
- 时间线视图项目上下文菜单 -
timeline/item/context
- 扩展视图上下文菜单 -
extension/context
{
"contributes": {
"menus": {
"editor/title": [
{
"when": "resourceLangId == markdown",
"command": "markdown.showPreview",
"alt": "markdown.showPreviewToSide",
"group": "navigation"
}
]
}
}
}
2. 可以通过 when
来控制何时可见
"menus": {
"commandPalette": [
{
"command": "extension.sayHello",
"when": "editorHasSelection"
}
]
}
仅当被选中时可见
3. 分组排序
1. editor context menu
默认组
navigation
:导航组在所有情况下都排在第一位1_modification
:该组紧随其后,包含修改代码的命令9_cutcopypaste
:带有基本编辑命令的倒数第二个默认组z_commands
:带有打开命令面板的条目的最后一个默认组
2. explorer context menu
默认组
navigation
:与跨VS Code
导航相关的命令。该组在所有情况下都排在第一位2_workspace
:与工作区操作相关的命令3_compare
:与在差异编辑器中比较文件相关的命令4_search
:在搜索视图中与搜索相关的命令5_cutcopypaste
:与剪切、复制和粘贴文件相关的命令6_copypath
:与复制文件路径相关的命令7_modification
:与文件修改相关的命令
3. editor tab context menu
默认组
1_close
:与关闭编辑器相关的命令3_preview
:与固定编辑器相关的命令
4. editor title menu
默认组
navigation
:与导航相关的命令1_run
:与运行和调试编辑器相关的命令1_diff
:与使用差异编辑器相关的命令3_open
:与打开编辑器相关的命令5_close
:与关闭编辑器相关的命令
5. Timeline view item context menu
默认组
inline
:重要或常用的时间线项目命令1_actions
:与使用时间线项目相关的命令5_copy
:与复制时间线项目相关的命令
6. Extensions view context menu
默认组
1_copy
:与复制扩展信息相关的命令2_configure
:与配置扩展相关的命令
4. 在组内排序
通过 @<number>
附加到组内来指定的
{
"editor/title": [
{
"when": "editorHasSelection",
"command": "extension.Command",
"group": "myGroup@1"
}
]
}
5、keybindings
快捷键绑定
当 win/linux
触发 Ctrl+F1
或者 MacOS
触发 Cmd + F1
时,调用 extension.sayHello
命令
{
"contributes": {
"keybindings": [
{
"command": "extension.sayHello",
"key": "ctrl+f1",
"mac": "cmd+f1",
"when": "editorTextFocus"
}
]
}
}
6、languages
语言
作用:
- 定义一个可以在
VS Code API
的其他部分重用的languageId
- 将文件扩展名、文件名模式、以特定行开头的文件、
mimetypes
与该语言ID
相关联。
{
"contributes": {
"languages": [
{
"id": "python",
"extensions": [".py"],
"aliases": ["Python", "py"],
"filenames": [],
"firstLine": "^#!/.*\\bpython[0-9.-]*\\b",
"configuration": "./language-configuration.json"
}
]
}
}
7、debuggers
调试器
type
是用于在启动配置中标识此调试器的唯一ID
label
是此调试器在 UI 中的用户可见名称program
编写调试适配器的路径,该适配器针对实际调试器或运行时实现VS Code
调试协议runtime
如果调试适配器的路径不是可执行文件但需要运行时configurationAttributes
是特定于此调试器的启动配置参数的架构。 请注意,不支持JSON
架构构造$ref
和定义initialConfigurations
列出了用于填充初始launch.json
的启动配置configurationSnippets
列出了在编辑launch.json
时通过IntelliSense
可用的启动配置variables
引入替换变量并将它们绑定到由调试器扩展实现的命令languages
那些调试扩展可以被视为“默认调试器”的语言
{
"contributes": {
"debuggers": [
{
"type": "node",
"label": "Node Debug",
"program": "./out/node/nodeDebug.js",
"runtime": "node",
"languages": ["javascript", "typescript", "javascriptreact", "typescriptreact"],
"configurationAttributes": {
"launch": {
"required": ["program"],
"properties": {
"program": {
"type": "string",
"description": "The program to debug."
}
}
}
},
"initialConfigurations": [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js"
}
],
"configurationSnippets": [
{
"label": "Node.js: Attach Configuration",
"description": "A new configuration for attaching to a running node program.",
"body": {
"type": "node",
"request": "attach",
"name": "${2:Attach to Port}",
"port": 9229
}
}
],
"variables": {
"PickProcess": "extension.node-debug.pickNodeProcess"
}
}
]
}
}
8、breakpoints
断点
{
"contributes": {
"breakpoints": [
{
"language": "javascript"
},
{
"language": "javascriptreact"
}
]
}
}
9、grammars
为一种语言写一个 TextMate
语法,包含语法的文件可以是 JSON
或者 XML plist
格式
必须指定一个 label
{
"contributes": {
"grammars": [
{
"language": "markdown",
"scopeName": "text.html.markdown",
"path": "./syntaxes/markdown.tmLanguage.json",
"embeddedLanguages": {
"meta.embedded.block.frontmatter": "yaml"
}
}
]
}
}
10、themes
主题
{
"contributes": {
"themes": [
{
"label": "Monokai",
"uiTheme": "vs-dark",
"path": "./themes/monokai-color-theme.json"
}
]
}
}
11、iconThemes
图标主题
必须指定一个 id
,一个 label
和一个 path
{
"contributes": {
"iconThemes": [
{
"id": "metro",
"label": "Metro File Icons",
"path": "./fileicons/metro-file-icon-theme.json"
}
]
}
}
12、productIconThemes
产品图标主题
必须指定一个 id
,一个 label
和一个 path
{
"contributes": {
"productIconThemes": [
{
"id": "elegant",
"label": "Elegant Icon Theme",
"path": "./producticons/elegant-product-icon-theme.json"
}
]
}
}
13、snippets
代码片段
为 go
语言添加一份代码片段
{
"contributes": {
"snippets": [
{
"language": "go",
"path": "./snippets/go.json"
}
]
}
}
14、jsonValidation
JSON
验证
为特定的 JSON
文件提供验证, url
可以时本地文件也可以时网络文件
{
"contributes": {
"jsonValidation": [
{
"fileMatch": ".jshintrc",
"url": "https://json.schemastore.org/jshintrc"
}
]
}
}
15、views
视图
必须为视图指定标识符和名称
explorer
: 活动栏中的资源管理器视图容器scm
: 活动栏中的源代码管理 (SCM) 视图容器debug
: 在活动栏中运行和调试视图容器test
: 活动栏中的测试视图容器Custom view
:扩展提供的自定义视图容器
当用户打开视图时,VScode
将会发出一个 activationEvent onView:${viewId}
{
"contributes": {
"views": {
"explorer": [
{
"id": "nodeDependencies",
"name": "Node Dependencies",
"when": "workspaceHasPackageJSON",
"icon": "media/dep.svg",
"contextualTitle": "Package Explorer"
}
]
}
}
}
两种方式填充视图内容
- 通过
createTreeView API
提供数据提供者或直接通过registerTreeDataProvider API
注册数据提供者来填充数据,从而使用TreeView
- 通过使用
registerWebviewViewProvider
注册提供程序来使用WebviewView
,Webview
视图允许在视图中呈现任意HTML
。
16、viewsWelcome
欢迎视图,仅适用于空树视图
{
"contributes": {
"viewsWelcome": [
{
"view": "scm",
"contents": "In order to use git features, you can open a folder containing a git repository or clone from a URL.\n[Open Folder](command:vscode.openFolder)\n[Clone Repository](command:git.clone)\nTo learn more about how to use git and source control in VS Code [read our docs](https://aka.ms/vscode-scm).",
"when": "config.git.enabled && git.state == initialized && workbenchState == empty"
}
]
}
}
17、viewsContainers
视图容器,必须为视图容器指定 identifier
(标识符)、title
(标题)、和 icon
{
"contributes": {
"viewsContainers": {
"activitybar": [
{
"id": "package-explorer",
"title": "Package Explorer",
"icon": "resources/package-explorer.svg"
}
]
},
"views": {
"package-explorer": [
{
"id": "package-dependencies",
"name": "Dependencies"
},
{
"id": "package-outline",
"name": "Outline"
}
]
}
}
}
图标规则
- 大小:图标应为 24x24 且居中。
- 颜色:图标应使用单一颜色。
- 格式:建议图标为
SVG
,但可以接受任何图像文件类型。 - 状态:所有图标都继承以下状态样式:
State | Opacity |
---|---|
Default | 60% |
Hover | 100% |
Active | 100% |
18、walkthroughs
演示,在开始页面提供演示,由标题、描述、ID
和一系列步骤组成
演示中每个步骤都有一个标题、描述、ID
和媒体元素(图像或者 markdown
内容),以及一系列将导致检查步骤的可选择事件
{
"contributes": {
"walkthroughs": [
{
"id": "sample",
"title": "Sample",
"description": "A sample walkthrough",
"steps": [
{
"id": "runcommand",
"title": "Run Command",
"description": "This step will run a command and check off once it has been run.\n[Run Command](command:getting-started-sample.runCommand)",
"media": { "image": "media/image.png", "altText": "Empty image" },
"completionEvents": ["onCommand:getting-started-sample.runCommand"]
},
{
"id": "changesetting",
"title": "Change Setting",
"description": "This step will change a setting and check off when the setting has changed\n[Change Setting](command:getting-started-sample.changeSetting)",
"media": { "markdown": "media/markdown.md" },
"completionEvents": ["onSettingChanged:getting-started-sample.sampleSetting"]
}
]
}
]
}
}
1. Completion events
默认情况下,如果没有提供 completion events
事件,单击任何按钮时将关闭该步骤,或者如果该步骤没有按钮,则在打开时将其选中,可以提供一个 completionEvents
列表
可用的 Completion Events
事件:
onCommand:myCommand.id
:在命令运行时onSettingChanged:mySetting.id
:一旦给定设置被修改onContext:contextKeyExpression
:当上下文键表达式计算为真时extensionInstalled:myExt.id
:如果安装了给定的扩展onView:myView.id
:一旦给定的视图变得可见onLink:https://...
:一旦通过演示打开给定链接。
一旦一个步骤被选中,它将保持选中状态,直到用户明确取消选中该步骤或重置他们的进度(通过入门:重置进度命令)。
19、problemMatchers
问题匹配
{
"contributes": {
"problemMatchers": [
{
"name": "gcc",
"owner": "cpp",
"fileLocation": ["relative", "${workspaceFolder}"],
"pattern": {
"regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
"file": 1,
"line": 2,
"column": 3,
"severity": 4,
"message": 5
}
}
]
}
}
{
"version": "2.0.0",
"tasks": [
{
"label": "build",
"command": "gcc",
"args": ["-Wall", "helloWorld.c", "-o", "helloWorld"],
"problemMatcher": "$gcc"
}
]
}
可以通过名称引用 $gcc
在 tasks.json
文件中使用此问题匹配器
20、problemPatterns
问题模式
21、taskDefinitions
任务定义,至少要有一个类型属性,通常需要定义附加属性
{
"taskDefinitions": [
{
"type": "npm",
"required": ["script"],
"properties": {
"script": {
"type": "string",
"description": "The script to execute"
},
"path": {
"type": "string",
"description": "The path to the package.json file. If omitted the package.json in the root of the workspace folder is used."
}
}
}
]
}
使用 JSON
架构语法为 required
和 properties
属性定义的
"type"
:"npm"
将任务定义与npm
任务相关联"required"
: ["script"
] 将该脚本属性定义为必需的。path
属性是可选的"properties" : { ... }
定义附加属性及其类型
当创建一个任务时,需要传递一个符合 package.json
文件中贡献的任务定义 TaskDefinition
let task = new vscode.Task({ type: 'npm', script: 'test' }, ....);
22、colors
主题颜色,定义后,用户可以在 workspace.colorCustomization
设置中自定义颜色,用户主题可以设置颜色值。
{
"contributes": {
"colors": [
{
"id": "superstatus.error",
"description": "Color for error message in the status bar.",
"defaults": {
"dark": "errorForeground",
"light": "errorForeground",
"highContrast": "#010203"
}
}
]
}
}
插件可以使用 ThemeColor API
使用新的和现有的主题颜色
const errorColor = new vscode.ThemeColor('superstatus.error');
23、typescriptServerPlugins
提供 TypeScript
服务器插件,以增强 VS Code
的 JavaScript
和 TypeScript
支持
{
"contributes": {
"typescriptServerPlugins": [
{
"name": "typescript-styled-plugin"
}
]
}
}
上面的示例扩展提供了 typescript-styled-plugin
,它为 JavaScript
和 TypeScript
添加了样式组件 IntelliSense
{
"dependencies": {
"typescript-styled-plugin": "*"
}
}
当用户使用 VS Code
的 TypeScript
版本时,会为所有 JavaScript
和 TypeScript
文件加载 TypeScript
服务器插件。如果用户使用的是 TypeScript
的工作区版本,它们不会被激活,除非插件明确设置 "enableForWorkspaceTypeScriptVersions": true
{
"contributes": {
"typescriptServerPlugins": [
{
"name": "typescript-styled-plugin",
"enableForWorkspaceTypeScriptVersions": true
}
]
}
}
24、resourceLabelFormatters
提供资源标签格式化程序,指定如何在工作台中的任何地方显示 URI
{
"contributes": {
"resourceLabelFormatters": [
{
"scheme": "remotehub",
"formatting": {
"label": "${path}",
"separator": "/",
"workspaceSuffix": "GitHub"
}
}
]
}
}
25、customEditors
customEditors
是你的差距如何告诉 VS Code
它提供的自定义编辑器
"contributes": {
"customEditors": [
{
"viewType": "catEdit.catScratch",
"displayName": "Cat Scratch",
"selector": [
{
"filenamePattern": "*.cscratch"
}
],
"priority": "default"
}
]
}
customEditors
是一个数组,所以插件可以贡献多个自定义编辑器
viewType
- 自定义编辑器的唯一标识符
这就是VS Code
如何将package.json
中的自定义编辑器贡献与代码中的自定义编辑器实现联系起来。这在所有扩展中必须是唯一的,因此不要使用通用的viewType
,例如“preview”
,请确保使用对您的扩展而言唯一的视图类型,例如“viewType”:“myAmazingExtension.svgPreview”
displayName
- 在VS Code
的UI
中标识自定义编辑器的名称
display name
是在VScode UI
中向用户显示的selector
- 指定自定义编辑器对哪些文件处于活动状态
selector
(选择器)是一个或多个glob
模式的数组。这些glob
模式与文件名匹配,以确定是否可以对它们使用自定义编辑器。诸如*.png
之类的filenamePattern
将为所有PNG
文件启用自定义编辑器priority
- 优先级(可选)指定何时使用自定义编辑器
当资源打开时使用自定义编辑器的优先级控制。可能的值为:default
option