xuguopeng/rrweb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Translated design docs to English (#19)

Browse Source 
* Renamed original documentation files

* Add translated English design docs
This commit is contained in:
Daniël van de Giessen
2026-04-01 12:00:00 +08:00
committed by yz-yu
parent 8b25f74cc5
commit 1a1f6d69a3
10 changed files with 464 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
docs/observer.md
View File

@@ -1,42 +1,42 @@
# 增量快照
# Incremental snapshots
After completing a full snapshot, we need to record events that change the state.
在完成一次全量快照之后，我们就需要基于当前视图状态观察所有可能对视图造成改动的事件，在 rrweb 中我们已经观察了以下事件（将不断增加）：
Right now, rrweb records the following events (we will expand upon this):
- DOM 变动
- 节点创建、销毁
- 节点属性变化
- 文本变化
- 鼠标移动
- 鼠标交互
- mouse up、mouse down
- click、double click、context menu
- focus、blur
- touch start、touch move、touch end
- 页面或元素滚动
- 视窗大小改变
- 输入
- DOM changes
- Node creation, deletion
- Node attribute changes
- Text changes
- Mouse movement
- Mouse interaction
- mouse up, mouse down
- click, double click, context menu
- focus, blur
- touch start, touch move, touch end
- Page or element scrolling
- Window size changes
- Input
## Mutation Observer
Since we don't execute any JavaScript during replay, we instead need to record all changes scripts make to the document.
由于我们在回放时不会执行所有的 JavaScript 脚本，所以例如这样的场景我们需要完整记录才能够实现回放：
Consider this example:
> User clicks a button. A dropdown menu appears. User selects the first item. The dropdown menu disappears.
> 点击 button，出现 dropdown menu，选择第一项，dropdown menu 消失
During replay, the dropdown menu does not automatically appear after the "click button" is executed, because the original JavaScript is not part of the recording. Thus, we need to record the creation of the dropdown menu DOM nodes, the selection of the first item, and subsequent deletion of the dropdown menu DOM nodes. This is the most difficult part.
回放时，在“点击 button”执行之后 dropdown menu 不会自动出现，因为已经没有 JavaScript 脚本为我们执行这件事，所以我们需要记录 dropdown menu 相关的 DOM 节点的创建以及后续的销毁，这也是录制中的最大难点。
Fortunately, modern browsers have provided us with a very powerful API which can do exactly this: [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
好在现代浏览器已经给我们提供了非常强大的 API —— [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) 用来完成这一功能。
This documentation does not explain the basic usages of MutationObserver, but only focusses on aspects in particular relevant to rrweb.
此处我们不具体讲解 MutationObserver 的基本使用方式，只专注于在 rrweb 中我们需要做哪些特殊处理。
The first thing to understand is that MutationObserver uses a **Bulk Asynchronous** callback. Specifically, there will be a single callback after a series of DOM changes occur, and it is passed an array of multiple mutation records.
首先要了解 MutationObserver 的触发方式为**批量异步**回调，具体来说就是会在一系列 DOM 变化发生之后将这些变化一次性回调，传出的是一个 mutation 记录数组。
This mechanism is not problematic for normal use, because we do not only have the mutation record, but we can also directly access the DOM object of the mutated node as well as any parent, child and sibling nodes.
这一机制在常规使用时不会有问题，因为从 mutation 记录中我们可以获取到变更节点的 JS 对象，可以做很多等值比较以及访问父子、兄弟节点等操作来保证我们可以精准回放一条 mutation 记录。
However in rrweb, since we have a serialization process, we need more sophisticated soluation to be able to deal with various scenarios.
但是在 rrweb 中由于我们有序列化的过程，我们就需要更多精细的判断来应对各种场景。
### 新增节点
例如以下两种操作会生成相同的 DOM 结构，但是产生不同的 mutation 记录：
### Add node
For example, the following two operations generate the same DOM structure, but produce a different set of mutation records:
```
body
@@ -44,58 +44,52 @@ body
n2
```
1. 创建节点 n1 并 append 在 body 中，再创建节点 n2 并 append 在 n1 中。
2. 创建节点 n1、n2，将 n2 append 在 n1 中，再将 n1 append 在 body 中。
1. Create node n1 and append it as child of body, then create node n2 and append it as child of n1.
2. Create nodes n1 and n2, then append n2 as child to of n1, then append n1 as child of body.
第 1 种情况将产生两条 mutation 记录，分别为增加节点 n1 和增加节点 n2；第 2 种情况则只会产生一条 mutation 记录，即增加节点 n1。
In the first case, two mutation records will be generated, namely adding node n1 and adding node n2; in the second case, only one mutation record will be generated, that is, node n1 (including children) is added.
**注意**，在第一种情况下虽然 n1 append 时还没有子节点，但是由于上述的批量异步回调机制，当我们处理 mutation 记录时获取到的 n1 是已经有子节点 n2 的状态。
**Note**: In the first case, although n1 has no child node when it is added, due to the above-mentioned batch asynchronous callback mechanism, when we receive the mutation record and process the n1 node the it already has the child node n2 in the DOM.
受第二种情况的限制，我们在处理新增节点时必须遍历其所有子孙节点，才能保证所有新增节点都被记录，但是这一策略应用在第一种情况中就会导致 n2 被作为新增节点记录两次，回放时就会产生与原页面不一致的 DOM 结构。
Due to the second case, when processing new nodes we must traverse all its descendants to ensure that all new nodes are recorded, however this strategy will cause n2 to be (incorrectly) recorded during the first record. Then, when processing the second record, adding a the node for a second time will result in a DOM structure that is inconsistent with the original page during replay.
因此，在处理一次回调中的多个 mutation 记录时我们需要“惰性”处理新增节点，即在遍历每条 mutation 记录遇到新增节点时先收集，再在全部 mutation 遍历完毕之后对收集的新增节点进行去重操作，保证不遗漏节点的同时每个节点只被记录一次。
Therefore, when dealing with multiple mutation records in a callback, we need to "lazely" process the newly added nodes, that is, first collect all raw, unprocessed nodes when we go through each mutation record, and then after we've been through all the mutation records we determine the the order nodes were added to the DOM. When new these nodes are added we perform deduplication to ensure that each node is only recorded once and we check no nodes were missed.
在[序列化设计](./serialization.md)中已经介绍了我们需要维护一个 `id -> Node` 的映射，因此当出现新增节点时，我们需要将新节点序列化并加入映射中。但由于我们为了去重新增节点，选择在所有 mutation 记录遍历完毕之后才进行序列化，在以下示例中就会出现问题：
We already introduced in the [serialization design document](./serialization.md) that we need to maintain a mapping of `id -> Node`, so when new nodes appear, we need to serialize the new nodes and add them to the map. But since we want to perform deduplication, and thus only serialize after all the mutation records have been processed, some problems may arise, as demonstrated in the following example:
1. mutation 记录1，新增节点 n1。我们暂不处理，等待最终去重后序列化。
2. mutation 记录2，n1 新增属性 a1。我们试图将它记录成一次增量快照，但会发现无法从映射中找到 n1 对应的 id，因为此时它还未被序列化。
1. mutation record 1, add node n1. We will not serialize it yet, since we are waiting for the final deduplication.
2. mutation record 2, n1 added attribute a1. We tried to record it as an incremental snapshot, but we found that we couldn't find the id for n1 from the map because it was not serialized yet.
由此可见，由于我们对新增节点进行了延迟序列化的处理，所有 mutation 记录也都需要先收集，再新增节点去重并序列化之后再做处理。
As you can see, since we have delayed serialization of the newly added nodes, all mutation records also need to be processed first, and only then the new nodes can be de-duplicated without causing trouble.
### 移除节点
### Remove node
When processing mutation records, we may encounter a removed node that has not yet been serialized. That indicates that it is a newly added node, and the "add node" mutation record is also somewhere in the mutation records we received. We label these nodes as "dropped nodes".
在处理移除节点时，我们需要做以下处理：
There are two cases we need to handle here:
1. Since the node was removed already, there is no need to replay it, and thus we remove it from the newly added node pool.
2. This also applies to descendants of the dropped node, thus when processing newly added nodes we need to check if it has a dropped node as an ancestor.
1. 移除的节点还未被序列化，则说明是在本次 callback 中新增的节点，无需记录，并且从新增节点池中将其移除。
2. 上步中在一次 callback 中被新增又移除的节点我们将其称为 dropped node，用于最终处理新增节点时判断节点的父节点是否已经 drop。
### Attribute change
Although MutationObserver is an asynchronous batch callback, we can still assume that the time interval between mutations occurring in a callback is extremely short, so we can optimize the size of the incremental snapshot by overwriting some data when recording the DOM property changes.
### 属性变化覆盖写
For example, resizing a `<textarea>` will trigger a large number of mutation records with varying width and height properties. While a full record will make replay more realistic, it can also result in a large increase in the number of incremental snapshots. After making a trade-off, we think that only the final value of an attribute of the same node needs to be recorded in a single mutation callback, that is, each subsequent mutation record will overwrite the attribute change part of the mutation record that existing before the write.
尽管 MutationObserver 是异步批量回调，但是我们仍然可以认为在一次回调中发生的 mutations 之间时间间隔极短，因此在记录 DOM 属性变化时我们可以通过覆盖写的方式优化增量快照的体积。
## Mouse movement
By recording the mouse movement position, we can simulate the mouse movement trajectory during replay.
例如对一个 `<textarea>` 进行 resize 操作，会触发大量的 width 和 height 属性变化的 mutation 记录。虽然完整记录会让回放更加真实，但是也可能导致增量快照数量大大增加。进行取舍之后，我认为在同一次 mutation callback 中只记录同一个节点某一属性的最终值即可，也就是后续的 mutation 记录会覆盖写之前已有的 mutation 记录中的属性变化部分。
Try to ensure that the mouse moves smoothly during replay and also minimize the number of corresponding incremental snapshots, so we need to perform two layers of throttling while listening to mousemove. The first layer records the mouse coordinates at most once every 20 ms, the second layer transmits the mouse coordinate set at most once every 500 ms to ensure a single snapshot doesn't accumulate a lot of mouse position data and becomes too large.
## 鼠标移动
### Time reversal
We record a timestamp when each incremental snapshot is generated so that during replay it can be applied at the correct time. However, due to the effect of throttling, the timestamps of the mouse movement corresponding to the incremental snapshot will be later than the actual recording time, so we need to record a negative time difference for correction and time calibration during replay.
通过记录鼠标移动位置，我们可以在回放时模拟鼠标移动轨迹。
## Input
We need to observe the input of the three elements `<input>`, `<textarea>`, `<select>`, including human input and programmatic changes.
尽量保证回放时鼠标移动流畅的同时也要尽量减少对应增量快照的数量，所以我们需要在监听 mousemove 的同时进行两层节流处理。第一层是每 20 ms 最多记录一次鼠标坐标，第二层是每 500 ms 最多发送一次鼠标坐标集合，第二层的主要目的是避免一次请求内容过多而做的分段。
### Human input
For human input, we mainly rely on listening to the input and change events. It is necessary to deduplicate different events triggered for the same the human input action. In addition, `<input type="radio" />` is also a special kind of control. If the multiple radio elements have the same name attribute, then when one is selected, the others will be reversed, but no event will be triggered on those others, so this needs to be handled separately.
### 时间逆推
我们在每个增量快照生成时会记录一个时间戳，用于在回放时按正确的时间差回放。但是由于节流处理的影响，鼠标移动对应增量快照的时间戳会比实际记录时间要更晚，因此我们需要记录一个用于校正的负时间差，在回放时将时间校准。
## 输入
我们需要观察 `<input>`, `<textarea>`, `<select>` 三种元素的输入，包含人为交互和程序设置两种途径的输入。
#### 人为交互
对于人为交互的操作我们主要靠监听 input 和 change 两个事件观察，需要注意的是对不同事件但值相同的情况进行去重。此外 `<input type="radio" />` 也是一类特殊的控件，如果多个 radio 元素的组件 name 属性相同，那么当一个被选择时其他都会被反选，但是不会触发任何事件，因此我们需要单独处理。
### 程序设置
通过代码直接设置这些元素的属性也不会触发事件，我们可以通过劫持对应属性的 setter 来达到监听的目的，示例代码如下：
### Programmatic changes
Setting the properties of these elements directly through the code will not trigger the MutationObserver. We can still achieve monitoring by hijacking the setter of the corresponding property. The sample code is as follows:
```typescript
function hookSetter<T>(
@@ -119,4 +113,4 @@ function hookSetter<T>(
}
```
注意为了避免我们在 setter 中的逻辑阻塞被录制页面的正常交互，我们应该把逻辑放入 event loop 中异步执行。
Note that in order to prevent our logic in the setter from blocking the normal interaction of the recorded page, we should put the logic into the event loop and execute it asynchronously.