匯入自動完成和智慧型註冊

語言伺服器支援 URL 的自動完成。

本機匯入自動完成

當嘗試匯入相對模組規格說明符（以 ./ 或 ../ 開頭）時，Deno 認為可以執行的目錄和檔案（副檔名為 .ts、.js、.tsx、.jsx 或 .mjs）會提供匯入完成。

工作區匯入完成

當嘗試匯入未設定為登錄檔的遠端 URL（見下方）時，此擴充功能將提供已成為工作區一部分的遠端模組。

模組登錄檔完成

支援的模組登錄檔可以設定為自動完成。這提供了一種便利的方式，讓您在 IDE 的「舒適」環境中探索模組登錄檔。

自動偵測

預設情況下，Deno 語言伺服器會嘗試判斷伺服器是否支援完成建議。如果主機/來源未明確設定，它會檢查伺服器，如果它支援完成建議，系統會提示您選擇是否啟用。

您只應為您信任的登錄檔啟用此功能，因為遠端伺服器可能會提供模組建議，讓您執行不受信任的程式碼。

設定

設定自動完成登錄檔的設定

deno.suggest.imports.autoDiscover - 如果啟用，當語言伺服器偵測到未明確設定的新來源時，它會檢查該來源是否支援匯入完成，並提示您是否啟用。預設為 true。
deno.suggest.imports.hosts - 這些是已設定為提供匯入完成的來源。目標主機需要支援 Deno 匯入完成（詳見下方）。值是一個物件，其中金鑰為主機，而值則表示是否已啟用。例如
```
{
  "deno.suggest.imports.hosts": {
    "https://deno.land": true
  }
}
```

其運作方式如何？

在擴充功能和語言伺服器啟動時，Deno 將嘗試從任何已設定和啟用的主機擷取 /.well-known/deno-import-intellisense.json。此檔案提供必要的資料，以高度可設定的方式形成模組規格說明的自動完成（表示您不必綁定至任何特定模組註冊表，即可獲得豐富的編輯器體驗）。

當您建立或編輯模組規格說明時，Deno 將會前往並從主機擷取 URL 的其他部分，根據 JSON 設定檔中的設定而定。

當您完成模組規格說明時，如果尚未在本地快取，Deno 將嘗試從註冊表中擷取已完成的規格說明。

它是否適用於所有遠端模組？

否，因為擴充功能和 Deno 需要了解如何尋找模組。設定檔提供高度彈性的方式，讓人們描述如何建立 URL，包括支援語意版本控制（如果模組註冊表支援的話）。

登錄表支援匯入完成

為了支援 Deno 語言伺服器發現登錄表，登錄表需要提供一些事項

架構定義檔。此檔案需要位於 /.well-known/deno-import-intellisense.json。此檔案提供 Deno 語言伺服器查詢登錄表並建構匯入指定項所需的組態。
提供要提供給使用者以完成匯入指定項的值的一系列 API 端點。

組態架構

架構定義的 JSON 回應需要是一個具有兩個必要屬性的物件

"version" - 一個數字，必須等於 1 或 2。
"registries" - 一個登錄表物件陣列，定義如何為此登錄表建構模組指定項。

有一個 JSON 架構文件定義此架構，可作為 CLI 原始碼的一部分取得。

雖然 v2 支援比 v1 更多的功能，但它們是以非中斷方式導入的，而且語言伺服器會自動處理 v1 或 v2 版本，而不論在 "version" 鍵中提供的是哪個版本，因此技術上來說，一個登錄表可以宣稱自己是 v1 但使用所有 v2 功能。不過不建議這樣做，因為雖然目前沒有特定的分支來支援 v2 功能，但這並不表示未來不會有分支來支援 v3 或其他版本。

登錄

在組態架構中，"registries" 屬性是登錄陣列，這些登錄是包含兩個必要屬性的物件

"schema" - 字串，類似 Express 路徑比對表達式，定義如何於登錄上建立 URL。語法直接根據 path-to-regexp。例如，如果下列內容是登錄上 URL 的指定符
```
https://example.com/a_package@v1.0.0/mod.ts
```
Schema 值可能是類似這樣
```
{
  "version": 1,
  "registries": [
    {
      "schema": "/:package([a-z0-9_]*)@:version?/:path*"
    }
  ]
}
```
"variables" - 對於 schema 中定義的鍵，需要定義對應變數，以通知語言伺服器從模組指定符的哪個部分擷取完成。在上述範例中，我們有 3 個變數，分別是 package、version 和 path，因此我們預期每個變數都有變數定義。

變數

在組態架構中，"variables" 屬性是變數定義陣列，這些定義是具有兩個必要屬性的物件

"key" - 字串，比對 "schema" 屬性中的變數鍵名稱指定符。
"documentation" - 選擇性 URL，語言伺服器可以在其中擷取個別變數條目的文件。變數可以替換以建立最終 URL。具有單大括號格式（例如 ${variable}）的變數將新增為從字串中比對出的內容，而具有雙大括號格式（例如 ${{variable}}）的變數將百分比編碼為 URI 組成部分。

"url" - 語言伺服器可以擷取變數完成項的 URL。變數可以替換為建立 URL。格式為單一括弧的變數，例如 ${variable}，會從字串中新增為已配對，而格式為雙重括弧的變數，例如 ${{variable}}，會以 URI 組成部分編碼為百分比。如果變數包含 "key" 的值，則語言伺服器會支援部分模組的遞增要求，讓伺服器可以在使用者輸入變數值一部分時提供完成項。如果 URL 不是完全限定，則會使用架構檔案的 URL 作為基礎。在上述範例中，我們有三個變數，因此我們的變數定義可能會如下所示

{
  "version": 1,
  "registries": [
    {
      "schema": "/:package([a-z0-9_]*)@:version?/:path*",
      "variables": [
        {
          "key": "package",
          "documentation": "https://api.example.com/docs/packages/${package}",
          "url": "https://api.example.com/packages/${package}"
        },
        {
          "key": "version",
          "url": "https://api.example.com/packages/${package}/versions"
        },
        {
          "key": "path",
          "documentation": "https://api.example.com/docs/packages/${package}/${{version}}/paths/${path}",
          "url": "https://api.example.com/packages/${package}/${{version}}/paths/${path}"
        }
      ]
    }
  ]
}

URL 端點

每個 URL 端點的回應必須是 JSON 文件，其中包含字串陣列或完成項清單

interface CompletionList {
  /** The list (or partial list) of completion items. */
  items: string[];
  /** If the list is a partial list, and further queries to the endpoint will
   * change the items, set `isIncomplete` to `true`. */
  isIncomplete?: boolean;
  /** If one of the items in the list should be preselected (the default
   * suggestion), then set the value of `preselect` to the value of the item. */
  preselect?: string;
}

從上述範例延伸，URL https://api.example.com/packages 預期會傳回類似下列內容

[
  "a_package",
  "another_package",
  "my_awesome_package"
]

或類似下列內容

{
  "items": [
    "a_package",
    "another_package",
    "my_awesome_package"
  ],
  "isIncomplete": false,
  "preselect": "a_package"
}

而查詢 https://api.example.com/packages/a_package/versions 會傳回類似下列內容

[
  "v1.0.0",
  "v1.0.1",
  "v1.1.0",
  "v2.0.0"
]

或

{
  "items": [
    "v1.0.0",
    "v1.0.1",
    "v1.1.0",
    "v2.0.0"
  ],
  "preselect": "v2.0.0"
}

而查詢 https://api.example.com/packages/a_package/versions/v1.0.0/paths 會傳回類似下列內容

[
  "a.ts",
  "b/c.js",
  "d/e.ts"
]

或

{
  "items": [
    "a.ts",
    "b/c.js",
    "d/e.ts"
  ],
  "isIncomplete": true,
  "preselect": "a.ts"
}

多部分變數和資料夾

導覽大型檔案清單對使用者來說可能是一項挑戰。使用登錄 V2，語言伺服器會對傳回的項目進行一些特別處理，以簡化完成子資料夾中檔案路徑的作業。

當傳回的項目以 / 結尾時，語言伺服器會將其呈現給用戶端作為「資料夾」，並在用戶端中顯示。因此，希望提供類似下列結構的子導覽至資料夾的登錄

examples/
└─┬─ first.ts
  └─ second.ts
sub-mod/
└─┬─ mod.ts
  └─ tests.ts
mod.ts

並有一個類似於 /:package([a-z0-9_]*)@:version?/:path* 的架構，以及一個類似於 https://api.example.com/packages/${package}/${{version}}/${path} 的 path API 端點，將想要回應 /packages/pkg/1.0.0/ 的路徑

{
  "items": [
    "examples/",
    "sub-mod/",
    "mod.ts"
  ],
  "isIncomplete": true
}

以及 /packages/pkg/1.0.0/examples/ 的路徑

{
  "items": [
    "examples/first.ts",
    "examples/second.ts"
  ],
  "isIncomplete": true
}

這將允許使用者在取得資料夾中內容的清單之前，在 IDE 中選擇資料夾 examples，使其更容易瀏覽檔案結構。

文件端點

文件端點應傳回文件物件，其中包含與所要求實體相關的任何文件

interface Documentation {
  kind: "markdown" | "plaintext";
  value: string;
}

針對上述範例進行延伸，對 https://api.example.com/packages/a_package 的查詢將傳回類似於

{
  "kind": "markdown",
  "value": "some _markdown_ `documentation` here..."
}

架構驗證

當語言伺服器啟動（或延伸模組的組態已變更）時，語言伺服器將嘗試擷取並驗證組態中網域主機規格的架構組態。

驗證嘗試確保已定義的所有登錄都有效，這些架構中包含的變數已在變數中指定，且沒有定義未包含在架構中的額外變數。如果驗證失敗，則不會啟用登錄，且錯誤將記錄到 vscode 中的 Deno 語言伺服器輸出。

如果您是登錄維護者，需要協助、建議或設定登錄以進行自動完成，請隨時開啟問題，我們將嘗試提供協助。

已知登錄

以下是已知支援此架構的登錄清單。您只需將網域新增至 deno.suggest.imports.hosts，並將值設定為 true

https://deno.land/ - 第 3 方 /x/ 登錄和 /std/ 函式庫登錄皆可使用。
https://nest.land/ - 區塊編織上的 Deno 模組登錄。
https://crux.land/ - 永久存放小型指令碼的免費開源登錄。

匯入自動完成和智慧型註冊

本機匯入自動完成​

工作區匯入完成​

模組登錄檔完成​

自動偵測​

設定​

其運作方式如何？​

它是否適用於所有遠端模組？​

登錄表支援匯入完成​

組態架構​

登錄​

變數​

URL 端點​

多部分變數和資料夾​

文件端點​

架構驗證​

已知登錄​