RTCStatsReport

实例属性

RTCStatsReport.size

返回 RTCStatsReport 对象中的项目数量。

实例方法

RTCStatsReport.entries()

返回一个新的 迭代器 对象，其中包含 RTCStatsReport 对象中每个元素的 [id, statistic-dictionary] 形式的双成员数组，按插入顺序排列。

RTCStatsReport.forEach()

按插入顺序，对 RTCStatsReport 对象中存在的每个键值对调用一次 callbackFn。如果向 forEach 提供了 thisArg 参数，它将用作每个回调的 this 值。

RTCStatsReport.get()

返回与传入的 id 关联的统计信息字典，如果不存在则返回 undefined。

RTCStatsReport.has()

返回一个布尔值，指示 RTCStatsReport 是否包含与指定的 id 关联的统计信息字典。

RTCStatsReport.keys()

返回一个新的 迭代器 对象，其中包含 RTCStatsReport 对象中每个元素的键（ID），按插入顺序排列。

RTCStatsReport.values()

返回一个新的 迭代器 对象，其中包含 RTCStatsReport 对象中每个元素的 值（统计信息对象），按插入顺序排列。

RTCStatsReport[Symbol.iterator]()

返回一个新的 迭代器 对象，其中包含 RTCStatsReport 对象中每个元素的 [id, statistic-dictionary] 形式的双成员数组，按插入顺序排列。

描述

从 RTCRtpReceiver.getStats()、RTCRtpSender.getStats() 和 RTCPeerConnection.getStats() 方法返回一个解析为 RTCStatsReport 的 Promise。对 RTCPeerConnection 调用 getStats() 可以让你指定是希望获取出站统计信息、入站统计信息还是整个连接的统计信息。getStats() 的 RTCRtpReceiver 和 RTCRtpSender 版本分别只返回入站和出站统计信息。

统计报告是一个只读的 类似 Map 的对象：一个有序字典，其属性是唯一标识用于生成特定统计信息集的 WebRTC 对象的 id 字符串，值是一个包含这些统计信息的字典对象。RTCStatsReport 可以像只读 Map 一样进行迭代和使用。

报告可能包含许多不同的统计类别，包括当前和远程端点之间对等连接的入站和出站统计信息、有关编解码器、证书和使用的媒体的信息等等。每种统计类别都以不同类型的统计信息字典对象提供，可以通过其 type 属性来识别。

常见实例属性

所有字典类型都具有以下属性

id

一个唯一标识用于生成统计信息集的对象的字符串。此值在报告之间（至少在连接生命周期内）保持不变。请注意，对于某些统计信息，ID 可能在浏览器之间以及后续连接（即使是与同一对等方）之间有所不同。

时间戳

一个高精度时间戳对象（DOMHighResTimeStamp），指示采样时间。许多报告的统计信息是累积值；时间戳允许计算任何两次报告之间、以任何所需报告速率下的速率和平均值。

type

一个字符串，其值指示对象包含的统计信息类型，例如 candidate-pair、inbound-rtp、certificate 等等。下文列出了 统计信息的类型及其对应的对象。

用户通常会迭代 RTCStatsReport，使用 forEach() 或 for...of 循环，并通过 type 属性选择感兴趣的统计信息。一旦使用 type 识别出特定的统计信息对象，随后就可以使用 id 属性结合 get() 来在不同时间获取相同的统计信息报告。

时间戳可用于计算连接生命周期内累积的统计信息的平均值。

统计信息类型

下表列出了统计信息 type 的值及其对应的字典。

示例

使用 forEach 循环迭代 RTCPeerConnection 的报告

此示例日志显示了如何记录本地 RTCRtpReceiver 的与视频相关的统计信息，该接收器负责接收流式媒体。

给定一个变量 myPeerConnection，它是 RTCPeerConnection 的一个实例，代码使用 await 等待统计信息报告，然后使用 RTCStatsReport.forEach() 进行迭代。然后，它过滤字典，只保留 type 为 inbound-rtp 且 kind 为 video 的报告。

const stats = await myPeerConnection.getStats();

stats.forEach((report) => {
  if (report.type === "inbound-rtp" && report.kind === "video") {
    // Log the frame rate
    console.log(report.framesPerSecond);
  }
});

使用 for...of 循环迭代 RTCRtpSender 的报告

此示例显示了如何迭代 RTCRtpSender 的出站统计信息。

代码遵循与上一个示例类似的模式，但通过 for...of 循环对 RTCStatsReport.values() 进行迭代，并过滤 type 为 outbound-rtp 的项。它假设你已经有一个名为“sender”的 RTCRtpSender 对象。

const stats = await sender.getStats();

for (const stat of stats.values()) {
  if (stat.type !== "outbound-rtp") continue;
  Object.keys(stat).forEach((statName) => {
    console.log(`${statName}: ${stat[statName]}`);
  });
}

规范

浏览器兼容性

另见

• WebRTC API
• RTCPeerConnection
• RTCPeerConnection.getStats()、RTCRtpReceiver.getStats() 和 RTCRtpSender.getStats()