WebTransport

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

安全上下文: 此项功能仅在一些支持的浏览器安全上下文(HTTPS)中可用。

备注: 此特性在 Web Worker 中可用。

WebTransport APIWebTransport 接口提供了使用户代理能够连接到 HTTP/3 服务器,启动(单向或双向的)可靠和不可靠传输,并在不再需要时关闭连接的功能。

构造函数

WebTransport()

创建新的 WebTransport 对象实例。

实例属性

closed 只读

返回一个在传输关闭时兑现的 promise。

datagrams 只读

返回一个可用于发送和接收数据报的 WebTransportDatagramDuplexStream 实例。

congestionControl 只读 实验性

返回一个指示应用程序在发送数据时对高吞吐量或低延迟的偏好的字符串。

incomingBidirectionalStreams 只读

表示服务器打开的一个或多个双向流。返回 WebTransportBidirectionalStream 对象(每个对象都可以用于从服务器读取数据并将数据写回服务器)的 ReadableStream

incomingUnidirectionalStreams 只读

表示服务器打开的一个或多个单向流。返回 WebTransportReceiveStream 对象(每个对象都可以用于从服务器读取数据)的 ReadableStream

ready 只读

返回一个会在传输准备就绪时兑现的 promise。

reliability 只读 实验性

返回一个指示连接是否仅支持可靠传输,或者它是否还支持不可靠传输(例如 UDP)的字符串。

实例方法

close()

关闭正在进行的 WebTransport 会话。

createBidirectionalStream()

异步打开一个双向流(WebTransportBidirectionalStream),该流可用于从服务器读取数据并将数据写回服务器。

createUnidirectionalStream()

异步打开一个单向流(WebTransportSendStream),该流可用于向服务器写入数据。

getStats() 实验性

异步返回一个 Promise,其会兑现一个包含 HTTP/3 连接统计信息的对象。

示例

以下示例代码展示了如何将 HTTP/3 服务器的 URL 传递给 WebTransport() 构造函数以连接到该服务器。注意,方案需要是 HTTPS,且需要明确指定端口号。一旦 WebTransport.ready promise 兑现,你就可以开始使用连接。

js
async function initTransport(url) {
  // 初始化传输的连接
  const transport = new WebTransport(url);

  // 连接一旦成功兑现,就可以开始使用
  await transport.ready;
  return transport;
}

你可以通过等待 WebTransport.closed promise 的兑现来响应连接关闭。WebTransport 操作返回的错误是 WebTransportError 类型的,除了标准的 DOMException 集合之外,还包含其他数据。

以下的 closeTransport() 方法展示了一种可能的实现方式。在 try...catch 块中,它使用 await 等待 closed promise 的兑现或拒绝,然后报告连接是因为意外关闭还是因为错误关闭。

js
async function closeTransport(transport) {
  // 响应连接的关闭
  try {
    await transport.closed;
    console.log(`${url} 的 HTTP/3 连接已正常关闭。`);
  } catch (error) {
    console.error(`${url} 的 HTTP/3 连接由于 ${error} 而被关闭。`);
  }
}

我们可以在自己的异步函数中调用上面的异步函数,如下所示。

js
// 使用传输
async function useTransport(url) {
  const transport = await initTransport(url);

  // 使用传输对象来发送和接收数据
  // ……

  // 在完成时关闭传输
  await closeTransport(transport);
}

const url = "https://example.com:4999/wt";
useTransport(url);

参见单独的属性和方法页面以获取其他示例代码。

规范

Specification
WebTransport
# web-transport

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
WebTransport
WebTransport() constructor
options.allowPooling parameter
Experimental
options.congestionControl parameter
Experimental
options.requireUnreliable parameter
Experimental
options.serverCertificateHashes parameter
BYOB reader support
close
closed
congestionControl
Experimental
createBidirectionalStream
options.sendOrder parameter
Experimental
createUnidirectionalStream
BYOB reader support
options.sendOrder parameter
Experimental
datagrams
getStats
Experimental
incomingBidirectionalStreams
incomingUnidirectionalStreams
ready
reliability
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
User must explicitly enable this feature.

参见