iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 11
0
Software Development

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

Day11 | 那些跟extension開發脫不了關係的window命名空間api

大家好,我是韋恩,今天讓我們來看一下vscode在window的namespace底下的api。目的是把握這些api設計的組織與全貌,幫助我們理解與統合之前與接下來會學習到的內容。

window命名空間API概覽


在昨天的使用情境介紹裡,我們使用了在VSCode API的

  • 狀態欄物件: vscode.window.createStatusBarItem

  • 使用者輸入框: vscode.window.showInputBox

  • 下拉選單: vscode.window.showQuickPick

  • 通知訊息:vscode.window.showInformationMessage

這些api都隸屬於window命名空間底下。

在vscode的window命名空間底下的api,不僅提供了當前vscode的window、terminal、editor、colorTheme等狀態讓我們訪問,同時包含了許多vscode視窗裡的互動元件:

從昨天的使用的狀態欄,到sidebar的explorer的樹狀選單、讓我們能在vscode裡使用客製化元件的webview,以及panel底下用於輸出訊息的output跟我們常用terminal,都可以在vscode.window底下找到對應的api進行操作。

因此掌握跟使用window下面的api將會對我們的extension開發幫助很大,我們今天會先對這些可用的api做了解,並於明天針對重點詳細的說明。

讓我們先來看VSCode API文件,並點擊右側的window導航到window命名空間的段落。


[圖片來源:VSCode官網截圖]

這裡的文件內容,其實跟我們在VSCode裡自動補全看到的內容一模一樣,均由VSCode類型定義檔所生成的,唯其UI更為精美且易於閱讀。

Window命名空間API分類


整個window namespace的api文件分為三大部分:

  1. Variable:

    此處的api,用於取得當前colorTheme、window、textEditor、terminal的狀態與當前活躍(active)中的(termainal、textEditor)物件。terminal等物件底下亦提供sendText等方法讓我們與其進行操作,如底下範例:

const terminal = vscode.window.activeTerminal;
terminal?.sendText('git branch');

我們會取得當前使用者在VSCode開啟的Terminal物件,並可以使用sendText方法對使用者當前的terminal執行git branch的指令,非常好用!

  1. Event:

    event底下提供對當前colorTheme、window、textEditor、terminal進行監聽的方法,讓我們可以在這些對象狀態發生改變時對其做些處理。如以下示例:


let terminal = vscode.window.activeTerminal;

vscode.window.onDidChangeActiveTerminal((activeTerminal) => {
    terminal = activeTerminal;
});

vscode會透過window.onDidChangeActiveTerminal方法,監聽編輯器是否切換當前terminal,並傳給我們當前active的terminal給我們使用。如此,當我們再次對terminal物件使用sendText方法執行指令時,就不會對被切換掉的terminal執行指令,而是會正確的在當前開啟的terminal中執行指令。

  1. Function:

    底下提供各類創建元件的方法與顯示提示訊息的message彈窗。筆者將其歸納為幾大類,方便讀者理解:

  • 創建元件類:諸如createWebview、createStatusBarItem、createQuickPick、createInputBox、createOutputChannel、createTerminal、createTreeView。

createXXX的方法會創建物件,並可以在創建的物件上監聽事件或綁定相關command(如statusBarItem)等等。以createInputBox為例,我們會這樣操作api:

const input = vscode.window.createInputBox();

input.prompt = 'Enter your message';

input.title = 'message title';

input.value = 'default value';

input.onDidChangeValue((value) => {
    vscode.window.showInformationMessage(`changed value: ${value}`);
});

input.onDidAccept((value) => {
    input.hide();
});

input.show();

從上面的createInputBox示例,可以看到創建類的api起手式會先create一個物件,在設定物件的屬性,並可以監聽這個物件的事件,並在事件發生後的callback函數內執行對應操作。了解這些api操作的方式對於理解一些強大元件的用法(比如說webview),會有相當幫助,希望讀者們都能順利抓到重點。

除了使用create方法創建元件之後,如Treeview之類的元件還可以使用registerTreeDataProvider等方法創建元件,底下是一個簡單示例:


class DataProvider implements vscode.TreeDataProvider<TreeItem> {

	onDidChangeTreeData?: vscode.Event<any> | undefined;
	
    getTreeItem(element: any): vscode.TreeItem | Thenable<vscode.TreeItem> {
		...
	}
	
    getChildren(element?: any): vscode.ProviderResult<any[]> {
		...
	}
}

vscode.window.registerTreeDataProvider(
	'newTreeVIewId',
	new DataProvider()
);

當我們使用registerDataProvider,我們需要先實作一個dataProvider的class,再new出這個provider的class提供給這個register方法使用。

許多創建類的元件功能強大且複雜,尤其是Treevie與Webview,我們將於明天開始深入講解。

  • 顯示訊息、互動元件類:諸如showErrorMessage、showInformationMessage、showInputBox、showQuickPick、showSaveDialog、showTextDocument、showWarningMessage、showWorkspaceFolderPick、withProgress(顯示進度)。

showXXX的方法則會回傳Thenable讓我們處理用戶點擊、輸入的非同步行為,並取得用戶輸入、點擊結果。如昨天之前使用過的showInputBox


let disposable = vscode.commands.registerCommand('extenionId.commandName'), async () => {
  const inputValue = await vscode.window.showInputBox({
      value: 'defaultValue'
  });
  vscode.window.showInformationMessage(`Enter value: ${inputValue}`);
});

Thenable的用法與Promise雷同,相信有ES6語法基礎的讀者們可以很容易地掌握。如對範例中的語法有問題,請在底下留言,我會試著幫您解答。

結語


好的,以上是就是今天window命名空間api的概覽介紹,相信大家讀後會對vscode的window api的組織跟用法有更多的認識,不再只是一個api一個api記住,更能把握住重點。

明天我們會詳細講解創建元件類的api,希望大家都能收穫滿滿,我們明天見,謝謝大家!

參考文件



上一篇
Day10 | 你問我答,Extension與使用者的互動流程
下一篇
Day12 | 打造VSCode上的TreeView樹狀選單 (一) - 元件基本用法介紹
系列文
自己用的工具自己做! 30天玩轉VS Code Extension之旅36

尚未有邦友留言

立即登入留言