SpeechRecognition: available() 靜態方法

語法

available(options)

引數

options

一個指定可用性檢查選項的物件。可能的屬性包括：

langs

一個包含一個或多個字串的陣列，其中包含 BCP 47 語言標籤，每個標籤代表一種要檢查可用性的語言。傳遞一個空的 langs 陣列不會丟擲錯誤，但返回值將始終解析為 unavailable。

processLocally 可選

一個布林值，指定是僅為 裝置上語音識別（true）還是為裝置上或遠端語音識別（false）檢查語言的可用性。預設值為 false。

注意：無法使用 available() 來保證遠端服務支援指定的語言。值為 false 意味著裝置上或遠端語音識別服務支援它們。

返回值

一個 Promise，它會解析為一個列舉值，指示指定語言是否可用於語音識別。

可能的值包括：

available

表示所有指定語言的支援都可用。

• 如果 processLocally 設定為 true，available 表示這些語言的語音識別在裝置上可用（所需的語言包已在使用者的計算機上下載並安裝）。
• 如果 processLocally 設定為 false，available 表示這些語言的語音識別在裝置上或遠端可用。

downloading

表示裝置上支援指定語言，並且至少一種語言的相關語言包正在下載中。僅在 processLocally 為 true 時相關。

downloadable

表示裝置上支援指定語言，但至少一種語言的相關語言包尚未下載。僅在 processLocally 為 true 時相關。

unavailable

表示至少一種指定語言的支援不可用。

• 如果 processLocally 設定為 true，unavailable 表示至少一種指定語言的裝置上語音識別不可用。
• 如果 processLocally 設定為 false，unavailable 表示至少一種指定語言的語音識別在裝置上或遠端不可用。

多個語言具有不同狀態時的最終返回值

即使在 langs 陣列中指定了多種語言，也只會返回一個狀態值。如果不同的指定語言具有不同的可用性狀態，則最終返回值是任何語言的“離 available 最遠”的狀態，其順序如下所示：

如果 processLocally 為 false

• 如果所有語言都 available，則返回 available。
• 否則，返回 unavailable。

如果 processLocally 為 true

• 如果所有語言都 available，則返回 available。
• 如果至少一種語言正在 downloading，則返回 downloading。
• 如果至少一種語言是 downloadable，則返回 downloadable。
• 如果至少一種語言是 unavailable，則返回 unavailable。

異常

InvalidStateError DOMException

當前文件未完全啟用。

SyntaxError DOMException

langs 中指定的字串有一個或多個不是有效的 BCP 47 語言標籤。

示例

檢查裝置上的可用性並安裝語言包

為了使裝置上的語音識別工作，瀏覽器必須安裝您要識別的語言的語言包。如果在指定 processLocally = true 後執行 start() 方法，但未安裝正確的語言包，則函式呼叫將失敗並出現 language-not-supported 錯誤。

要安裝正確的語言包，請確保遵循以下兩個步驟

1. 使用 available() 方法檢查語言包是否在使用者的計算機上可用。
2. 如果語言包不可用，則使用 SpeechRecognition.install() 方法進行安裝。

這些步驟使用以下程式碼片段處理：

startBtn.addEventListener("click", () => {
  // check availability of target language
  SpeechRecognition.available({ langs: ["en-US"], processLocally: true }).then(
    (result) => {
      if (result === "unavailable") {
        diagnostic.textContent = `en-US not available to download at this time. Sorry!`;
      } else if (result === "available") {
        recognition.start();
        console.log("Ready to receive a color command.");
      } else {
        diagnostic.textContent = `en-US language pack downloading`;
        SpeechRecognition.install({
          langs: ["en-US"],
          processLocally: true,
        }).then((result) => {
          if (result) {
            diagnostic.textContent = `en-US language pack downloaded. Try again.`;
          } else {
            diagnostic.textContent = `en-US language pack failed to download. Try again later.`;
          }
        });
      }
    },
  );
});

我們首先執行 available() 方法，指定一種語言（langs: ["en-US"]）來檢查可用性，並將 processLocally: true。我們測試返回值的三個不同可能性：

• 如果結果值為 unavailable，則表示沒有合適的語言包可供下載。我們還會向輸出列印一條相應的訊息。
• 如果結果值為 available，則表示語言包可在本地使用，因此可以開始識別。在這種情況下，我們執行 start() 並在應用程式準備好接收語音時將訊息記錄到控制檯。
• 如果該值是其他值（downloadable 或 downloading），我們列印一條診斷訊息，通知使用者語言包下載正在開始，然後執行 install() 方法來處理下載。

install() 方法的工作方式與 available() 方法類似，只是其選項物件只接受 langs 陣列。執行時，它會開始下載 en-US 語言包，並返回一個 Promise，該 Promise 解析為一個布林值，指示指定的語言包是否已成功下載並安裝（true）或未成功（false）。

此程式碼摘錄自我們的 裝置語音顏色更換器（即時執行演示）。有關完整說明，請參閱 使用 Web Speech API。

規範

瀏覽器相容性

另見

• Web Speech API
• 使用 Web Speech API
• SpeechRecognition.processLocally
• SpeechRecognition.install()