iT邦幫忙

第 12 屆 iT 邦幫忙鐵人賽

DAY 5
0
Software Development

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

Day05 | 在Extension專案裡執行第一個Command命令吧

大家好,我是韋恩,今天是鐵人賽的第五天,今天,我們將開始第一個extension專案,並練習使用VSCode的Command命令。

開發環境配置


在開始前,請照下方指示正確設置自己的環境。

  1. 確認已安裝nodejs與npm:
node -v && npm -v 

如果正確安裝了以上兩者,會跳出兩行版本號資訊。

如未安裝兩者,請先至Nodejs官方網站下載。npm會隨著nodejs下載一併被安裝,有時候您可能使用過舊的npm,這時您可以使用以下指令更新它到最新版。

npm install -g npm@latest
  1. 安裝yoman

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

Yoman是一款流行已久的code generator,可以允許我們使用yoman設置專案的樣板,
並讓我們使用yo指令快速產生樣板專案。

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

VSCode官方已經發布了VSCode Yoman專案,並且定期更新,因此我們可以直接使用yo指令產生VSCode Extension,無需手動開發yoman樣板。

請使用以下指令安裝yoman與VSCode Extension Generator:

npm install -g yo generator-code

安裝yoman後,再次使用版本號指令確認有無正確安裝:

yo --version

使用yo快速產生第一個Extesnion專案


首先,於terminal進入一個要放置專案的資料夾,使用

yo code

指令,generator會跳出提示,讓我們選擇要產生的extension種類:

這些Extension選項的描述與說明如下:

Extension選項 描述
New Extension(Typescript) 產生使用typescript開發的extension專案
New Extension(Javascript) 產生使用javascript開發的extension專案
New Color Theme 配置VSCode介面顏色的擴充套件專案(詳見: Color Theme)
New Language Support 程式語言(Programming Languages)擴充套件
New Code Snippets 程式碼片段擴充套件
New Keymap 快捷鍵擴充套件,keymap讓使用者得以在vscode中使用vim、sublime等等不同編輯器的快捷鍵開發。
New Extension Pack 打包多個已發佈的extension,讓使用者一鍵快速安裝。
New Language Pack (Localization) 配置VSCode編輯器多國語氣的擴充套件。

請選擇第一個New Extension(Typescript)選項,選後yo會請我們輸入extensnion name

這裡我們輸入: day05-first-command

輸入完成後,會再輸入iddescription、是否要使用git、使用yarn還是npm開發,我們依序輸入如下:

輸入完成後,yoman即會開始幫我們產生extension,並使用npm或yarn安裝必須的node_modules。

全部完成後,在terminal輸入

cd day-05-first-command

讓terminal的根路徑位於專案資料夾。

Extension專案重點相關檔案介紹


現在,讓我們使用VSCode打開新產生的專案資料夾吧,打開後,我們會看到一個nodejs的typescript專案,結構如下:

    ├── .vscode
    │   ├── extensions.json
    │   ├── launch.json
    │   ├── settings.json
    │   └── tasks.json
    ├── node_modules
    ├── src
    │   ├── extension.ts
    │   └── test
    │       ├── runTest.ts
    │       └── suite
    │           ├── extension.test.ts
    │           └── index.ts
    ├── .eslintrc.json
    ├── .gitignore
    ├── .vscodeignore
    ├── CHANGELOG.md
    ├── README.md
    ├── package-lock.json
    ├── package.json
    ├── tsconfig.json
    └── vsc-extension-quickstart.md
  • workspace設定(位於.vscode資料夾下)
檔案名稱 說明
task.json 設定defaultBuild Task,用於compile extension專案的typescript程式。
launch.json 配置debug mode的兩個選項:Run extensionTest extension,用於執行extension主程式與相關測試程式,程式執行前,會先執行defulat buildTask。
settings.json extension專案的設定檔,此處的設定會覆蓋user settings跟default settings。
extensions.json 設定用於輔助extension專案安裝的extension recommendations list,此處推薦安裝eslint extension。
  • 主程式檔案: 位於src資料夾下方的extension.ts。
  • 測試程式:位於src/test資料夾下方的檔案。
  • .eslintrc.json: 用於extension專案的eslint設置。
  • .vscodeignore: 用於忽略不打包進發佈套件的專案檔案。
  • tsconfig.json: 用於專案ts compiler的設定選項。
  • package.json: 用於配置node相關依賴與相關npm script,在extension專案裡,package.json亦用於配置extension重要相關設定(詳見: Extension Manifest)
  • vsc-extension-quickstart.md:產生的extension專案的markdown說明文件。

Extension專案程式簡介


讓我們打開extension.ts吧,打開後可以看見extension.ts裡面有個
active function跟deactive function。

active function為extension程式的進入點。當extension被active事件啟動時,即會執行extension程式。

因此我們可以查看pakcage.json,package.json配置了activeEvents清單,可以看到清單裡列出跟active有關的設定activationEvents

   {
    ...
	"activationEvents": [
		"onCommand:day05-first-command.helloWorld"
	],
    ...
   }

activationEvents指定了一個hello worldcommand,此即是說,當使用者執行hello world command時,extension即會活躍並執行active function。

此處的onCommand語法為:

onCommand: ${commandId}

那麼,command的id是在哪裡配置的呢? 一樣是在package.json裡,我們可以到contributes屬性(Contribution Point: 詳見Contribution Point)下面查看:

{
    ...
	"contributes": {
		"commands": [
			{
				"command": "day05-first-command.helloWorld",
				"title": "Hello World"
			}
		]
	},
    ...
} 

可以看到在contrubutes屬性下面已經配置了commands清單,裡面條列著一個command設定,此處command設定的語法為

{
   /**
    * 被產生的Command會預設使用extension的id作為namespace,亦可自訂其他Namespace名稱
    */
   "command": ${自定義的command-id},
   "title": ${Command的標題內容}
}

當我們使用Command Palette搜尋Command並執行時,是使用Command的Title搜尋。

好,現在我們已經了解如何在Contribution Point設定簡單的Command id跟title,以及設定它為活躍extension的event。現在回到extension.ts的active function吧!

export function activate(context: vscode.ExtensionContext) {
    ...
	console.log('Congratulations, your extension "ithome" is now active!');
    ...
	let disposable = vscode.commands.registerCommand('day05-first-command.helloWorld', () => {
        ...
		vscode.window.showInformationMessage('Hello World from day05-first-command!');
	});
    ...
	context.subscriptions.push(disposable);
}

我們可以看到,active function裡面在extenions活躍後將註冊我們在Contribution Point那邊設定的command id,並且有一個callback函式,當我們配置的command執行之後,即會在vscode裡跳出顯示「 Hello World from day05-first-command! 」的訊息。

這個註冊過後的command函式(disposable)會再push進extension context裡面,如此當extension被關閉後,VSCode就可以自動釋放listen這個command的相關資源。

執行extension專案應用程式


讓我們來執行extension吧,vscode專案已經幫我們配置好了lanunch.json,因此我們可以在debug mode裡執行extension。讓我們點開左上角Activity bar的第四個icon,再點擊sidebar上方的Run Extension旁的執行按鈕開始extension吧!(此處的快捷鍵為F5)

執行後,vscode會開啟一個新的vscode的window視窗,window視窗上的title會註明這個視窗為[Extension Development Host],我們可以在這個視窗操作我們開發中的extension,並且使用中斷點偵錯。

  • 檢查已被註冊的command

先來檢查一下剛才註冊的command,在Contribution Point裡宣告的Command,一樣在Keyboard Shortcuts下方可以搜尋的到。讓我們照昨天的教學先進入keyboard shortcuts頁中,並在搜尋條上輸入day05,使用extension id來列出剛才註冊的command。

輸入後我們可以看到,Command已正確被註冊。

  • 執行註冊後的Command

現在,我們打開Command Palette,輸入hello world,使用註冊的Command Title查找到command。

然後,點擊下去,我們可以看到vscode的window正確跳出「 Hello World from day05-first-command! 」訊息。

然後,我們回到原本專案的Vscode Window,我們可以在專案的debug console檢視active function下面的console.log訊息。

結語

好啦,今天,我們已經建立並了解最基本的extension專案的架構,我們也註冊並執行了我們的第一個Command,明天我們來了解怎麼使用command api並且實際練習。

我們明天見,謝謝大家。

話說,今天的主題相當基本,可是居然花了我超過6000個字,我有很多想說的還沒說完啊啊! 從此處可以想見寫詳細的說明與文件真的相當的不容易呢,感謝所有文件跟教學的撰寫者們。

參考文件



上一篇
Day04 | Command命令,一切VSCode操作行為的根源
下一篇
Day06 | 用Command API來操控使用者的VSCode吧
系列文
自己用的工具自己做! 30天玩轉VS Code Extension之旅36

尚未有邦友留言

立即登入留言