xmake-vscode外掛開發過程記錄

                                    

最近打算給xmake寫一些IDE和編輯器的整合外掛,發現vscode的編輯器外掛比較容易上手的,就先研究了下vscode的外掛開發流程,並且完成了xmake-vscode外掛的開發。

我們先來看幾張最後的效果圖:

語法高亮和自動補全

<img src="http://tboox.org/static/img/xmake/xmake-vscode-completion.gif" width="60%" />

狀態列

statusbar

要實現上面的效果,其實並不複雜,首先我們先來簡單介紹下,vscode的外掛開發的基本流程:

安裝外掛開發環境

安裝cnpm

由於國內環境比較複雜,直接用npm安裝也許很慢或者訪問不穩定,因此這裡先安裝了cnpm去預設使用淘寶的映象源。

$ npm install -g cnpm --registry=https://registry.npm.taobao.org

建立空工程

通過cnpm去安裝yo工具,用來建立一個vscode外掛的空工程

$ cnpm install -g yo generator-code
$ yo code

大體的原始碼結構如下:

<img src="http://tboox.org/static/img/xmake/xmake-vscode-yo-code.png" width="80%" />

選擇建立專案後有四個輸入和一個選擇:

輸入你擴充套件的名稱 xmake-vscode
輸入一個標誌(專案建立的檔名稱用這個)xmake-vscode
輸入對這個擴充套件的描述
輸入以後要釋出用到的一名稱(和以後再發布時候有一個名字是對應上的)tboox
是問你要不要建立一個git倉庫用於版本管理

建立完成後的空工程,我們可以用vscode直接開啟,然後進行除錯載入執行下:

<img src="http://tboox.org/static/img/xmake/xmake-vscode-debug.png" width="80%" />

載入起來後,敲F1開啟命令視窗,執行預設的hello world測試命令:

<img src="http://tboox.org/static/img/xmake/xmake-vscode-hello1.png" width="80%" />
<img src="http://tboox.org/static/img/xmake/xmake-vscode-hello2.png" width="80%" />

到此,一個簡答的demo外掛就搞定了,接下來我們簡單介紹下如何釋出這個外掛到vscode的market上去。

建立釋出者

首先我們需要在marketplace.visualstudio.com上註冊一個賬號,建立一個釋出者,這裡我取名為tboox

然後,我們需要在自己的賬號裡面,新增一個Personal Access Token(地址:https://[your name].visualstudio.com/_details/security/tokens

安裝好vsce後,我們先建立一個釋出者,這裡為tboox,輸入剛剛market賬號裡面提供的token進行繫結。

$ vsce create-publisher (publisher name)

構建釋出

最後,只需要通過下面命令進行打包或者釋出就行了,如果僅僅打個本地包,拖入vscode載入測試,可以執行:

$ vsce package

這將會生成一個類似xmake-vscode-0.0.1.vslx

這個時候,我們就可以在xmake-vscode on marketplace上看到你的外掛了,使用者也可以直接通過vscode進行搜尋和安裝使用。

<img src="http://tboox.org/static/img/xmake/xmake-vscode-market.png" width="60%" />

外掛開發詳解

外掛的載入機制

外掛通過工程根目錄extension.json中配置的activationEvents進行觸發,例如:

{
    "activationEvents": [
        "workspaceContains:xmake.lua",
        "onCommand:xmake.sayHello"
    ]
}

當vscode開啟帶有xmake.lua

上述程式碼,在載入外掛的時候,註冊sayHello

在建立的時候可以指定一個label名,用於區分不同的輸出通道,最後顯示的結果如下:

<img src="http://tboox.org/static/img/xmake/xmake-vscode-channel.png" width="60%" />

需要注意的是,必須執行log.show()

上面的程式碼,通過建立一個label名為xmake的獨立終端,然後傳送執行命令:xmake

上述配置,增加了三個配置項,都在xmake.

建立狀態列

狀態列上的按鈕是可以響應之前建立的那些命令的,例如:xmake.sayHello

createStatusBarItem中第二個引數4.5用於控制按鈕在狀態列上的佈局順序,建立好後,再設定下一些基礎屬性就行了,這裡按鈕的文字直接通過$(bug)

自定義語法高亮

語法高亮完全可以通過配置檔案來搞定,不用寫程式碼,當然也可以在程式碼中動態配置,這樣稍微繁瑣些。

xmake-vscode裡面需要處理工程xmake.lua描述檔案的語法高亮,因此這邊在package.json裡面先定義了一個叫xmake的語言型別,如果編輯器開啟xmake.lua

跟語法高亮相關的描述,都放置在/languages/xmake-grammars.json

自動補全的實現

程式碼的自動提示和補全比較麻煩下,需要寫個自定義的class,通過languages進行註冊:

vscode.languages.registerCompletionItemProvider("xmake", new Completion());

這裡我們定義了一個Completion類,註冊到xmake語言上去,xmake語言定義,就是剛才講的在package.json中的配置。

然後我們實現下這個Completion類:

export class Completion implements vscode.CompletionItemProvider {

    // 匹配當前輸入,提供需要補全的候選文字列表
    public provideCompletionItems(document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken): Thenable<vscode.CompletionItem[]> {

        // 獲取當前輸入的單詞文字
        let wordAtPosition = document.getWordRangeAtPosition(position);
        var currentWord = '';
        if (wordAtPosition && wordAtPosition.start.character < position.character) {
            var word = document.getText(wordAtPosition);
            currentWord = word.substr(0, position.character - wordAtPosition.start.character);
        }

        // 猜測匹配結果,返回候選列表
        return new Promise(function (resolve, reject) {
            Promise.all([
                getLuaKeywordsSuggestions(currentWord),
                getXMakeCommandsSuggestions(currentWord)
            ]).then(function (results) {
                var suggestions = Array.prototype.concat.apply([], results);
                resolve(suggestions);
            }).catch(err => { reject(err); });
        });
    }

    // 這裡可以對剛剛返回的候選文字列表在做二次處理,例如:增加詳細的文件描述資訊
    public resolveCompletionItem(item: vscode.CompletionItem, token: vscode.CancellationToken): Thenable<vscode.CompletionItem> {
        
        // 對每個候選文字增加文件描述
        return new Promise(function (resolve, reject) { 
            item.documentation = "xxxxxxxxxxx";
            resolve(item);
         });
    }
}

這部分程式碼比較多,就不完全貼出來了,完整實現,可參考:completion.ts

<img src="http://tboox.org/static/img/xmake/xmake-vscode-completion.gif" width="60%" />

結語

本文講述的一些vscode外掛程式碼都來自xmake-vscode,有興趣的同學可以直接參考原始碼,寫個自己的外掛。

關聯文章