html2canvas Implementation Principles and Opacity Rendering Issue Analysis

This article explores the implementation principles of html2canvas and addresses a common issue where transparent overlays are rendered without transparency when capturing screenshots.

Problem Background: In a frontend project requiring page screenshot and upload functionality, after installing the html2canvas npm package, transparent overlays were captured as opaque. This opacity rendering failure issue has existed since 2015. Although niklasvh fixed it in December 2020, the fix was not merged into the npm package.

html2canvas Implementation Principles: The library's workflow consists of three main parts: the main entry method, DOM cloning and parsing, and DOM rendering. The entry method passes the selected DOM node and custom configuration to renderElement, which merges configurations, generates a CanvasRenderer instance, clones and parses the DOM node, then renders it to an offscreen canvas.

Key Methods: DocumentCloner handles DOM cloning through recursive tree traversal to find and clone the selected DOM nodes. parseTree parses cloned DOM nodes to extract position, dimensions, and style information, outputting an ElementContainer structure with bounds, elements, flags, styles, and textNodes.

Stacking Context: html2canvas renders DOM nodes based on stacking context. A node creates a stacking context when it meets certain conditions such as: root element, position absolute/relative with z-index not auto, position fixed/sticky, flex/grid children with z-index not auto, opacity less than 1, non-normal mix-blend-mode, certain transform/filter/perspective properties, isolation: isolate, or will-change. The 7-level stacking order determines how elements are layered.

Rendering Process: The renderStackContent method follows stacking context to render DOM nodes layer by layer from bottom to top: background/border → negative z-index → block boxes → float boxes → inline boxes → z-index auto/0 or opacity < 1 → positive z-index.

Root Cause and Solution: The npm package lacks opacity rendering effect handling logic. The fix adds an OpacityEffect class that records node opacity during parsing and applies it during rendering via globalAlpha. By integrating this logic into html2canvas, transparent overlay screenshot failures can be resolved.

export class OpacityEffect implements IElementEffect {
    readonly type: EffectType = EffectType.OPACITY;
    readonly target: number = EffectTarget.BACKGROUND_BORDERS | EffectTarget.CONTENT;
    readonly opacity: number;
    
    constructor(opacity: number) {
        this.opacity = opacity;
    }
}

export const isOpacityEffect = (effect: IElementEffect): effect is OpacityEffect => effect.type === EffectType.OPACITY;

During parsing, when element styles have opacity less than 1:

if (element.styles.opacity < 1) {
    this.effects.push(new OpacityEffect(element.styles.opacity));
}

During rendering in applyEffects:

if (isOpacityEffect(effect)) {
    this.ctx.globalAlpha = effect.opacity;
}