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

update docs

Browse Source
This commit is contained in:
Yanzhen Yu
2026-04-01 12:00:00 +08:00
parent 4c9fc8ce70
commit aeeafddb46
16 changed files with 651 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

201
guide.md
View File

@@ -1,6 +1,8 @@
# Guide
[中文指南](./guide.zh_CN.md)
[中文指南](./guide.md)
> You may also want to read the [recipes](./docs/recipes/index.md) to find some use real-world use case, or read the [design docs](../) to know more technical details of rrweb.
## Installation
@@ -31,17 +33,44 @@ This also can be done by using the CDN service:
<script src="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/record/rrweb-record.min.js"></script>
```
#### Other bundles
Besides the `record/rrweb-record.min.js` entry, rrweb also provides other bundles for different usage.
```shell
# Include record, replay, compression, and decompression.
rrweb-all.js
rrweb-all.min.js
# Include record and replay.
rrweb.js
rrweb.min.js
# Include the styles for replay.
rrweb.min.css
# Record
record/rrweb-record.js
record/rrweb-record.min.js
# Data compression.
record/rrweb-record-pack.js
record/rrweb-record-pack.min.js
# Replay
replay/rrweb-replay.js
replay/rrweb-replay.min.js
# Data decompression.
replay/rrweb-replay-unpack.js
replay/rrweb-replay-unpack.min.js
```
### NPM
```shell
npm install --save rrweb
```
rrweb provides both commonJS and ES modules bundles, which is easy to use with the popular bundlers.
rrweb provides both commonJS and ES modules bundles, which are easy to use with the popular bundlers.
### Compatibility Note
rrweb does **not** support IE11 and below, because it uses the `MutationObserver` API which was supported by [these browsers](https://caniuse.com/#feat=mutationobserver).
rrweb does **not** support IE11 and below because it uses the `MutationObserver` API which was supported by [these browsers](https://caniuse.com/#feat=mutationobserver).
## Getting Started
@@ -73,7 +102,7 @@ let stopFn = rrweb.record({
});
```
A more real-world usage may looks like this:
A more real-world usage may look like this:
```js
let events = [];
@@ -102,6 +131,26 @@ function save() {
setInterval(save, 10 * 1000);
```
#### Options
The parameter of `rrweb.record` accepts the following options.
| key | default | description |
| ---------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| emit | required | the callback function to get emitted events |
| checkoutEveryNth | - | take a full snapshot after every N events<br />refer to the [checkout](#checkout) chapter |
| checkoutEveryNms | - | take a full snapshot after every N ms<br />refer to the [checkout](#checkout) chapter |
| blockClass | 'rr-block' | Use a string or RegExp to configure which elements should be blocked, refer to the [privacy](#privacy) chapter |
| ignoreClass | 'rr-ignore' | Use a string or RegExp to configure which elements should be ignored, refer to the [privacy](#privacy) chapter |
| maskAllInputs | false | mask all input content as \* |
| maskInputOptions | {} | mask some kinds of input \*<br />refert ot the [list](https://github.com/rrweb-io/rrweb-snapshot/blob/6728d12b3cddd96951c86d948578f99ada5749ff/src/types.ts#L72) |
| inlineStylesheet | true | whether to inline the stylesheet in the events |
| hooks | {} | hooks for events<br />refer to the [list](https://github.com/rrweb-io/rrweb/blob/9488deb6d54a5f04350c063d942da5e96ab74075/src/types.ts#L207) |
| packFn | - | refer to the [storage optimization recipe](./docs/recipes/optimize-storage.md) |
| sampling | - | refer to the [storage optimization recipe](./docs/recipes/optimize-storage.md) |
| recordCanvas | false | whether to record the canvas element |
| collectFonts | false | whether to collect fonts in the website |
#### Privacy
You may find some contents on the webpage which are not willing to be recorded, then you can use the following approaches:
@@ -109,6 +158,7 @@ You may find some contents on the webpage which are not willing to be recorded,
- An element with the class name `.rr-block` will not be recorded. Instead, it will replay as a placeholder with the same dimension.
- An element with the class name `.rr-ignore` will not record its input events.
- `input[type="password"]` will be ignored as default.
- Mask options to mask the content in input elements.
#### Checkout
@@ -204,18 +254,43 @@ const replayer = new rrweb.Replayer(events);
replayer.play();
```
#### Control the replayer by API
```js
const replayer = new rrweb.Replayer(events);
// play
replayer.play();
// play from the third seconds
replayer.play(3000);
// pause
replayer.pause();
// pause at the fifth seconds
replayer.pause(5000);
```
#### Options
The replayer accepts options as its constructor's second parameter, and it has the following options:
| key | default | description |
| ------------ | ------------- | ----------------------------------------------- |
| speed | 1 | replay speed ratio |
| root | document.body | the root element of replayer |
| loadTimeout | 0 | timeout of loading remote style sheet |
| skipInactive | false | whether to skip inactive time |
| showWarning | true | whether to print warning messages during replay |
| showDebug | false | whether to print debug messages during replay |
| key | default | description |
| ------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| speed | 1 | replay speed ratio |
| root | document.body | the root element of replayer |
| loadTimeout | 0 | timeout of loading remote style sheet |
| skipInactive | false | whether to skip inactive time |
| showWarning | true | whether to print warning messages during replay |
| showDebug | false | whether to print debug messages during replay |
| blockClass | 'rr-block' | element with the class name will display as a blocked area |
| liveMode | false | whether to enable live mode |
| inertStyleRules | [] | accepts multiple CSS rule string, which will be injected into the replay iframe |
| triggerFocus | true | whether to trigger focus during replay |
| UNSAFE_replayCanvas | false | whether to replay the canvas element. **Enable this will remove the sandbox, which is unsafe.** |
| mouseTail | true | whether to show mouse tail during replay. Set to false to disable mouse tail. A complete config can be found in this [type](https://github.com/rrweb-io/rrweb/blob/9488deb6d54a5f04350c063d942da5e96ab74075/src/types.ts#L407) |
| unpackFn | - | refer to the [storage optimization recipe](./docs/recipes/optimize-storage.md) |
#### Use rrweb-player
@@ -244,73 +319,63 @@ npm install --save rrweb-player
```js
new rrwebPlayer({
target: document.body, // customizable root element
data: {
props: {
events,
autoPlay: true,
},
});
```
##### Options
| key | default | description |
| -------------- | ------------ | ------------------------------------------------------ |
| events | [] | the events for replaying |
| width | 1024 | the width of the replayer |
| height | 576 | the height of the replayer |
| autoPlay | true | whether to autoplay |
| speedOption | [1, 2, 4, 8] | speed options in UI |
| showController | true | whether to show the controller UI |
| tags | {} | customize the custom events style with a key-value map |
| ... | - | all the rrweb Replayer options will be bypassed |
#### Events
Developers may want to extend the rrweb's replayer or respond to its events. Such as giving a notification when the replayer starts to skip inactive time.
So rrweb expose a public API `on` which allow developers listen to the events and customize the reactions, and it has the following events:
Developers may want to extend the rrweb's replayer or respond to its events. Such as giving notification when the replayer starts to skip inactive time.
So rrweb expose a public API `on` which allow developers to listen to the events and customize the reactions, and it has the following events:
| event | description |
| ---------------------- | ---------------------------------- |
| start | started to replay |
| pause | paused the replay |
| finish | finished the replay |
| fullsnapshot-rebuilded | rebuilded a full snapshot |
| load-stylesheet-start | started to load remote stylesheets |
| load-stylesheet-end | loaded remote stylesheets |
| skip-start | started to skip inactive time |
| skip-end | skipped inactive time |
```js
const replayer = new rrweb.Replayer(events);
replayer.on(EVENT_NAME, (payload) => {
...
})
```
The event list:
| Event | Description | Value |
| ---------------------- | ----------------------------------- | ----------------- |
| start | started to replay | - |
| pause | paused the replay | - |
| finish | finished the replay | - |
| resize | the viewport has changed | { width, height } |
| fullsnapshot-rebuilded | rebuilded a full snapshot | event |
| load-stylesheet-start | started to load remote stylesheets | - |
| load-stylesheet-end | loaded remote stylesheets | - |
| skip-start | started to skip inactive time | { speed } |
| skip-end | skipped inactive time | { speed } |
| mouse-interaction | mouse interaction has been replayed | { type, target } |
| event-cast | event has been replayed | event |
| custom-event | custom event has been replayed | event |
The rrweb-replayer also re-expose the event listener via a `component.addEventListener` API.
## API
And there are three rrweb-replayer event will be emitted in the same way:
### rrweb
#### rrweb.record
```typescript
type record = (options: recordOptions) => listenerHandler;
type recordOptions = {
emit: (e: eventWithTime) => void;
};
type listenerHandler = () => void;
```
#### rrweb.Replayer
```typescript
class Replayer {
public wrapper: HTMLDivElement;
constructor(events: eventWithTime[], config?: Partial<playerConfig>);
public on(event: string, handler: mitt.Handler): void;
public setConfig(config: Partial<playerConfig>): void;
public getMetaData(): playerMetaData;
public getTimeOffset(): number;
public play(timeOffset?: number): void;
public pause(timeOffset?: number): void;
}
type playerConfig = {
speed: number;
root: Element;
loadTimeout: number;
skipInactive: Boolean;
};
type playerMetaData = {
totalTime: number;
};
```
| Event | Description | Value |
| ---------------------- | -------------------------------- | ----------------------- |
| ui-update-current-time | current time has changed | { detail: { payload } } |
| ui-update-player-state | current player state has changed | { detail: { payload } } |
| ui-update-progress | current progress has changed | { detail: { payload } } |
## REPL tool
@@ -331,7 +396,7 @@ Ready to record. You can do any interaction on the page.
Once you want to finish the recording, enter 'y' to start replay:
```
At this point, you can interact in the web page. After the desired operations have been recorded, enter 'y' on the CLI, and the test tool will replay the operations to verify whether the recording was successful.
At this point, you can interact on the web page. After the desired operations have been recorded, enter 'y' on the CLI, and the test tool will replay the operations to verify whether the recording was successful.
The following messages will be printed on the CLI during replay: