iT邦幫忙

第 12 屆 iT 邦幫忙鐵人賽

DAY 8
1
Software Development

自己用的工具自己做! 30天玩轉VS Code Extension之旅系列 第 8

Day08 | 提供使用者Extension的設定選項吧

大家好,我是韋恩,今天是鐵人賽的第八天。

今天,我們來客製化提供給套件使用者的extension個人設定,這個功能在實務上非常有幫助。準備好了嗎?

Workspace設定


Contribution Point裡,我們可以在configuration為key的物件中設定Workspace的Settings或者是User Settings。在Contribution Point註冊後,我們即可以在preference -> settings的ui上讓user選取或填寫我們的extension設定選項。User也可以透過直接編輯settings.json來配置我們的extension設定。

Workspace的Configutation設定語法概覽如下:

{
...
"contributes": {
        ...
        "configuration": {
          "title": "${Extension專案設定的主標題}",
          "properties": {
            "${套件的Namespace}.${設定選項名稱}": {
              "type": "${使用者輸入資料類型: boolean、string、number...}",
              "default": "${選項預設值}",
              "description": "${選項內容描述}",
              ...
            },
          }
        }
        ...
	},
...
}

Extension Configuration的JSON設定格式涵蓋了JSON Schema的設定方式。JSON Schema是一種對JSON設定檔格式的規範。我們可以直接使用JSON Schema規範內的Property Key來規範使用者可以輸入的資料型態、長度、選項...等等,但Configuration不支援JSON Schema的$refdefinition這些用於引用外部json檔案的設定,此處需留意。

除了JSON Schema的屬性來限制使用者輸入的資料以外,VSCode還提供了markdownDescriptions、deprecationMessage、 markdownDeprecationMessage、enumDescriptions、markdownEnumDescriptions...等等屬性,讓開發者可以讓使用者讀取到更多設定選項相關的訊息。

其中的markdownDescription,是我覺得相當貼心的一個設定,可以在value裡直接使用markdown語法,vscode會自動將markdown渲染出來,如下所示:

此處Markdown description的寫法請詳見今天的第一個範例喔!

好了,簡單介紹後,讓我們直接來練習這些配置與功能吧!練習才是掌握各項細節的最快途徑。

Day08練習:使用Configration提供客製選項吧!


環境準備


  • 使用yoman產生extension專案:
yo code
  • 依序輸入專案名稱、id等資訊

如果環境建立有問題,請再次參照之前的教學建立專案與環境喔!

Workspace設定練習:

首先,讓我們到contributes的commands屬性上方,在物件括弧裡輸入""

可以看到vscode自動補全各類contributes的屬性選項,讓我們選擇configuration

接下來,我們在configuration之後輸入:,會看到跳出兩個補全的屬性選項,

通常我們只會設一個extension title,所以此處我們選第二個選項。

選擇後的結果如上,讓我們繼續輸入我們的titleproperties下面的設定選項吧!

我們輸入title為day08-workspace,properties屬性下面鍵入"day08-workspace.input"做為第一個設定的標題。一樣的,我們再度利用自動補全來列出key值。

上面自動跳出可選的JSON Schema properties,但請注意$ref是不能使用的,記得不要選取這個選項喔!

這裡我們先選擇type,再利用自動補全列出可選的value值

好的,以上這些就是我們可以輸入的所有type的類型。之後就不一一演示了,請讀者練習,並完成下方這樣的設定吧!

一切精髓盡在配置中。

{
    ...
    "configuration":{
			"title": "Day08-Workspace",
			"properties": {
				"day08-workspace.input": {
					"type": "string",
					"default": "defaultValue",
					"description": "provide a input for accepting value"
				},
				"day08-workspace.inputNum": {
					"type": "number",
					"default": "1.001",
					"description": "provide a input for accepting number"
				},
				"day08-workspace.inputInt": {
					"type": "integer",
					"default": "1",
					"markdownDescription": "MarkdownDescription: provide a input for accepting integer, See the [VSCode Docs (https://code.visualstudio.com/api/references/contribution-points#contributes.configuration) for more details.\n - a: item1\n - b: itemb"
				},
				"day08-workspace.checkbox": {
					"type": "boolean",
					"default": "0",
					"description": "provide a checkbox"
				},
				"day08-workspace.dropdown": {
					"type": "string",
					"default": "defaultValue",
					"enum": [
						"optionA",
						"optionB",
						"optionC"
					],
					"description": "provide a dropdown and options",
					"enumDescriptions": [
						"description for option A",
						"description for option B",
						"description for option C"
					]
				},
				"day08-workspace.array": {
					"type": "array",
					"default": [
						"defaultValue"
					],
					"description": "array settings is only available at settings.json"
				},
				"day08-workspace.object": {
					"type": "object",
					"default": { 
						"key" : "defaultValue"
					},
					"description": "object settings is only available at settings.json"
				},
				"day08-workspace.null.a": {
					"type": null,
					"default": null,
					"description": "null settings for showing group feature"
				},
				"day08-workspace.null.b": {
					"type": null,
					"default": null,
					"description": "null settings for showing group feature"
				}
			}
    }
    ...
}

範例成果檢視


照以上輸入完後,我們按F5執行extension,並置user settings頁面的extension下方,可以找到VSCode的Day08-Workspace設定,並可以看到各個不同type型態對應的UI元件,是不是很有趣呢?

以上是第一個範例的成果展示,讓我們再這個範例元件上檢視幾個貼心的小功能吧!

  • 輸入錯誤型態跳出提示

當我們在元件輸入不合法的型態,輸入框下話自動跳出提示警告。此處我們設定的輸入框需為整數,不能有小數點。

  • 下拉選單選項描述

下拉選單的enum選項可以另外配置enumDescription,讓我們可以針對每一個選項提供個別的說明。除了enumDescription外,vscode特別準備了markdownEnumDescriptions,這裡故意不多做說明,希望讀者能夠動手練習,培養舉一反三的能力,進而對這些api運用自如!

範例元件有許多小細節,讀者們請務必動手玩玩看,從中熟悉api的設定跟小撇步。若有問題,請隨時在留言板發問,我會與您一銅解決單元練習時所遇到的問題,

取得使用者Workspace設定


好啦,現在,我們已經知道如何配置給使用者輸入資料的元件了。但作為一個extension開發者,我們會如何取得workspace的設定呢?為此,今天我們準備了另一個相關命令小練習,請讀者們按順序配置吧!

  • 設定Command:

首先,讓我們設定一個getSettings命令,如下所示:

{
    ...
    "contributes": {
		"commands": [
            {
				"command": "day08-workspace-api.getSettings",
				"title": "Day08: GetSettings"
			}
		]
	},
    ...
}

  • 專案extension.ts範例程式配置:

命令配置後,我們在extension.ts這裡,可以使用workspace下面的getConfiguration方法,提供給定的namespace取得設定。

import * as vscode from 'vscode';
​
export function activate(context: vscode.ExtensionContext) {
​
	console.log('Congratulations, your extension "day08-workspace-api" is now active!');
 
    let getCmd = vscode.commands.registerCommand('day08-workspace-api.getSettings', async () => {
			const workspaceSettings = vscode.workspace.getConfiguration('day08-workspace');
			console.log(workspaceSettings);
	});

	context.subscriptions.push(getCmd);
​
export function deactivate() {}
  • 執行Day08: GetSettings

執行命令後,我們可以看到取得的設定結果。

總結


總算結束啦,今天,我們練習配置了Workspace的各種選項,並利用簡單的命令取得了Workspace的Settings,Workspace設定是使用者常使用的功能,並且它的api使用仍有不少細節可以發掘喔!

明天,我們將會探討如何在本地儲存extension使用者的資料,也會更將其與workspace api做個比較說明,敬請期待吧,我們明天見,掰掰!

本日參考文件



上一篇
Day07 | 那些你可以自訂選項的Context Menu
下一篇
Day09 | Data Storage以及教學中沒有特別提及的小細節
系列文
自己用的工具自己做! 30天玩轉VS Code Extension之旅36

1 則留言

0
Homura
iT邦高手 1 級 ‧ 2020-12-25 17:47:49

感謝大大的教學文
我剛剛試了一下
發現GetConfigurtion是抓properties key前面的名稱
我直接只打了keyname
結果抓到的Configurtion內部一直是空的
可能有人會遇到一樣的問題
紀錄一下

錯誤示範

"properties": {
    "1": {
        "type": "string",
        "enum": [
            "a",
            "b",
            "c"
        ]
    },
    "2": {
        "type": "string",
        "enum": [
            "a",
            "b",
            "c"
        ]
    }
}

正確示範

"properties": {
    "test123.1": {
        "type": "string",
        "enum": [
            "a",
            "b",
            "c"
        ]
    },
    "test123.2": {
        "type": "string",
        "enum": [
            "a",
            "b",
            "c"
        ]
    }
}

Homura,感謝您的補充喔!

最近可能會晚一點回應,不好意思m(_ _)m

Homura iT邦高手 1 級 ‧ 2020-12-28 09:42:49 檢舉

缺乏咖啡因的韋恩
我也只是剛好碰到XD

我要留言

立即登入留言