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()