WebTransport: createUnidirectionalStream() 方法

有限可用性

此功能不是基线，因为它在一些最广泛使用的浏览器中不起作用。

安全上下文：此功能仅在 安全上下文 (HTTPS) 中可用，并且在部分或所有 支持的浏览器 中可用。

注意：此功能在 Web Workers 中可用。

createUnidirectionalStream() 方法是 WebTransport 接口的方法，它异步打开一个单向流。

该方法返回一个 Promise，该 Promise 解析为一个 WritableStream 对象，可用于可靠地将数据写入服务器。

“可靠”是指保证数据的传输和顺序。这比 datagrams 提供更慢的传输速度（尽管比 WebSockets 快），但在可靠性和排序至关重要的场景中是必需的，例如聊天应用程序。

可以使用 sendOrder 选项指定创建的流中排队字节清空的相对顺序。如果设置了，则具有更高发送顺序的流中的排队字节保证在具有较低发送顺序的流中的排队字节之前发送。如果未设置顺序号，则发送字节的顺序取决于实现。但是请注意，即使来自更高发送顺序流的字节先发送，它们也可能不会先到达。

语法

js
createUnidirectionalStream()
createUnidirectionalStream(options)

参数

options 可选

一个可能具有以下属性的对象

sendOrder 可选

一个整数值，指定此流相对于其他已设置值的流的发送优先级。排队的字节将首先发送给具有更高值的流。如果未设置，则发送顺序取决于实现。

返回值

一个 Promise，它解析为一个 WebTransportSendStream 对象（这是一个 WritableStream）。

异常

InvalidStateError DOMException

如果在 WebTransport 关闭或失败时调用 createUnidirectionalStream()，则会抛出此异常。

示例

使用 createUnidirectionalStream() 方法获取 WritableStream 的引用。由此你可以 获取写入器 以允许数据写入流并发送到服务器。

使用 close() 方法在生成的 WritableStreamDefaultWriter 中关闭关联的 HTTP/3 连接。浏览器尝试在实际关闭关联连接之前发送所有挂起的數據。

js
async function writeData() {
  const stream = await transport.createUnidirectionalStream({
    sendOrder: "596996858",
  });
  const writer = stream.writable.getWriter();
  const data1 = new Uint8Array([65, 66, 67]);
  const data2 = new Uint8Array([68, 69, 70]);
  writer.write(data1);
  writer.write(data2);

  try {
    await writer.close();
    console.log("All data has been sent.");
  } catch (error) {
    console.error(`An error occurred: ${error}`);
  }
}

你还可以使用 WritableStreamDefaultWriter.abort() 来突然终止流。当使用 abort() 时，浏览器可能会丢弃任何尚未发送的挂起数据。

js
// ...

const stream = await transport.createUnidirectionalStream();
const writer = ws.getWriter();

// ...

writer.write(...);
writer.write(...);
await writer.abort();
// Not all the data may have been written.

规范

规范
WebTransport
# dom-webtransport-createunidirectionalstream

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅