web-vitals Utils
web-vitals 库是一个小巧（压缩后约2K）、模块化的库，用于在实际用户上测量所有 Web Vitals 指标，以准确匹配 Chrome 测量它们的方式以及将它们报告给其他 Google 工具
runOnce
export const runOnce = (cb: () => void) => {
// 执行一次回调函数
let called = false;
return () => {
if (called) return;
cb();
called = true;
};
};
onHidden
export const onHidden = (cb: () => void) => {
// watch页面后台状态改变时执行回调函数
document.addEventListener('visibilitychange', () => {
if (document.visibilityState === 'hidden') {
cd();
}
});
};
whenActivated
// 当文档处于预渲染状态时（document.prerendering 为 true），它不会立即执行传入的 callback 回调函数。相反，它添加了一个事件监听器，监听 prerenderingchange 事件。这个事件在文档的预渲染状态改变时触发。一旦预渲染状态改变，回调函数将被执行。
// 当文档不处于预渲染状态时，回调函数将立即执行。
export const whenActivated = (callback: () => void) => {
if (document.prerendering) {
addEventListener('prerenderingchange', () => callback(), true);
} else {
callback();
}
};
*whenIdle
// “在下一次空闲时段运行传入的回调函数，或hidden立即执行”
// window.requestIdleCallback() 方法插入一个函数，这个函数将在浏览器空闲时期被调用。这使开发者能够在主事件循环上执行后台和低优先级工作，而不会影响延迟关键事件，如动画和输入响应。
export const whenIdle = (cb: () => void): number => {
const rIC = self.requestIdleCallback || self.setTimeout;
let handle = -1;
cb = runOnce(cb); // 防止重复触发
if (document.visibilityState === 'hidden') {
cb();
} else {
handle = rIC(cb);
onHidden(cb); // 防止hiden导致requestIdleCallback没执行， 而且防止这里的重复触发
}
return handle;
};
*doubleRAF
// 通常用于优化动画效果，减少画面的撕裂现象和不必要的计算。
// cb 函数将在下一次重绘之后的下一次重绘之前执行，也就是在两次重绘周期之间执行。
// 这种用法确保了 cb 函数不会干扰浏览器的重绘过程，并且能够在浏览器的两次重绘之间稳定执行，这对于创建平滑的动画和减少性能问题非常有用。
export doubleRAF = (cb: ()=>unknown) => {
return requestAnimationFrame(() => requestAnimationFrame(cb));
}
generateUniqueID
// 生成唯一ID
export const generateUniqueID = () => {
return `v4-${Date.now()}-${Math.floor(Math.random() * (9e12 - 1)) + 1e12}`;
};
*getNavigationEntry
// https://developer.mozilla.org/zh-CN/docs/Web/API/Performance
// Performance 接口可用于获取当前页面中与性能相关的信息。
// getEntries() 对于给定的 filter，此方法返回 PerformanceEntry 对象数组。
// PerformanceNavigation 对象提供了在指定的时间段里发生的操作相关信息，包括页面是加载还是刷新、发生了多少次重定向等等。Not available in workers.
export const getNavigationEntry = (): PerformanceNavigationTiming | void => {
const navigationEntry =
self.performance &&
performance.getEntriesByType &&
performance.getEntriesByType('navigation')[0];
// Check to ensure the `responseStart` property is present and valid.
// In some cases no value is reported by the browser (for
// privacy/security reasons), and in other cases (bugs) the value is
// negative or is larger than the current page time. Ignore these cases:
// https://github.com/GoogleChrome/web-vitals/issues/137
// https://github.com/GoogleChrome/web-vitals/issues/162
// https://github.com/GoogleChrome/web-vitals/issues/275
if (
navigationEntry &&
navigationEntry.responseStart > 0 &&
navigationEntry.responseStart < performance.now()
) {
return navigationEntry;
}
};
// response
// {
// "name": "http://localhost:8099/#/", // 页面地址，表示此次导航的类型和目的地。
// "entryType": "navigation", // 条目类型，这里是 'navigation'，表示这是一个导航条目。
// "startTime": 0, // 条目开始的时间点，相对于页面加载开始时的时间戳。
// "duration": 3649.2999999523163, // 页面加载的总持续时间，从页面开始加载到完全加载完成的时间。
// "initiatorType": "navigation", // 发起类型，这里是 'navigation'，表示页面是通过导航启动的。
// "deliveryType": "", // 传递类型，空字符串表示没有特殊传递类型。
// "nextHopProtocol": "http/1.1", // 下一跳协议，这里是 'http/1.1'，表示页面使用的是 HTTP/1.1 协议。
// "renderBlockingStatus": "non-blocking", // 渲染阻塞状态，这里是 'non-blocking'，表示页面加载不会阻塞渲染。
// "workerStart": 0, // Service Worker 开始的时间点，这里是 0，表示没有使用 Service Worker。
// "redirectStart": 0, // 重定向开始的时间点，这里为 0，表示没有重定向发生。
// "redirectEnd": 0, // 重定向结束的时间点，这里为 0，表示没有重定向发生。
// "fetchStart": 3, // 页面开始获取的时间点。
// "domainLookupStart": 5.399999976158142, // DNS 查询开始的时间点。
// "domainLookupEnd": 5.399999976158142, // DNS 查询结束的时间点。
// "connectStart": 5.399999976158142, // TCP 连接开始的时间点。
// "secureConnectionStart": 0, // 安全连接开始的时间点，这里是 0，表示没有使用 HTTPS。
// "connectEnd": 320.89999997615814, // TCP 连接结束的时间点。
// "requestStart": 321, // 页面请求开始的时间点。
// "responseStart": 330, // 页面响应开始的时间点。
// "firstInterimResponseStart": 0, // 第一个临时响应开始的时间点，这里为 0。
// "responseEnd": 330.7999999523163, // 页面响应结束的时间点。
// "transferSize": 1015, // 传输大小，表示页面资源的大小。
// "encodedBodySize": 715, // 编码后的主体大小，表示页面资源的压缩后大小。
// "decodedBodySize": 715, // 解码后的主体大小，表示页面资源的未压缩大小。
// "responseStatus": 200, // HTTP 响应状态码，这里是 200，表示请求成功。
// "serverTiming": [], // 服务器计时数组，这里为空，表示没有服务器计时信息。
// "unloadEventStart": 333.6999999284744, // 页面卸载事件开始的时间点。
// "unloadEventEnd": 333.6999999284744, // 页面卸载事件结束的时间点。
// "domInteractive": 837.1999999284744, // DOM 交互开始的时间点，表示 DOM 已完全加载并解析完成。
// "domContentLoadedEventStart": 1600, // DOMContentLoaded 事件开始的时间点。
// "domContentLoadedEventEnd": 1600.5, // DOMContentLoaded 事件结束的时间点。
// "domComplete": 3648.6999999284744, // DOM 完全加载完成的时间点。
// "loadEventStart": 3648.6999999284744, // 页面加载事件开始的时间点。
// "loadEventEnd": 3649.2999999523163, // 页面加载事件结束的时间点。
// "type": "reload", // 页面加载类型，这里是 'reload'，表示页面是通过重新加载启动的。
// "redirectCount": 0, // 重定向次数，这里是 0，表示没有重定向发生。
// "activationStart": 0, // 激活开始的时间点，这里是 0，表示页面没有预渲染。
// "criticalCHRestart": 0 // 关键请求链重启的时间点，这里是 0，表示没有关键请求链的重启。
// }
getSelector
const getName = (node: Node) => {
const name = node.nodeName;
return node.nodeType === 1
? name.toLowerCase()
: name.toUpperCase().replace(/^#/, '');
};
export const getSelector = (node: Node | null | undefined, maxLen?: number) => {
let sel = '';
try {
while (node && node.nodeType !== 9) {
const el: Element = node as Element;
const part = el.id
? '#' + el.id
: getName(el) +
(el.classList &&
el.classList.value &&
el.classList.value.trim() &&
el.classList.value.trim().length
? '.' + el.classList.value.trim().replace(/\s+/g, '.')
: '');
if (sel.length + part.length > (maxLen || 100) - 1) return sel || part;
sel = sel ? part + '>' + sel : part;
if (el.id) break;
node = el.parentNode;
}
} catch (err) {
// Do nothing...
}
return sel;
};
*observe
// 观望 PerformanceEntry 执行回调
export const observe = <K extends keyof PerformanceEntryMap>(
type: K,
callback: (entries: PerformanceEntryMap[K]) => void,
opts?: PerformanceObserverInit,
): PerformanceObserver | undefined => {
try {
if (PerformanceObserver.supportedEntryTypes.includes(type)) {
const po = new PerformanceObserver((list) => {
// Delay by a microtask to workaround a bug in Safari where the
// callback is invoked immediately, rather than in a separate task.
// See: https://github.com/GoogleChrome/web-vitals/issues/277
Promise.resolve().then(() => {
callback(list.getEntries() as PerformanceEntryMap[K]);
});
});
po.observe(
Object.assign(
{
type,
buffered: true,
},
opts || {},
) as PerformanceObserverInit,
);
return po;
}
} catch (e) {
// Do nothing.
}
return;
};
onBFCacheRestore
// 监听页面是否被缓存
let bfcacheRestoreTime = -1;
export const getBFCacheRestoreTime = () => bfcacheRestoreTime;
export const onBFCacheRestore = (cb: onBFCacheRestoreCallback) => {
addEventListener(
'pageshow',
(event) => {
if (event.persisted) {
// 只读属性 persisted 代表一个页面是否从缓存中加载的
bfcacheRestoreTime = event.timeStamp;
cb(event);
}
},
true,
);
};
getLoadState
export const getLoadState = (timestamp: number): LoadState => {
if (document.readyState === 'loading') {
// If the `readyState` is 'loading' there's no need to look at timestamps
// since the timestamp has to be the current time or earlier.
return 'loading';
} else {
const navigationEntry = getNavigationEntry();
if (navigationEntry) {
if (timestamp < navigationEntry.domInteractive) {
// domInteractive： 文档的 DOM 已经完全加载并解析完成
// 但可能还没有加载完成所有的子资源（如图片、样式表、脚本等）。
return 'loading';
} else if (
navigationEntry.domContentLoadedEventStart === 0 ||
timestamp < navigationEntry.domContentLoadedEventStart
) {
// domContentLoadedEventStart 是一个性能指标，它表示 DOMContentLoaded 事件触发的时间点。这个事件在文档被完全加载和解析完成后立即触发，但在样式表、图片、子框架等子资源加载完成之前。这意味着 domContentLoadedEventStart 时刻，可以开始执行那些不依赖于样式表或图片资源的 JavaScript 代码。
// 这个指标对于理解页面加载的性能非常有用，因为它可以帮助开发者识别页面何时准备好进行交互，而不必等待所有媒体资源加载完成。通过优化页面加载和解析的时间，可以提高页面的响应速度和用户体验。
// If the `domContentLoadedEventStart` timestamp has not yet been
// set, or if the given timestamp is less than that value.
return 'dom-interactive';
} else if (
navigationEntry.domComplete === 0 ||
timestamp < navigationEntry.domComplete
) {
// 它表示整个页面包括所有DOM、CSSOM（CSS对象模型）以及子资源（如图片、脚本、样式表等）都已加载完成，并且页面已经完全解析。此时，页面已准备好被用户查看和交互。
// If the `domComplete` timestamp has not yet been
// set, or if the given timestamp is less than that value.
return 'dom-content-loaded';
}
}
}
// If any of the above fail, default to loaded. This could really only
// happy if the browser doesn't support the performance timeline, which
// most likely means this code would never run anyway.
return 'complete';
};
getVisibilityWatcher
// 监听页面的可见性变化 返回隐藏时候的时间 firstHiddenTime
import {onBFCacheRestore} from './bfcache.js';
let firstHiddenTime = -1;
const initHiddenTime = () => {
// If the document is hidden when this code runs, assume it was always
// hidden and the page was loaded in the background, with the one exception
// that visibility state is always 'hidden' during prerendering, so we have
// to ignore that case until prerendering finishes (see: `prerenderingchange`
// event logic below).
return document.visibilityState === 'hidden' && !document.prerendering
? 0
: Infinity;
};
const onVisibilityUpdate = (event: Event) => {
// If the document is 'hidden' and no previous hidden timestamp has been
// set, update it based on the current event data.
if (document.visibilityState === 'hidden' && firstHiddenTime > -1) {
// If the event is a 'visibilitychange' event, it means the page was
// visible prior to this change, so the event timestamp is the first
// hidden time.
// However, if the event is not a 'visibilitychange' event, then it must
// be a 'prerenderingchange' event, and the fact that the document is
// still 'hidden' from the above check means the tab was activated
// in a background state and so has always been hidden.
firstHiddenTime = event.type === 'visibilitychange' ? event.timeStamp : 0;
// Remove all listeners now that a `firstHiddenTime` value has been set.
removeChangeListeners();
}
};
const addChangeListeners = () => {
addEventListener('visibilitychange', onVisibilityUpdate, true);
// IMPORTANT: when a page is prerendering, its `visibilityState` is
// 'hidden', so in order to account for cases where this module checks for
// visibility during prerendering, an additional check after prerendering
// completes is also required.
addEventListener('prerenderingchange', onVisibilityUpdate, true);
};
const removeChangeListeners = () => {
removeEventListener('visibilitychange', onVisibilityUpdate, true);
removeEventListener('prerenderingchange', onVisibilityUpdate, true);
};
export const getVisibilityWatcher = () => {
if (firstHiddenTime < 0) {
// If the document is hidden when this code runs, assume it was hidden
// since navigation start. This isn't a perfect heuristic, but it's the
// best we can do until an API is available to support querying past
// visibilityState.
firstHiddenTime = initHiddenTime();
addChangeListeners();
// Reset the time on bfcache restores.
onBFCacheRestore(() => {
// Schedule a task in order to track the `visibilityState` once it's
// had an opportunity to change to visible in all browsers.
// https://bugs.chromium.org/p/chromium/issues/detail?id=1133363
setTimeout(() => {
firstHiddenTime = initHiddenTime();
addChangeListeners();
}, 0);
});
}
return {
get firstHiddenTime() {
return firstHiddenTime;
},
};
};
getActivationStart
export const getActivationStart = (): number => {
const navEntry = getNavigationEntry();
return (navEntry && navEntry.activationStart) || 0;
};
initMetric
// 初始化指标数据格式
export const initMetric = <MetricName extends MetricType['name']>(
name: MetricName,
value?: number,
) => {
const navEntry = getNavigationEntry();
let navigationType: MetricType['navigationType'] = 'navigate';
if (getBFCacheRestoreTime() >= 0) {
navigationType = 'back-forward-cache';
} else if (navEntry) {
if (document.prerendering || getActivationStart() > 0) {
navigationType = 'prerender';
} else if (document.wasDiscarded) {
navigationType = 'restore';
} else if (navEntry.type) {
navigationType = navEntry.type.replace(
/_/g,
'-',
) as MetricType['navigationType'];
}
}
// Use `entries` type specific for the metric.
const entries: Extract<MetricType, {name: MetricName}>['entries'] = [];
return {
name,
value: typeof value === 'undefined' ? -1 : value,
rating: 'good' as const, // If needed, will be updated when reported. `const` to keep the type from widening to `string`.
delta: 0,
entries,
id: generateUniqueID(),
navigationType,
};
};
bindReporter
// 获取评分等级
const getRating = (
value: number,
thresholds: MetricRatingThresholds,
): MetricType['rating'] => {
if (value > thresholds[1]) {
return 'poor';
}
if (value > thresholds[0]) {
return 'needs-improvement';
}
return 'good';
};
// callback：一个回调函数，当度量值发生变化并且满足报告条件时，会被调用。
// metric：一个包含度量值的对象，它有一个 value 属性，表示当前度量值。
// thresholds：一个包含阈值的对象，用于确定度量值变化是否足够大，值得报告。
// reportAllChanges：一个可选的布尔值，指示是否报告所有变化。
export const bindReporter = <MetricName extends MetricType['name']>(
callback: (metric: Extract<MetricType, {name: MetricName}>) => void,
metric: Extract<MetricType, {name: MetricName}>,
thresholds: MetricRatingThresholds,
reportAllChanges?: boolean,
) => {
let prevValue: number;
let delta: number;
return (forceReport?: boolean) => {
if (metric.value >= 0) {
if (forceReport || reportAllChanges) {
delta = metric.value - (prevValue || 0);
// Report the metric if there's a non-zero delta or if no previous
// value exists (which can happen in the case of the document becoming
// hidden when the metric value is 0).
// See: https://github.com/GoogleChrome/web-vitals/issues/14
if (delta || prevValue === undefined) {
prevValue = metric.value;
metric.delta = delta;
metric.rating = getRating(metric.value, thresholds);
callback(metric);
}
}
}
};
};
