Add option to selectively include style properties when cloning element (#436)

* feat: add `includeStyleProperties` option

* the full list of computedStyle properties can be cached
* users can now manually specify which style properties are included

* docs: update docs

Author: Justineo

README.md

@@ -294,7 +294,11 @@ Defaults to `false`
 A string indicating the image format. The default type is image/png; that type is also used if the given type isn't supported.
 When supplied, the toCanvas function will return a blob matching the given image type and quality. 
 
-Defaults to `image/png`  
+Defaults to `image/png`
+
+### includeStyleProperties
+
+An array of style property names. Can be used to manually specify which style properties are included when cloning nodes. This can be useful for performance-critical scenarios.
 
 ## Browsers
 

src/apply-style.ts

@@ -1,4 +1,4 @@
-import { Options } from './types'
+import type { Options } from './types'
 
 export function applyStyle<T extends HTMLElement>(
   node: T,

src/clone-node.ts

@@ -1,6 +1,11 @@
 import type { Options } from './types'
 import { clonePseudoElements } from './clone-pseudos'
-import { createImage, toArray, isInstanceOfElement } from './util'
+import {
+  createImage,
+  toArray,
+  isInstanceOfElement,
+  getStyleProperties,
+} from './util'
 import { getMimeType } from './mimes'
 import { resourceToDataURL } from './dataurl'
 
@@ -29,12 +34,12 @@ async function cloneVideoElement(video: HTMLVideoElement, options: Options) {
   return createImage(dataURL)
 }
 
-async function cloneIFrameElement(iframe: HTMLIFrameElement) {
+async function cloneIFrameElement(iframe: HTMLIFrameElement, options: Options) {
   try {
     if (iframe?.contentDocument?.body) {
       return (await cloneNode(
         iframe.contentDocument.body,
-        {},
+        options,
         true,
       )) as HTMLBodyElement
     }
@@ -58,7 +63,7 @@ async function cloneSingleNode<T extends HTMLElement>(
   }
 
   if (isInstanceOfElement(node, HTMLIFrameElement)) {
-    return cloneIFrameElement(node)
+    return cloneIFrameElement(node, options)
   }
 
   return node.cloneNode(isSVGElement(node)) as T
@@ -114,7 +119,11 @@ async function cloneChildren<T extends HTMLElement>(
   return clonedNode
 }
 
-function cloneCSSStyle<T extends HTMLElement>(nativeNode: T, clonedNode: T) {
+function cloneCSSStyle<T extends HTMLElement>(
+  nativeNode: T,
+  clonedNode: T,
+  options: Options,
+) {
   const targetStyle = clonedNode.style
   if (!targetStyle) {
     return
@@ -125,7 +134,7 @@ function cloneCSSStyle<T extends HTMLElement>(nativeNode: T, clonedNode: T) {
     targetStyle.cssText = sourceStyle.cssText
     targetStyle.transformOrigin = sourceStyle.transformOrigin
   } else {
-    toArray<string>(sourceStyle).forEach((name) => {
+    getStyleProperties(options).forEach((name) => {
       let value = sourceStyle.getPropertyValue(name)
       if (name === 'font-size' && value.endsWith('px')) {
         const reducedFont =
@@ -177,10 +186,14 @@ function cloneSelectValue<T extends HTMLElement>(nativeNode: T, clonedNode: T) {
   }
 }
 
-function decorate<T extends HTMLElement>(nativeNode: T, clonedNode: T): T {
+function decorate<T extends HTMLElement>(
+  nativeNode: T,
+  clonedNode: T,
+  options: Options,
+): T {
   if (isInstanceOfElement(clonedNode, Element)) {
-    cloneCSSStyle(nativeNode, clonedNode)
-    clonePseudoElements(nativeNode, clonedNode)
+    cloneCSSStyle(nativeNode, clonedNode, options)
+    clonePseudoElements(nativeNode, clonedNode, options)
     cloneInputValue(nativeNode, clonedNode)
     cloneSelectValue(nativeNode, clonedNode)
   }
@@ -247,6 +260,6 @@ export async function cloneNode<T extends HTMLElement>(
   return Promise.resolve(node)
     .then((clonedNode) => cloneSingleNode(clonedNode, options) as Promise<T>)
     .then((clonedNode) => cloneChildren(node, clonedNode, options))
-    .then((clonedNode) => decorate(node, clonedNode))
+    .then((clonedNode) => decorate(node, clonedNode, options))
     .then((clonedNode) => ensureSVGSymbols(clonedNode, options))
 }

src/clone-pseudos.ts

@@ -1,4 +1,5 @@
-import { uuid, toArray } from './util'
+import type { Options } from './types'
+import { uuid, getStyleProperties } from './util'
 
 type Pseudo = ':before' | ':after'
 
@@ -7,8 +8,8 @@ function formatCSSText(style: CSSStyleDeclaration) {
   return `${style.cssText} content: '${content.replace(/'|"/g, '')}';`
 }
 
-function formatCSSProperties(style: CSSStyleDeclaration) {
-  return toArray<string>(style)
+function formatCSSProperties(style: CSSStyleDeclaration, options: Options) {
+  return getStyleProperties(options)
     .map((name) => {
       const value = style.getPropertyValue(name)
       const priority = style.getPropertyPriority(name)
@@ -22,11 +23,12 @@ function getPseudoElementStyle(
   className: string,
   pseudo: Pseudo,
   style: CSSStyleDeclaration,
+  options: Options,
 ): Text {
   const selector = `.${className}:${pseudo}`
   const cssText = style.cssText
     ? formatCSSText(style)
-    : formatCSSProperties(style)
+    : formatCSSProperties(style, options)
 
   return document.createTextNode(`${selector}{${cssText}}`)
 }
@@ -35,6 +37,7 @@ function clonePseudoElement<T extends HTMLElement>(
   nativeNode: T,
   clonedNode: T,
   pseudo: Pseudo,
+  options: Options,
 ) {
   const style = window.getComputedStyle(nativeNode, pseudo)
   const content = style.getPropertyValue('content')
@@ -50,14 +53,17 @@ function clonePseudoElement<T extends HTMLElement>(
   }
 
   const styleElement = document.createElement('style')
-  styleElement.appendChild(getPseudoElementStyle(className, pseudo, style))
+  styleElement.appendChild(
+    getPseudoElementStyle(className, pseudo, style, options),
+  )
   clonedNode.appendChild(styleElement)
 }
 
 export function clonePseudoElements<T extends HTMLElement>(
   nativeNode: T,
   clonedNode: T,
+  options: Options,
 ) {
-  clonePseudoElement(nativeNode, clonedNode, ':before')
-  clonePseudoElement(nativeNode, clonedNode, ':after')
+  clonePseudoElement(nativeNode, clonedNode, ':before', options)
+  clonePseudoElement(nativeNode, clonedNode, ':after', options)
 }

src/types.ts

@@ -23,6 +23,12 @@ export interface Options {
    * An object whose properties to be copied to node's style before rendering.
    */
   style?: Partial<CSSStyleDeclaration>
+  /**
+   * An array of style properties to be copied to node's style before rendering.
+   * For performance-critical scenarios, users may want to specify only the
+   * required properties instead of all styles.
+   */
+  includeStyleProperties?: string[]
   /**
    * A function taking DOM node as argument. Should return `true` if passed
    * node should be included in the output. Excluding node means excluding

src/util.ts

@@ -65,6 +65,22 @@ export function toArray<T>(arrayLike: any): T[] {
   return arr
 }
 
+let styleProps: string[] | null = null
+export function getStyleProperties(options: Options = {}): string[] {
+  if (styleProps) {
+    return styleProps
+  }
+
+  if (options.includeStyleProperties) {
+    styleProps = options.includeStyleProperties
+    return styleProps
+  }
+
+  styleProps = toArray(window.getComputedStyle(document.documentElement))
+
+  return styleProps
+}
+
 function px(node: HTMLElement, styleProperty: string) {
   const win = node.ownerDocument.defaultView || window
   const val = win.getComputedStyle(node).getPropertyValue(styleProperty)

test/resources/style/image-include-style

@@ -0,0 +1 @@
+data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAYAAABw4pVUAAAAAXNSR0IArs4c6QAAAXJJREFUeF7t3LENwDAMxEBp/6FlJFNcQU9AkHio897MTY8xsAVhWvwgBbF6FATrUZCCaAYwnm5IQTADGE4LKQhmAMNpIQXBDGA4LaQgmAEMp4UUBDOA4bSQgmAGMJwWUhDMAIbTQgqCGcBwWkhBMAMYTgspCGYAw2khBcEMYDgtpCCYAQynhRQEM4DhtJCCYAYwnBZSEMwAhtNCCoIZwHBaSEEwAxhOCykIZgDDaSEFwQxgOC2kIJgBDKeFFAQzgOG0kIJgBjCcnbl+lIOiFASK8aEUpCCYAQynhRQEM4DhtJCCYAYwnBZSEMwAhtNCCoIZwHBaSEEwAxhOCykIZgDDaSEFwQxgOC2kIJgBDKeFFAQzgOG0kIJgBjCcFlIQzACG00IKghnAcFpIQTADGE4LKQhmAMNpIQXBDGA4LaQgmAEMp4UUBDOA4bSQgmAGMJwWUhDMAIbTQgqCGcBwWkhBMAMYTgspCGYAw2khBcEMYDgPsePHnRi+YEEAAAAASUVORK5CYII=

test/spec/options.spec.ts

@@ -67,6 +67,18 @@ describe('work with options', () => {
       .catch(done)
   })
 
+  it('should only clone specified style properties when includeStyleProperties is provided', (done) => {
+    bootstrap('style/node.html', 'style/style.css', 'style/image-include-style')
+      .then((node) => {
+        return toPng(node, {
+          includeStyleProperties: ['width', 'height'],
+        })
+      })
+      .then(check)
+      .then(done)
+      .catch(done)
+  })
+
   it('should combine dimensions and style', (done) => {
     bootstrap('scale/node.html', 'scale/style.css', 'scale/image')
       .then((node) => {