Allow more fine grained control over blocking elements

.changeset/silver-pianos-attack.md

@@ -0,0 +1,7 @@
+---
+"rrweb-snapshot": patch
+"rrweb": patch
+"@rrweb/types": patch
+---
+
+Adds `blockElementFN` to record options to allow consumer finer-grained element blocking.

guide.md

@@ -137,7 +137,8 @@ The parameter of `rrweb.record` accepts the following options.
 | 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                                                                                |
-| blockSelector            | null               | Use a string to configure which selector should be blocked, refer to the [privacy](#privacy) chapter                                                                                          |
+| blockElementFN           | null               | Use a string to configure which selector should be blocked, refer to the [privacy](#privacy) chapter                                                                                          |
+| blockSelector            | null               | Manually determine what element 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                                                                                |
 | ignoreSelector           | null               | Use a string to configure which selector should be ignored, refer to the [privacy](#privacy) chapter                                                                                          |
 | ignoreCSSAttributes      | null               | array of CSS attributes that should be ignored                                                                                                                                                |
@@ -171,6 +172,7 @@ You may find some contents on the webpage which are not willing to be recorded,
 - All text of elements with the class name `.rr-mask` and their children will be masked.
 - `input[type="password"]` will be masked by default.
 - Mask options to mask the content in input elements.
+- `blockElementFN` takes precedence over `blockSelector` and `blockClass`, this callback function is passed a single argument: the elment to block.
 
 #### Checkout
 

packages/rrweb-snapshot/src/snapshot.ts

@@ -16,6 +16,7 @@
   attributes,
   mediaAttributes,
   DataURLOptions,
+  BlockElementFn,
 } from '@rrweb/types';
 import {
   Mirror,
@@ -219,8 +220,12 @@
   element: HTMLElement,
   blockClass: string | RegExp,
   blockSelector: string | null,
+  blockElementFn: BlockElementFn | null,
 ): boolean {
   try {
+    if (blockElementFn) {
+      return blockElementFn(element);
+    }
     if (typeof blockClass === 'string') {
       if (element.classList.contains(blockClass)) {
         return true;
@@ -282,7 +287,7 @@
     // should warn? maybe a text node isn't attached to a parent node yet?
     return false;
   } else {
     el = dom.parentElement(node)!;
   }
   try {
     if (typeof maskTextClass === 'string') {
@@ -392,6 +397,7 @@
     doc: Document;
     mirror: Mirror;
     blockClass: string | RegExp;
+    blockElementFn: BlockElementFn | null;
     blockSelector: string | null;
     needsMask: boolean;
     inlineStylesheet: boolean;
@@ -413,6 +419,7 @@
     doc,
     mirror,
     blockClass,
+    blockElementFn,
     blockSelector,
     needsMask,
     inlineStylesheet,
@@ -454,6 +461,7 @@
       return serializeElementNode(n as HTMLElement, {
         doc,
         blockClass,
+        blockElementFn,
         blockSelector,
         inlineStylesheet,
         maskInputOptions,
@@ -544,6 +552,7 @@
   options: {
     doc: Document;
     blockClass: string | RegExp;
+    blockElementFn: BlockElementFn | null;
     blockSelector: string | null;
     inlineStylesheet: boolean;
     maskInputOptions: MaskInputOptions;
@@ -562,6 +571,7 @@
   const {
     doc,
     blockClass,
+    blockElementFn,
     blockSelector,
     inlineStylesheet,
     maskInputOptions = {},
@@ -573,7 +583,12 @@
     newlyAddedElement = false,
     rootId,
   } = options;
-  const needBlock = _isBlockedElement(n, blockClass, blockSelector);
+  const needBlock = _isBlockedElement(
+    n,
+    blockClass,
+    blockSelector,
+    blockElementFn,
+  );
   const tagName = getValidTagName(n);
   let attributes: attributes = {};
   const len = n.attributes.length;
@@ -702,10 +717,10 @@
     const recordInlineImage = () => {
       image.removeEventListener('load', recordInlineImage);
       try {
         canvasService!.width = image.naturalWidth;
         canvasService!.height = image.naturalHeight;
         canvasCtx!.drawImage(image, 0, 0);
         attributes.rr_dataURL = canvasService!.toDataURL(
           dataURLOptions.type,
           dataURLOptions.quality,
         );
@@ -903,6 +918,7 @@
     doc: Document;
     mirror: Mirror;
     blockClass: string | RegExp;
+    blockElementFn: BlockElementFn | null;
     blockSelector: string | null;
     maskTextClass: string | RegExp;
     maskTextSelector: string | null;
@@ -937,6 +953,7 @@
     doc,
     mirror,
     blockClass,
+    blockElementFn,
     blockSelector,
     maskTextClass,
     maskTextSelector,
@@ -976,6 +993,7 @@
     doc,
     mirror,
     blockClass,
+    blockElementFn,
     blockSelector,
     needsMask,
     inlineStylesheet,
@@ -1047,6 +1065,7 @@
       doc,
       mirror,
       blockClass,
+      blockElementFn,
       blockSelector,
       needsMask,
       maskTextClass,
@@ -1123,6 +1142,7 @@
             doc: iframeDoc,
             mirror,
             blockClass,
+            blockElementFn,
             blockSelector,
             needsMask,
             maskTextClass,
@@ -1175,6 +1195,7 @@
             doc,
             mirror,
             blockClass,
+            blockElementFn,
             blockSelector,
             needsMask,
             maskTextClass,
@@ -1217,6 +1238,7 @@
   options?: {
     mirror?: Mirror;
     blockClass?: string | RegExp;
+    blockElementFn?: BlockElementFn | null;
     blockSelector?: string | null;
     maskTextClass?: string | RegExp;
     maskTextSelector?: string | null;
@@ -1246,6 +1268,7 @@
   const {
     mirror = new Mirror(),
     blockClass = 'rr-block',
+    blockElementFn = null,
     blockSelector = null,
     maskTextClass = 'rr-mask',
     maskTextSelector = null,
@@ -1312,6 +1335,7 @@
     doc: n,
     mirror,
     blockClass,
+    blockElementFn,
     blockSelector,
     maskTextClass,
     maskTextSelector,

packages/rrweb-snapshot/test/snapshot.test.ts

@@ -16,6 +16,7 @@ const serializeNode = (node: Node): serializedNodeWithId | null => {
     doc: document,
     mirror: new Mirror(),
     blockClass: 'blockblock',
+    blockElementFn: null,
     blockSelector: null,
     maskTextClass: 'maskmask',
     maskTextSelector: null,
@@ -129,7 +130,12 @@ describe('absolute url to stylesheet', () => {
 
 describe('isBlockedElement()', () => {
   const subject = (html: string, opt: any = {}) =>
-    _isBlockedElement(render(html), 'rr-block', opt.blockSelector);
+    _isBlockedElement(
+      render(html),
+      'rr-block',
+      opt.blockSelector,
+      opt.blockElementFn,
+    );
 
   const render = (html: string): HTMLElement =>
     JSDOM.fragment(html).querySelector('div')!;
@@ -151,6 +157,14 @@ describe('isBlockedElement()', () => {
       subject('<div data-rr-block />', { blockSelector: '[data-rr-block]' }),
     ).toEqual(true);
   });
+
+  it('blocks with blockElementFn', () => {
+    expect(
+      subject('<div class="special" />', {
+        blockElementFn: (e: HTMLElement) => e.matches('div.special'),
+      }),
+    ).toEqual(true);
+  });
 });
 
 describe('style elements', () => {

packages/rrweb/src/record/index.ts

@@ -70,6 +70,7 @@
     checkoutEveryNms,
     checkoutEveryNth,
     blockClass = 'rr-block',
+    blockElementFn = null,
     blockSelector = null,
     ignoreClass = 'rr-ignore',
     ignoreSelector = null,
@@ -321,6 +322,7 @@
     mutationCb: wrappedCanvasMutationEmit,
     win: window,
     blockClass,
+    blockElementFn,
     blockSelector,
     mirror,
     sampling: sampling.canvas,
@@ -332,6 +334,7 @@
     scrollCb: wrappedScrollEmit,
     bypassOptions: {
       blockClass,
+      blockElementFn,
       blockSelector,
       maskTextClass,
       maskTextSelector,
@@ -378,6 +381,7 @@
     const node = snapshot(document, {
       mirror,
       blockClass,
+      blockElementFn,
       blockSelector,
       maskTextClass,
       maskTextSelector,
@@ -543,6 +547,7 @@
           maskInputFn,
           maskTextFn,
           keepIframeSrcFn,
+          blockElementFn,
           blockSelector,
           slimDOMOptions,
           dataURLOptions,
@@ -557,7 +562,7 @@
             plugins
               ?.filter((p) => p.observer)
               ?.map((p) => ({
                 observer: p.observer!,
                 options: p.options,
                 callback: (payload: object) =>
                   wrappedEmit({
@@ -575,7 +580,7 @@
 
     iframeManager.addLoadListener((iframeEl) => {
       try {
         handlers.push(observe(iframeEl.contentDocument!));
       } catch (error) {
         // TODO: handle internal error
         console.warn(error);

packages/rrweb/src/record/mutation.ts

@@ -173,6 +173,7 @@
 
   private mutationCb: observerParam['mutationCb'];
   private blockClass: observerParam['blockClass'];
+  private blockElementFn: observerParam['blockElementFn'];
   private blockSelector: observerParam['blockSelector'];
   private maskTextClass: observerParam['maskTextClass'];
   private maskTextSelector: observerParam['maskTextSelector'];
@@ -199,6 +200,7 @@
       [
         'mutationCb',
         'blockClass',
+        'blockElementFn',
         'blockSelector',
         'maskTextClass',
         'maskTextSelector',
@@ -316,6 +318,7 @@
         doc: this.doc,
         mirror: this.mirror,
         blockClass: this.blockClass,
+        blockElementFn: this.blockElementFn,
         blockSelector: this.blockSelector,
         maskTextClass: this.maskTextClass,
         maskTextSelector: this.maskTextSelector,
@@ -363,13 +366,13 @@
     };
 
     while (this.mapRemoves.length) {
       this.mirror.removeNodeFromMap(this.mapRemoves.shift()!);
     }
 
     for (const n of this.movedSet) {
       if (
         isParentRemoved(this.removesSubTreeCache, n, this.mirror) &&
         !this.movedSet.has(dom.parentNode(n)!)
       ) {
         continue;
       }
@@ -556,7 +559,13 @@
         const value = dom.textContent(m.target);
 
         if (
-          !isBlocked(m.target, this.blockClass, this.blockSelector, false) &&
+          !isBlocked(
+            m.target,
+            this.blockClass,
+            this.blockSelector,
+            this.blockElementFn,
+            false,
+          ) &&
           value !== m.oldValue
         ) {
           this.texts.push({
@@ -594,7 +603,13 @@
           });
         }
         if (
-          isBlocked(m.target, this.blockClass, this.blockSelector, false) ||
+          isBlocked(
+            m.target,
+            this.blockClass,
+            this.blockSelector,
+            this.blockElementFn,
+            false,
+          ) ||
           value === m.oldValue
         ) {
           return;
@@ -695,7 +710,15 @@
         /**
          * Parent is blocked, ignore all child mutations
          */
-        if (isBlocked(m.target, this.blockClass, this.blockSelector, true))
+        if (
+          isBlocked(
+            m.target,
+            this.blockClass,
+            this.blockSelector,
+            this.blockElementFn,
+            true,
+          )
+        )
           return;
 
         if ((m.target as Element).tagName === 'TEXTAREA') {
@@ -711,7 +734,13 @@
             ? this.mirror.getId(dom.host(m.target))
             : this.mirror.getId(m.target);
           if (
-            isBlocked(m.target, this.blockClass, this.blockSelector, false) ||
+            isBlocked(
+              m.target,
+              this.blockClass,
+              this.blockSelector,
+              this.blockElementFn,
+              false,
+            ) ||
             isIgnored(n, this.mirror, this.slimDOMOptions) ||
             !isSerialized(n, this.mirror)
           ) {
@@ -790,7 +819,15 @@
 
     // if this node is blocked `serializeNode` will turn it into a placeholder element
     // but we have to remove it's children otherwise they will be added as placeholders too
-    if (!isBlocked(n, this.blockClass, this.blockSelector, false)) {
+    if (
+      !isBlocked(
+        n,
+        this.blockClass,
+        this.blockSelector,
+        this.blockElementFn,
+        false,
+      )
+    ) {
       dom.childNodes(n).forEach((childN) => this.genAdds(childN));
       if (hasShadowRoot(n)) {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -836,7 +873,7 @@
 function _isParentRemoved(
   removes: Set<Node>,
   n: Node,
   _mirror: Mirror,
 ): boolean {
   const node: ParentNode | null = dom.parentNode(n);
   if (!node) return false;