程式化語言功能

程式化語言功能是由 vscode.languages.* API 驅動的一組智慧編輯功能。在 Visual Studio Code 中提供動態語言功能有兩種常見方式。讓我們以浮動提示為例

vscode.languages.registerHoverProvider('javascript', {
  provideHover(document, position, token) {
    return {
      contents: ['Hover Content']
    };
  }
});

如您在上方所見，vscode.languages.registerHoverProvider API 提供了一種簡單的方式來為 JavaScript 檔案提供浮動提示內容。在此擴充功能啟用後，每當您將滑鼠游標停留在某些 JavaScript 程式碼上時，VS Code 都會查詢所有 JavaScript 的 HoverProvider，並在浮動提示小工具中顯示結果。語言功能列表和下方的動畫 GIF 為您提供了一種簡單的方式來找到您的擴充功能所需的 VS Code API / LSP 方法。

另一種方法是實作一個語言伺服器，該伺服器使用 語言伺服器協定。其運作方式如下

• 擴充功能為 JavaScript 提供語言用戶端和語言伺服器。
• 語言用戶端就像任何其他 VS Code 擴充功能一樣，在 Node.js 擴充功能主機上下文中執行。當它被啟用時，它會在另一個程序中產生語言伺服器，並透過 語言伺服器協定 與其通訊。
• 您在 VS Code 中將滑鼠游標停留在 JavaScript 程式碼上
• VS Code 將浮動提示通知語言用戶端
• 語言用戶端向語言伺服器查詢浮動提示結果，並將其傳回 VS Code
• VS Code 在浮動提示小工具中顯示浮動提示結果

此過程看起來更複雜，但它提供了兩個主要優點

• 語言伺服器可以用任何語言編寫
• 語言伺服器可以重複使用，為多個編輯器提供智慧編輯功能

如需更深入的指南，請前往語言伺服器擴充功能指南。

語言功能列表

此列表包含每個語言功能的以下項目

• VS Code 中語言功能的說明圖
• 相關的 VS Code API
• 相關的 LSP 方法

提供診斷

診斷是一種指出程式碼問題的方式。

語言伺服器協定

您的語言伺服器將 textDocument/publishDiagnostics 訊息傳送至語言用戶端。此訊息攜帶資源 URI 的診斷項目陣列。

注意：用戶端不會要求伺服器提供診斷。伺服器會將診斷資訊推送至用戶端。

直接實作

let diagnosticCollection: vscode.DiagnosticCollection;

export function activate(ctx: vscode.ExtensionContext): void {
  ...
  ctx.subscriptions.push(getDisposable());
  diagnosticCollection = vscode.languages.createDiagnosticCollection('go');
  ctx.subscriptions.push(diagnosticCollection);
  ...
}

function onChange() {
  let uri = document.uri;
  check(uri.fsPath, goConfig).then(errors => {
    diagnosticCollection.clear();
    let diagnosticMap: Map<string, vscode.Diagnostic[]> = new Map();
    errors.forEach(error => {
      let canonicalFile = vscode.Uri.file(error.file).toString();
      let range = new vscode.Range(error.line-1, error.startColumn, error.line-1, error.endColumn);
      let diagnostics = diagnosticMap.get(canonicalFile);
      if (!diagnostics) { diagnostics = []; }
      diagnostics.push(new vscode.Diagnostic(range, error.msg, error.severity));
      diagnosticMap.set(canonicalFile, diagnostics);
    });
    diagnosticMap.forEach((diags, file) => {
      diagnosticCollection.set(vscode.Uri.parse(file), diags);
    });
  })
}

基本

回報開啟編輯器的診斷。至少，這需要在每次儲存時發生。更好的是，診斷應根據編輯器未儲存的內容計算。

進階

不僅回報開啟編輯器的診斷，還回報開啟資料夾中所有資源的診斷，無論它們是否曾在編輯器中開啟過。

顯示程式碼完成建議

程式碼完成提供與上下文相關的建議給使用者。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供完成功能，以及是否支援 completionItem\resolve 方法來為計算出的完成項目提供額外資訊。

{
    ...
    "capabilities" : {
        "completionProvider" : {
            "resolveProvider": "true",
            "triggerCharacters": [ '.' ]
        }
        ...
    }
}

直接實作

class GoCompletionItemProvider implements vscode.CompletionItemProvider {
    public provideCompletionItems(
        document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken):
        Thenable<vscode.CompletionItem[]> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(getDisposable());
    ctx.subscriptions.push(
        vscode.languages.registerCompletionItemProvider(
            GO_MODE, new GoCompletionItemProvider(), '.', '\"'));
    ...
}

基本

您不支援 resolve 提供器。

進階

您支援 resolve 提供器，這些提供器為使用者選取的完成建議計算額外資訊。此資訊會與選取的項目並排顯示。

顯示浮動提示

浮動提示顯示滑鼠游標下方符號/物件的相關資訊。這通常是符號的類型和描述。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供浮動提示。

{
    ...
    "capabilities" : {
        "hoverProvider" : "true",
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/hover 請求。

直接實作

class GoHoverProvider implements HoverProvider {
    public provideHover(
        document: TextDocument, position: Position, token: CancellationToken):
        Thenable<Hover> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerHoverProvider(
            GO_MODE, new GoHoverProvider()));
    ...
}

基本

顯示類型資訊，並在可用時包含文件。

進階

以與程式碼著色相同的樣式為方法簽章著色。

協助函式和方法簽章

當使用者輸入函式或方法時，顯示有關正在呼叫的函式/方法的資訊。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供簽章幫助。

{
    ...
    "capabilities" : {
        "signatureHelpProvider" : {
            "triggerCharacters": [ '(' ]
        }
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/signatureHelp 請求。

直接實作

class GoSignatureHelpProvider implements SignatureHelpProvider {
    public provideSignatureHelp(
        document: TextDocument, position: Position, token: CancellationToken):
        Promise<SignatureHelp> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerSignatureHelpProvider(
            GO_MODE, new GoSignatureHelpProvider(), '(', ','));
    ...
}

基本

確保簽章幫助包含函式或方法的參數文件。

進階

沒有其他事項。

顯示符號的定義

允許使用者直接在變數/函式/方法的使用位置查看變數/函式/方法的定義。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供跳到定義位置。

{
    ...
    "capabilities" : {
        "definitionProvider" : "true"
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/definition 請求。

直接實作

class GoDefinitionProvider implements vscode.DefinitionProvider {
    public provideDefinition(
        document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken):
        Thenable<vscode.Location> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerDefinitionProvider(
            GO_MODE, new GoDefinitionProvider()));
    ...
}

基本

如果符號不明確，您可以顯示多個定義。

進階

沒有其他事項。

尋找符號的所有參考

允許使用者查看特定變數/函式/方法/符號的所有原始碼位置。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供符號參考位置。

{
    ...
    "capabilities" : {
        "referencesProvider" : "true"
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/references 請求。

直接實作

class GoReferenceProvider implements vscode.ReferenceProvider {
    public provideReferences(
        document: vscode.TextDocument, position: vscode.Position,
        options: { includeDeclaration: boolean }, token: vscode.CancellationToken):
        Thenable<vscode.Location[]> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerReferenceProvider(
            GO_MODE, new GoReferenceProvider()));
    ...
}

基本

傳回所有參考的位置（資源 URI 和範圍）。

進階

沒有其他事項。

醒目提示文件中符號的所有出現位置

允許使用者查看開啟編輯器中符號的所有出現位置。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供符號文件位置。

{
    ...
    "capabilities" : {
        "documentHighlightProvider" : "true"
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/documentHighlight 請求。

直接實作

class GoDocumentHighlightProvider implements vscode.DocumentHighlightProvider {
    public provideDocumentHighlights(
        document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken):
        vscode.DocumentHighlight[] | Thenable<vscode.DocumentHighlight[]>;
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerDocumentHighlightProvider(
            GO_MODE, new GoDocumentHighlightProvider()));
    ...
}

基本

您傳回在編輯器文件中找到參考的範圍。

進階

沒有其他事項。

顯示文件中所有符號定義

允許使用者快速導航到開啟編輯器中的任何符號定義。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供符號文件位置。

{
    ...
    "capabilities" : {
        "documentSymbolProvider" : "true"
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/documentSymbol 請求。

直接實作

class GoDocumentSymbolProvider implements vscode.DocumentSymbolProvider {
    public provideDocumentSymbols(
        document: vscode.TextDocument, token: vscode.CancellationToken):
        Thenable<vscode.SymbolInformation[]> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerDocumentSymbolProvider(
            GO_MODE, new GoDocumentSymbolProvider()));
    ...
}

基本

傳回文件中所有符號。定義符號的種類，例如變數、函式、類別、方法等。

進階

沒有其他事項。

顯示資料夾中所有符號定義

允許使用者快速導航到 VS Code 中開啟的資料夾（工作區）中任何位置的符號定義。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供全域符號位置。

{
    ...
    "capabilities" : {
        "workspaceSymbolProvider" : "true"
        ...
    }
}

此外，您的語言伺服器需要回應 workspace/symbol 請求。

直接實作

class GoWorkspaceSymbolProvider implements vscode.WorkspaceSymbolProvider {
    public provideWorkspaceSymbols(
        query: string, token: vscode.CancellationToken):
        Thenable<vscode.SymbolInformation[]> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerWorkspaceSymbolProvider(
            new GoWorkspaceSymbolProvider()));
    ...
}

基本

傳回開啟資料夾中原始碼定義的所有符號。定義符號的種類，例如變數、函式、類別、方法等。

進階

沒有其他事項。

錯誤或警告的可能動作

在錯誤或警告旁邊向使用者提供可能的更正動作。如果有可用的動作，則錯誤或警告旁邊會出現一個燈泡。當使用者點擊燈泡時，會顯示可用程式碼動作的列表。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供程式碼動作。

{
    ...
    "capabilities" : {
        "codeActionProvider" : "true"
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/codeAction 請求。

直接實作

class GoCodeActionProvider implements vscode.CodeActionProvider<vscode.CodeAction> {
    public provideCodeActions(
        document: vscode.TextDocument, range: vscode.Range | vscode.Selection,
        context: vscode.CodeActionContext, token: vscode.CancellationToken):
        Thenable<vscode.CodeAction[]> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerCodeActionsProvider(
            GO_MODE, new GoCodeActionProvider()));
    ...
}

基本

為錯誤/警告更正動作提供程式碼動作。

進階

此外，提供原始碼操作動作，例如重構。例如，提取方法。

CodeLens - 在原始碼中顯示可操作的上下文資訊

向使用者提供可操作的上下文資訊，這些資訊與原始碼穿插顯示。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供 CodeLens 結果，以及是否支援 codeLens\resolve 方法將 CodeLens 繫結到其命令。

{
    ...
    "capabilities" : {
        "codeLensProvider" : {
            "resolveProvider": "true"
        }
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/codeLens 請求。

直接實作

class GoCodeLensProvider implements vscode.CodeLensProvider {
    public provideCodeLenses(document: TextDocument, token: CancellationToken):
        CodeLens[] | Thenable<CodeLens[]> {
    ...
    }

    public resolveCodeLens?(codeLens: CodeLens, token: CancellationToken):
         CodeLens | Thenable<CodeLens> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerCodeLensProvider(
            GO_MODE, new GoCodeLensProvider()));
    ...
}

基本

定義文件中可用的 CodeLens 結果。

進階

透過回應 codeLens/resolve 將 CodeLens 結果繫結到命令。

顯示色彩裝飾器

允許使用者預覽和修改文件中的色彩。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供色彩資訊。

{
    ...
    "capabilities" : {
        "colorProvider" : "true"
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/documentColor 和 textDocument/colorPresentation 請求。

直接實作

class GoColorProvider implements vscode.DocumentColorProvider {
    public provideDocumentColors(
        document: vscode.TextDocument, token: vscode.CancellationToken):
        Thenable<vscode.ColorInformation[]> {
    ...
    }
    public provideColorPresentations(
        color: Color, context: { document: TextDocument, range: Range }, token: vscode.CancellationToken):
        Thenable<vscode.ColorPresentation[]> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerColorProvider(
            GO_MODE, new GoColorProvider()));
    ...
}

基本

傳回文件中所有色彩參考。為支援的色彩格式（例如 rgb(...)、hsl(...)）提供色彩呈現。

進階

沒有其他事項。

格式化編輯器中的原始碼

為使用者提供格式化整個文件的支援。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供文件格式化。

{
    ...
    "capabilities" : {
        "documentFormattingProvider" : "true"
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/formatting 請求。

直接實作

class GoDocumentFormatter implements vscode.DocumentFormattingEditProvider {
    provideDocumentFormattingEdits(
        document: vscode.TextDocument, options: vscode.FormattingOptions, token: vscode.CancellationToken)
        : vscode.ProviderResult<vscode.TextEdit[]> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerDocumentFormattingEditProvider(
            GO_MODE, new GoDocumentFormatter()));
    ...
}

基本

不提供格式化支援。

進階

您應始終傳回導致原始碼格式化的最小可能文字編輯。這對於確保正確調整診斷結果等標記且不會遺失至關重要。

格式化編輯器中選取的行

為使用者提供格式化文件中選取行範圍的支援。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供行範圍的格式化支援。

{
    ...
    "capabilities" : {
        "documentRangeFormattingProvider" : "true"
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/rangeFormatting 請求。

直接實作

class GoDocumentRangeFormatter implements vscode.DocumentRangeFormattingEditProvider{
    public provideDocumentRangeFormattingEdits(
        document: vscode.TextDocument, range: vscode.Range,
        options: vscode.FormattingOptions, token: vscode.CancellationToken):
        vscode.ProviderResult<vscode.TextEdit[]> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerDocumentRangeFormattingEditProvider(
            GO_MODE, new GoDocumentRangeFormatter()));
    ...
}

基本

不提供格式化支援。

進階

您應始終傳回導致原始碼格式化的最小可能文字編輯。這對於確保正確調整診斷結果等標記且不會遺失至關重要。

在使用者輸入時逐步格式化程式碼

為使用者提供在輸入時格式化文字的支援。

注意：使用者設定 editor.formatOnType 控制原始碼是否在使用者輸入時格式化。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供使用者輸入時的格式化。它還需要告訴用戶端應該在哪些字元上觸發格式化。moreTriggerCharacters 是選用的。

{
    ...
    "capabilities" : {
        "documentOnTypeFormattingProvider" : {
            "firstTriggerCharacter": "}",
            "moreTriggerCharacter": [";", ","]
        }
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/onTypeFormatting 請求。

直接實作

class GoOnTypingFormatter implements vscode.OnTypeFormattingEditProvider{
    public provideOnTypeFormattingEdits(
        document: vscode.TextDocument, position: vscode.Position,
        ch: string, options: vscode.FormattingOptions, token: vscode.CancellationToken):
        vscode.ProviderResult<vscode.TextEdit[]> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerOnTypeFormattingEditProvider(
            GO_MODE, new GoOnTypingFormatter()));
    ...
}

基本

不提供格式化支援。

進階

您應始終傳回導致原始碼格式化的最小可能文字編輯。這對於確保正確調整診斷結果等標記且不會遺失至關重要。

重新命名符號

允許使用者重新命名符號並更新符號的所有參考。

語言伺服器協定

在對 initialize 方法的回應中，您的語言伺服器需要宣告它提供重新命名功能。

{
    ...
    "capabilities" : {
        "renameProvider" : "true"
        ...
    }
}

此外，您的語言伺服器需要回應 textDocument/rename 請求。

直接實作

class GoRenameProvider implements vscode.RenameProvider {
    public provideRenameEdits(
        document: vscode.TextDocument, position: vscode.Position,
        newName: string, token: vscode.CancellationToken):
        Thenable<vscode.WorkspaceEdit> {
    ...
    }
}

export function activate(ctx: vscode.ExtensionContext): void {
    ...
    ctx.subscriptions.push(
        vscode.languages.registerRenameProvider(
            GO_MODE, new GoRenameProvider()));
    ...
}

基本

不提供重新命名支援。

進階

傳回需要執行的所有工作區編輯列表，例如包含符號參考的所有檔案中的所有編輯。