# webidl-conversions 中文文档

规范地址：https://npmcn.com/package/webidl-conversions/

版本：8\.0\.1
npm 元数据更新时间：2026-01-02T12:56:46.075Z
中文译文更新时间：2026-11-04T13:11:56.399Z
软件包许可：BSD-2-Clause

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/webidl-conversions
原文对照：https://npmcn.com/package/webidl-conversions/?lang=original
项目主页：https://github.com/jsdom/webidl-conversions#readme
源码仓库：https://github.com/jsdom/webidl-conversions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：23.5 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2014-08-15T20:52:19.528Z
- 最新版本发布：2026-01-02T12:56:45.580Z
- 近 30 天下载量：979689001（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 1 个）

## 中文简介

实现用于与JavaScript值之间转换的WebIDL算法

## 安装

```sh
npm install webidl-conversions
```

也可以使用：`pnpm add webidl-conversions`、`yarn add webidl-conversions`、`bun add webidl-conversions`

## README

# JavaScript值上的Web IDL类型转换

这个包在JavaScript中实现了根据给定值转换给定JavaScript值的算法 [Web IDL](https://webidl.spec.whatwg.org/) [类型](https://webidl.spec.whatwg.org/#idl-types)。

目标是您应该能够编写类似的代码

```js
"use strict";
const conversions = require("webidl-conversions");

function doStuff(x, y) {
    x = conversions["boolean"](x);
    y = conversions["unsigned long"](y);
    // actual algorithm code here
}
```

你的函数 `doStuff` 将表现为相同的Web IDL操作声明为

```webidl
undefined doStuff(boolean x, unsigned long y);
```

## API

此包的主模块的默认导出是一个具有各种方法的对象，每个方法对应于不同的Web IDL类型。在JavaScript值上调用每个方法时，将返回通过Web IDL转换规则后产生的新JavaScript值。（详情见下文。）另外，如果指定了Web IDL算法，该方法也可能抛出错误：例如 `conversions["float"](NaN)` [我会扔一个 `TypeError`](https://webidl.spec.whatwg.org/#js-float)。

每个方法还接受用于其他选项的第二个可选参数。对于抛出错误的转换方法，一个字符串选项 `{ context }` 可以在错误消息中提供更多信息。(例如, `conversions["float"](NaN, { context: "Argument 1 of Interface's operation" })` 会抛出带有消息的错误吗 `"Argument 1 of Interface's operation is not a finite floating-point value."`）

如果我们正在处理多个JavaScript领域（例如使用Node.js创建的领域） [虚拟机](https://nodejs.org/api/vm.html) 模块或HTML `iframe` 元素)，并且需要抛出来自另一个领域的异常，则可以提供对象选项 `globals` 包含以下属性：

```js
{
  globals: {
    Number,
    String,
    TypeError
  }
}
```

抛出异常时将使用这些特定的函数。

特定的转换也可以接受其他选项，其详细信息可以在下面找到。

## 转换实现

实现了Web IDL规范中所有基本类型的转换：

-   [`any`](https://webidl.spec.whatwg.org/#js-any)
-   [`undefined`](https://webidl.spec.whatwg.org/#js-undefined)
-   [`boolean`](https://webidl.spec.whatwg.org/#js-boolean)
-   [整数类型](https://webidl.spec.whatwg.org/#js-integer-types)，可以另外提供布尔选项 `{ clamp, enforceRange }` 作为第二个参数
-   [`float`](https://webidl.spec.whatwg.org/#js-float)， [`unrestricted float`](https://webidl.spec.whatwg.org/#js-unrestricted-float)
-   [`double`](https://webidl.spec.whatwg.org/#js-double)， [`unrestricted double`](https://webidl.spec.whatwg.org/#js-unrestricted-double)
-   [`DOMString`](https://webidl.spec.whatwg.org/#js-DOMString)，可以另外提供布尔选项 `{ treatNullAsEmptyString }` 作为第二个参数
-   [`ByteString`](https://webidl.spec.whatwg.org/#js-ByteString)， [`USVString`](https://webidl.spec.whatwg.org/#js-USVString)
-   [`object`](https://webidl.spec.whatwg.org/#js-object)
-   [缓冲源类型](https://webidl.spec.whatwg.org/#js-buffer-source-types)，其中一些可以另外提供布尔选项 `{ allowShared, allowResizable }` 作为第二个参数

此外，为了方便起见，实现了以下派生类型定义：

-   [`ArrayBufferView`](https://webidl.spec.whatwg.org/#ArrayBufferView)，可以另外提供布尔选项 `{ allowShared, allowResizable }` 作为第二个参数
-   [`BufferSource`](https://webidl.spec.whatwg.org/#BufferSource)
-   [`DOMTimeStamp`](https://webidl.spec.whatwg.org/#DOMTimeStamp)

派生类型，如可空类型、承诺类型、序列、记录等，不被这个库处理。你不妨调查一下 [webidl2js](https://github.com/jsdom/webidl2js) 项目。

### 关于…的笔记 `long long` 类型

这个 `long long` 和 `unsigned long long` Web IDL类型可以保存不能存储在JavaScript数字中的值。当我们在转换过程中使用BigInt时，转换仍然是准确的，但是在 `unsigned long long` 我们根本无法在JavaScript中表示一些可能的输出值。例如，转换JavaScript编号 `-1` 到Web IDL `unsigned long long` 应该产生Web IDL值吗 `18446744073709551615`。因为我们用JavaScript表示Web IDL值，所以我们不能表示 `18446744073709551615`，所以我们所能做的就是 `18446744073709551616` 作为输出。

为了减轻这种情况，我们可以从转换函数返回原始的BigInt值，但现在还没有实现。如果您的用例需要这样的精度， [提出一个问题](https://github.com/jsdom/webidl-conversions/issues/new)。

另一方面， `long long` 转换总是精确的，因为输入值永远不会比输出值更精确。

### 关于 `BufferSource` 类型

所有的 `BufferSource` 类型将在相关时抛出 `ArrayBuffer` 已经分离了。严格来说，这并不属于 [指定转换算法](https://webidl.spec.whatwg.org/#js-buffer-source-types)，而是……的一部分 [找参考/找副本](https://webidl.spec.whatwg.org/#ref-for-dfn-get-buffer-source-reference%E2%91%A0) 算法。为了方便和易于实现，我们在这里合并了它们，但如果将来需要将它们分开，请打开一个问题，以便我们进行调查。

## 背景

从概念上讲，这里实际发生的事情是相当奇怪的。让我们试着解释一下。

Web IDL有自己的类型系统。当人们在web平台规范中编写算法时，他们通常对web IDL值进行操作，即web IDL类型的实例。例如，如果他们为我们的 `doStuff` 手术以上，他们会治疗 `x` 的Web IDL值 [Web IDL类型 `boolean`](https://webidl.spec.whatwg.org/#idl-boolean)。关键是，他们会 _不_ 治疗 `x` 作为JavaScript变量，其值要么是JavaScript `true` 或 `false`。相反，它们在一个完全不同的类型系统中工作，有自己的规则。

与它的类型系统不同，Web IDL定义了 [“绑定”](https://webidl.spec.whatwg.org/#javascript-binding) 将类型系统转换为JavaScript。这包含如下规则：当您将JavaScript值传递给显示给定Web IDL操作的JavaScript方法时，如何将其转换为Web IDL值？例如，一个JavaScript `true` 传递到Web IDL的位置 `boolean` 参数变成了Web IDL `true`。但是，JavaScript `true` 在a的位置传递 [Web IDL `unsigned long`](https://webidl.spec.whatwg.org/#idl-unsigned-long) 成为Web IDL `1`。等等......。

最后，我们有了实际的实现代码。这通常是c++ ([或生锈](https://github.com/servo/servo))。当然，实现有自己的类型系统。因此，当他们实现Web IDL算法时，他们实际上并不使用Web IDL值，因为这些值在规范之外并不是“真实的”。相反，实现以这样一种方式应用Web IDL绑定规则，将传入的JavaScript值转换为c++值。例如，if代码在浏览器中调用 `doStuff(true, true)`，那么实现代码最终会收到一个c++ `bool` 包含 `true` 和一个c++ `uint32_t` 包含 `1`。

这样做的好处是，实现可以抽象出所有的转换逻辑，让Web IDL处理它，并专注于用已经提供的正确类型的值在c++中实现相关的方法。简而言之，这就是Web IDL的回报。

获得回报是我们的目标 _这_ 项目—但是用于JavaScript实现，而不是c++实现。也就是说，这个库旨在使JavaScript开发人员更容易编写行为类似于给定Web IDL操作的函数。所以从概念上讲，转换管道，它的一般形式是JavaScript值乘以Web IDL值乘以实现语言值，在这种情况下变成了JavaScript值乘以Web IDL值乘以JavaScript值。 中间步骤是执行所有逻辑的地方：JavaScript `true` 成为Web IDL `1` 在unsigned long上下文中，然后变成JavaScript `1`。

## 不要用这个

说真的，你为什么要用这个？你真的不应该。Web IDL是……奇怪的，您不应该模仿它的语义。如果您正在寻找一个通用的参数处理库，那么您应该找到一个具有比Web IDL更好规则的库。一般来说，你的JavaScript不应该试图变得更像Web IDL；如果有的话，我们应该修复Web IDL，使其更像JavaScript。

这个 _只有_ 应该使用它的人是那些试图创建web IDL中定义的web平台接口的忠实实现（或填充）的人。它的主要消费者是美国人 [jsdom](https://github.com/jsdom/jsdom) 项目。

## 常见问题

### webidl-conversions 是什么？

实现用于与JavaScript值之间转换的WebIDL算法

### 如何安装 webidl-conversions？

在项目目录运行 npm install webidl-conversions，或使用 pnpm add / yarn add / bun add。

### webidl-conversions 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/webidl-conversions 是否存在。

### webidl-conversions 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### webidl-conversions 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### webidl-conversions 可以商用吗？

webidl-conversions 使用 BSD-2-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### webidl-conversions 的下载量有多少？

根据 npm 官方下载统计，webidl-conversions 在 2026/10/06 – 2026/11/04 这 30 天内被下载 979,689,001 次，日均约 32,656,300 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### webidl-conversions 还在维护吗？

最新版本 8\.0\.1 发布于 2026/01/02（10 个月前）；至今共发布 18 个版本，其中过去 12 个月发布了 1 个；首次发布于 2014/08/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。