在 WebNN API 中使用 TypeScript

TypeScript（TS）为 JavaScript 项目提供强大的类型能力，通过代码补全和编译时错误检查等功能提升开发效率。本指南介绍如何在项目中集成 WebNN API 的 TypeScript 类型定义。

概述

@webnn/types 包包含 WebNN API 的 TypeScript 声明文件（.d.ts），为 WebNN 规范中使用的方法、属性和返回值提供类型信息。

注意： 如果您使用的是 Transformers.js 或 ONNX Runtime Web 等 JavaScript 机器学习库，则无需使用 @webnn/types，因为它们自带类型定义。

为什么要使用类型定义？

没有类型定义时，TypeScript 会将 WebNN API 对象和方法视为 unknown 类型：

WebNN without TypeScript type definitions

图 1：没有类型定义时出现 unknown 类型错误

有了合适的类型定义，TypeScript 就能提供代码补全、参数校验和类型检查：

图 2：有类型定义时类型检查正常工作

安装

使用您偏好的包管理器，将类型定义安装为开发依赖：


# npm
npm install --save-dev @webnn/types
# yarn
yarn add --dev @webnn/types
# pnpm
pnpm add -D @webnn/types

配置

由于 @webnn/types 不在 DefinitelyTyped (@types) 之内，您需要显式配置 TypeScript 来识别这些类型。您有两种选项：

选项 1：在 `tsconfig.json` 中使用 `types`

tsconfig.json


{
  "compilerOptions": {
    "types": ["@webnn/types"]
  }
}

选项 2：在 `tsconfig.json` 中使用 `typeRoots`

tsconfig.json


{
  "compilerOptions": {
    "typeRoots": [
      "./node_modules/@webnn/types",
      "./node_modules/@types"
    ]
  }
}

图 3：tsconfig.json 中的配置

全局类型

配置完成后，WebNN 类型即可在项目中全局使用。您无需显式导入它们，TypeScript 会自动识别 navigator.ml 和 MLGraphBuilder 等 WebNN 接口。


// 无需导入 WebNN 类型，它们是全局可用的
async function runInference() {
  // TypeScript 将识别这些类型
  const ml:ML = navigator.ml;
  const context:MLContext = await ml.createContext();
  const builder:MLGraphBuilder = new MLGraphBuilder(context);
 
  const input:MLOperand = builder.input('input', {dataType: 'float32', shape: [1, 3, 224, 224]});
  const weights:MLOperand = builder.constant({dataType: 'float32', shape: [16, 3, 3, 3]}, new Float32Array(432));
 
  // 卷积参数的类型
  const options:MLConv2dOptions = {
    padding: [1, 1, 1, 1],
    strides: [1, 1],
    dilations: [1, 1],
    groups: 1
  };
  
  const conv:MLOperand = builder.conv2d(input, weights, options);
  const graph:MLGraph = await builder.build({output: conv});
  
  // 其余推理代码...
}

TypeScript 原生示例

如需完整的可运行示例，请参阅 WebNN TypeScript Vanilla Example 仓库，其中演示了：

WebNN TS 开发提示

使用 TypeScript 的自动补全来发现可用的方法和属性
利用参数类型检查来避免常见的 WebNN API 使用错误
TypeScript 接口将帮助您符合 WebNN 选项对象的预期结构
类型正确时，VSCode 和其他现代编辑器会为 WebNN API 方法显示文档提示