Canvascontent beschikbaar maken voor browserfuncties

Webfuncties: HTML in canvas

Normale <canvas>-content is niet beschikbaar voor browserfuncties zoals schermlezers, indexering, vertaaltools, toegankelijkheidstools, zoeken op pagina, afdrukken, enzovoort. Met HTML in canvas kun je echte DOM rechtstreeks weergeven in een canvaselement. Als je het kenmerk content="drawable" toevoegt aan een HTML-element <canvas>, worden de onderliggende HTML-elementen opgemaakt. Het kenmerk drawable markeert de elementen die je kunt renderen binnen de weergavecontext van het canvas. Je kunt de API gebruiken om tekst op een canvas op te maken en in te delen, canvascontent beschikbaar te maken voor browserfuncties (zoals toegankelijkheid, vertaling of zoeken op pagina) en 2D- en 3D-effecten toe te passen op HTML.

Hoe wordt dit geïmplementeerd

  1. Controleer of HTML-in-Canvas wordt ondersteund in de browser:

    if ('content' in HTMLCanvasElement.prototype) {
  // Use HTML in Canvas API
} else {
  // Use fallback strategy
}

  2. Voeg het kenmerk content="drawable" toe aan het HTML-element <canvas>.

  3. Plaats uw HTML-content in het element <canvas> en voeg het kenmerk drawable toe aan elk element dat u tekent. Een element met drawable legt de substructuur vast, behalve geneste onderliggende elementen die ook drawable zijn.

    <canvas id="canvas" content="drawable">
  <div id="html-content" drawable></div>
</canvas>

  4. Schaal je canvasraster zodat het overeenkomt met de schaalfactor van het apparaat om wazigheid te voorkomen:

    const observer = new ResizeObserver(([entry]) => {
  const dpc = entry.devicePixelContentBoxSize;
  canvas.width = dpc
    ? dpc[0].inlineSize
    : Math.round(entry.contentRect.width * window.devicePixelRatio);
  canvas.height = dpc
    ? dpc[0].blockSize
    : Math.round(entry.contentRect.height * window.devicePixelRatio);
});

const supportsDevicePixelContentBox =
  typeof ResizeObserverEntry !== "undefined" &&
  "devicePixelContentBoxSize" in ResizeObserverEntry.prototype;
const options = supportsDevicePixelContentBox
  ? { box: "device-pixel-content-box" }
  : {};
observer.observe(canvas, options);

  5. Geef de HTML-content weer op het canvas in een canvas.onpaint-gebeurtenishandler. Een element kan alleen worden getekend nadat het canvas het heeft getekend: roep canvas.requestPaint() aan om een paint-gebeurtenis aan te vragen.

  • Gebruik in een 2D-context de methode drawElementImage. Hiermee wordt de laatste momentopname van een drawable-element en de tekenbare substructuur getekend, beginnend bij het randvak van het element, vóór CSS-transformaties:
canvas.onpaint = () => {
  ctx.reset();
  // Draw the form element at x:0, y:0
  ctx.drawElementImage(form_element, 0, 0);
};
  • In WebGL- en WebGPU-contexten kopieer je het element naar een textuur. Pas de grootte van de textuur aan vanaf canvas.captureElementImage(element). De width en height zijn in canvasrasterpixels (backing store), dus rond ze naar boven af met Math.ceil(). captureElementImage() genereert een fout als het element nog geen tekenrecord heeft: roep requestPaint() aan en probeer het opnieuw bij de volgende paint-gebeurtenis.
// Returns the element's size in canvas grid pixels, or null if the element
// has no paint record yet.
function getElementImageSize(canvas, element) {
  let elementImage;
  try {
    elementImage = canvas.captureElementImage(element);
  } catch (err) {
    canvas.requestPaint(); // No paint record yet: retry on the next paint event.
    return null;
  }
  const width = Math.ceil(elementImage.width);
  const height = Math.ceil(elementImage.height);
  elementImage.close();
  return width > 0 && height > 0 ? { width, height } : null;
}
  • Wijs in de WebGL-context eerst de textuurbacking vooraf toe met de methode texImage2D. De fragmenten in deze handleiding gebruiken een WebGL 2-context (canvas.getContext("webgl2")). Wijs textuuropslag toe door texImage2D() aan te roepen met null in plaats van pixelgegevens. Hiermee wordt GPU-geheugen van de opgegeven grootte en indeling gereserveerd zonder pixels te uploaden. Volg deze regels:
    • Pas de grootte van de textuur aan vanaf captureElementImage(), zoals hierboven getoond.
    • Wijs niveau 0 alleen toe bij de eerste upload of als de grootte verandert, omdat de textuur wordt gewist als je deze opnieuw toewijst. Gebruik veranderlijke opslag: de grootte van onveranderlijke texStorage2D()-opslag kan niet worden aangepast als de grootte van het element verandert.
// Binds the texture, and allocates its storage on the first upload, and when
// the element size changes. `state` stores the allocated size.
function allocateElementTexture(gl, texture, state, width, height) {
  gl.bindTexture(gl.TEXTURE_2D, texture);
  if (state.width === width && state.height === height) return;

  gl.texImage2D(
    gl.TEXTURE_2D,
    0,                // Mipmap level
    gl.RGBA8,         // Internal format: 8 bits per RGBA channel
    width,            // Size in canvas grid pixels
    height,
    0,                // Border: must be 0
    gl.RGBA,          // Format and type that match RGBA8
    gl.UNSIGNED_BYTE,
    null              // null reserves GPU memory without uploading pixels
  );
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
  state.width = width;
  state.height = height;
}

const texture = gl.createTexture();
const textureState = { width: 0, height: 0 };
  • Geef daarna in de WebGL-context de HTML-content weer in de textuur met de methode texElementSubImage2D. Volg deze regels:
    • Geef { width, height } door in de configuratie. De kopie vult de toegewezen textuur, ongeacht hoe het canvas wordt geschaald.
    • Wijs de textuur opnieuw toe als de grootte is gewijzigd, zoals hierboven getoond.
// Uploads the element into the texture. Returns false if the element has no
// paint record yet. In that case, it's uploaded on the next paint event.
function uploadElementWebGL(gl, canvas, texture, element, state) {
  const size = getElementImageSize(canvas, element);
  if (!size) return false;
  const { width, height } = size;

  // Bind the texture, and reallocate it if the size changed (see above).
  allocateElementTexture(gl, texture, state, width, height);
  gl.texElementSubImage2D(gl.TEXTURE_2D, 0, 0, 0, element, { width, height });
  return true;
}

canvas.onpaint = () => {
  try {
    uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
  } catch (err) {
    console.error('texElementSubImage2D copy failed:', err);
  }
};
  • Gebruik in de WebGPU-context de drawElementImageToTexture-methode. Volg deze regels:
    • Maak de textuur met COPY_DST- en RENDER_ATTACHMENT-gebruik en voeg TEXTURE_BINDING toe om deze te samplen in shaders. Onjuist gebruik wordt gerapporteerd als een WebGPU-validatiefout, niet als een uitzondering.
    • Geef de textuurgrootte door als size. Zonder size wordt een groter element bijgesneden tot de textuur. Met size wordt het element geschaald om het te vullen.
    • Het formaat van WebGPU-texturen kan niet worden aangepast. Maak de textuur opnieuw als de elementgrootte verandert en maak de bindingsgroepen die ernaar verwijzen opnieuw.
// WebGPU textures can't be resized. Create the texture once, and recreate it
// when the element size changes.
function ensureElementTexture(device, state, width, height) {
  if (state.texture?.width === width && state.texture?.height === height) {
    return state.texture;
  }
  state.texture?.destroy();
  state.texture = device.createTexture({
    size: { width, height },
    format: "rgba8unorm",
    usage:
      GPUTextureUsage.TEXTURE_BINDING |
      GPUTextureUsage.COPY_DST |
      GPUTextureUsage.RENDER_ATTACHMENT,
  });
  return state.texture; // Recreate the bind groups that used the previous texture.
}

const textureState = { texture: null };

canvas.onpaint = () => {
  const size = getElementImageSize(canvas, uiElement);
  if (!size) return;
  const previousTexture = textureState.texture;
  const texture = ensureElementTexture(device, textureState, size.width, size.height);
  if (texture !== previousTexture) {
    // New texture: create, or rebuild, the bind groups that reference it.
  }
  try {
    device.queue.drawElementImageToTexture({ source: uiElement }, { texture, size });
  } catch (err) {
    console.error('drawElementImageToTexture copy failed:', err);
  }
};

Als je een requestAnimationFrame-lus gebruikt om de scène te renderen, roep je canvas.requestPaint() aan binnen de lus om te zorgen dat de HTML-content wordt gerenderd naar het canvas. event.changedElements vermeldt de elementen waarvan de weergave is gewijzigd. Zorg dat u het element alleen opnieuw tekent of de textuur opnieuw uploadt als er een update is geweest voor de onderliggende HTML-elementen:

function render() {
  // Request to update the canvas
  canvas.requestPaint();
  requestAnimationFrame(render);
}
requestAnimationFrame(render);

canvas.onpaint = (event) => {
  if (event.changedElements && event.changedElements.length > 0) {
    // Redraw the element, or update its texture, as shown above
  }
  // In WebGL and WebGPU, render the scene, and sync the element geometry as shown in step 6
};
  1. Synchroniseer de elementgeometrie.

De browser moet weten waar het HTML-element wordt getekend, zodat de DOM-positie overeenkomt met de getekende pixels. Hit-tests, bijvoorbeeld voor klikken en tekstselectie, en toegankelijkheid gebruiken deze geometrie: een drawable-element waarvan de geometrie niet is geüpdatet, wordt nog steeds blootgesteld aan de toegankelijkheidsstructuur, maar zonder geometrie-informatie. Een canvas voert alleen hit-tests uit voor de elementen die zijn getekend met de 2D-methode drawElementImage() of zijn geregistreerd met updateElementGeometry().

  • In het geval van 2D-context synchroniseert de browser het element automatisch. drawElementImage() lijnt de DOM-hit-testgrenzen en de focusringen van de schermlezer uit met de getekende coördinaten, zodat je style.transform niet hoeft in te stellen. Als je de geometrie handmatig wilt beheren, bijvoorbeeld als je hetzelfde element meerdere keren tekent, geef je { preserveElementGeometry: true } door aan drawElementImage() en pas je transformaties toe met canvas.updateElementGeometry().

  • In het 3D-geval met WebGL of WebGPU kan het canvas niet bepalen waar het HTML-element wordt getekend. Je moet dit dus zelf aangeven. Bereken een DOMMatrix die het randvak van het element, in CSS-pixels, toewijst aan het canvas, in CSS-pixels. De browser moet de 3D-coördinatenruimte toewijzen aan de CSS-coördinatenruimte met een viewport-transformatie. Doe hiervoor het volgende:

    • Normaliseer het HTML-element. HTML-elementen worden gemeten in pixels (bijvoorbeeld 200 pixels breed). WebGL behandelt objecten meestal als eenheidsvierkanten, bijvoorbeeld van -0,5 tot 0,5. Als je niet normaliseert, ziet je knop van 200 px er 200 keer groter uit. In deze stap wordt ook de Y-as omgedraaid, omdat in CSS omlaag positief is, maar in WebGL omhoog positief is.
    • Zet de WebGL MVP-matrix om in een DOM-matrix.
    • Toewijzen aan het kijkvenster van het canvas. Deze stap is de fase van opnieuw schalen: de wiskunde van de eenheidsruimte wordt weer uitgerekt zodat deze overeenkomt met de CSS-pixelafmetingen van je <canvas>-element op het scherm en de Y-as wordt weer omgedraaid.
    • Bereken de uiteindelijke transformatie. Vermenigvuldig de matrices in de volgorde: Viewport * MVP * Normalization. Als je ze combineert tot één uiteindelijke transformatie, krijg je een 'kaart' die de browser precies vertelt waar dat HTML-element moet staan om uit te lijnen met de 3D-tekening. De browser voert de perspectiefdeling uit.
    // Maps the element's border box (CSS pixels) to the canvas (CSS pixels), for a
// quad that spans -0.5 to 0.5 in model space and is drawn with the `mvp` matrix.
function computeCanvasTransform(canvas, element, mvp) {
  const width = element.offsetWidth;
  const height = element.offsetHeight;

  // 1. Normalize the HTML element (CSS pixels -> WebGL Model Space)
  const toGLModel = new DOMMatrix()
    // Scale pixels to 1 unit, flip Y (as in CSS it points down, and in WebGL it points up)
    .scale(1 / width, -1 / height, 1 / height)
    // Center the origin: (0,0) becomes (-width/2, -height/2) before scaling
    .translate(-width / 2, -height / 2);

  // 2. Convert WebGL MVP Matrix to DOM Matrix
  const mvpDOM = new DOMMatrix(Array.from(mvp));

  // 3. Map to the canvas viewport, in CSS pixels
  const clipToCanvasViewport = new DOMMatrix()
    // Move center (0,0) to center of canvas
    .translate(canvas.clientWidth / 2, canvas.clientHeight / 2)
    // Scale normalized clip (-1..1) to viewport size, and flip Y back
    .scale(canvas.clientWidth / 2, -canvas.clientHeight / 2, canvas.clientHeight / 2);

  // 4. Multiply: (Clip -> Pixels) * (MVP) * (pixels -> unit square)
  return clipToCanvasViewport.multiply(mvpDOM).multiply(toGLModel);
}

Geef de transformatie daarna door aan canvas.updateElementGeometry() als canvasTransform. Hiermee wordt het HTML-element rechtstreeks boven de gerenderde pixels geplaatst. Zo weet u zeker dat wanneer een gebruiker op een knop klikt of tekst selecteert, deze ook echt het echte HTML-element raakt. De browser gebruikt de transformatie ook voor de toegankelijkheidsgrenzen van het element, bijvoorbeeld voor focusringen van schermlezers:

  canvas.updateElementGeometry(targetHTMLElement, {
    canvasTransform: computeCanvasTransform(canvas, targetHTMLElement, htmlElementMVP),
  });

Gebruik deze opties om hit-tests te beheren:

  • Elke updateElementGeometry()-aanroep verplaatst het element naar de bovenkant van de hit-testvolgorde. Kaart { preserveHitTestOrder: true } behoudt de positie.
  • Roep canvas.clearElementGeometry(element) aan om een element uit de hit-test te verwijderen, bijvoorbeeld als je het verbergt.

Voorbeeldcode

2D-canvas

<canvas id="canvas" content="drawable" style="width: 400px; height: 200px;">
  <div id="ui-element" drawable>
    <p>
      This text is rendered inside the canvas but is present in the DOM tree.
    </p>
    <input type="email" name="email" placeholder="enter your email" />
    <button type="button">Submit</button>
  </div>
</canvas>

<script>
  const canvas = document.getElementById("canvas");
  const ctx = canvas.getContext("2d");
  const uiElement = document.getElementById("ui-element");

  canvas.onpaint = () => {
    ctx.reset();
    // Draw the HTML element at x:0, y:0. The browser syncs the DOM location
    // with the drawn location.
    ctx.drawElementImage(uiElement, 0, 0);
  };

  // Handle resizing to match device pixels
  const observer = new ResizeObserver(([entry]) => {
    const dpc = entry.devicePixelContentBoxSize;
    canvas.width = dpc
      ? dpc[0].inlineSize
      : Math.round(entry.contentRect.width * window.devicePixelRatio);
    canvas.height = dpc
      ? dpc[0].blockSize
      : Math.round(entry.contentRect.height * window.devicePixelRatio);
    canvas.requestPaint();
  });

  const supportsDevicePixelContentBox =
    typeof ResizeObserverEntry !== "undefined" &&
    "devicePixelContentBoxSize" in ResizeObserverEntry.prototype;
  const options = supportsDevicePixelContentBox
    ? { box: "device-pixel-content-box" }
    : {};
  observer.observe(canvas, options);
</script>

WebGL-canvas

<canvas id="canvas" content="drawable" style="width: 400px; height: 400px;">
  <div id="ui-element" drawable>
    <p>WebGL UI Element</p>
    <button>Action</button>
  </div>
</canvas>

<script>
  const canvas = document.getElementById("canvas");
  const gl = canvas.getContext("webgl2");
  const uiElement = document.getElementById("ui-element");

  // getElementImageSize(), allocateElementTexture(), and uploadElementWebGL()
  // are defined in step 5.
  // computeCanvasTransform() is defined in step 6.

  // Setup WebGL texture...
  const texture = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D, texture);
  const textureState = { width: 0, height: 0 };

  canvas.onpaint = () => {
    // 1. Update texture with HTML content
    try {
      uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
    } catch (err) {
      console.error('texElementSubImage2D copy failed:', err);
    }

    // ... Render your 3D scene here, calculating htmlElementMVP matrix ...

    // 2. Sync DOM position, hit testing, and accessibility bounds with 3D scene
    canvas.updateElementGeometry(uiElement, {
      canvasTransform: computeCanvasTransform(canvas, uiElement, htmlElementMVP),
    });
  };
</script>

WebGPU-canvas

<canvas id="canvas" content="drawable" style="width: 400px; height: 400px;">
  <div id="ui-element" drawable>
    <p>WebGPU UI Element</p>
  </div>
</canvas>

<script>
  const canvas = document.getElementById("canvas");
  const context = canvas.getContext("webgpu");
  const uiElement = document.getElementById("ui-element");

  // getElementImageSize() and ensureElementTexture() are defined in step 5.
  // computeCanvasTransform() is defined in step 6.

  // Setup WebGPU...
  // const device = ...
  const textureState = { texture: null };

  canvas.onpaint = () => {
    // 1. Copy HTML content to a texture that matches the element size
    const size = getElementImageSize(canvas, uiElement);
    if (size) {
      const previousTexture = textureState.texture;
      const texture = ensureElementTexture(device, textureState, size.width, size.height);
      if (texture !== previousTexture) {
        // New texture: create, or rebuild, the bind groups that reference it.
      }
      try {
        device.queue.drawElementImageToTexture({ source: uiElement }, { texture, size });
      } catch (err) {
        console.error('drawElementImageToTexture copy failed:', err);
      }
    }

    // ... Render your 3D scene here, calculating htmlElementMVP matrix ...

    // 2. Sync DOM position, hit testing, and accessibility bounds (same matrix math as WebGL)
    canvas.updateElementGeometry(uiElement, {
      canvasTransform: computeCanvasTransform(canvas, uiElement, htmlElementMVP),
    });
  };
</script>

Praktische tips

  • VERPLICHT: Controleer de browserondersteuning voor de HTML-in-Canvas API voordat u deze gebruikt.
  • VERPLICHT: Voeg altijd het kenmerk content="drawable" toe aan het element <canvas>.
  • VERPLICHT: Voeg het kenmerk drawable toe aan elk element dat u tekent, inclusief directe onderliggende elementen van het canvas.
  • VERPLICHT: Gebruik een onpaint-gebeurtenisverwerker om de HTML-content op het canvas te renderen.
  • VERPLICHT: Gebruik de methode drawElementImage in 2D of drawElementImageToTexture in WebGPU om de HTML-content weer te geven op het canvas.
  • VERPLICHT: Wijs in WebGL de textuurbuffer vooraf één keer toe met texImage2D() (wanneer deze wordt geïnitialiseerd of wanneer de elementgrootte verandert). Wijs de textuur alleen opnieuw toe als de grootte verandert en stel TEXTURE_MIN_FILTER in op LINEAR.
  • VERPLICHT: Gebruik in WebGL de methode texElementSubImage2D om de HTML-content te renderen naar een textuur die u vooraf toewijst met texImage2D(), met de grootte van captureElementImage().
  • VERPLICHT: Geef in WebGPU de textuur de grootte van captureElementImage() en maak deze alleen opnieuw als de grootte verandert. Maak de textuur met COPY_DST- en RENDER_ATTACHMENT-gebruik en geef de textuurgrootte door als size.
  • VERPLICHT: Synchroniseer de geometrie van het HTML-element met de gerenderde content. In 2D doet drawElementImage dit automatisch. Roep canvas.updateElementGeometry(element, { canvasTransform }) aan in WebGL en WebGPU.
  • VERPLICHT: Gebruik ResizeObserver om de schermgrootte te observeren en de canvasgrootte te updaten zodat deze overeenkomt met de apparaatpixels.
  • Sluit GEEN cross-origin content in een canvas in, want dat wordt niet ondersteund.
  • Initialiseer ResizeObserver NIET binnen de gebeurtenishandler onpaint, omdat dit kan leiden tot geheugenlekken.

Reservestrategieën

De HTML-in-Canvas API wordt op dit moment niet in alle moderne browsers ondersteund. Daarom is meestal een reservestrategie vereist.

Vanwege de verbeterde prestaties van deze API moet HTML-in-Canvas worden gebruikt als de browser dit ondersteunt.

De fallback-strategie is afhankelijk van de use case. Als HTML-in-Canvas bijvoorbeeld niet wordt ondersteund voor interactieve HTML-content in canvas, plaatst u de HTML-content boven op het canvas met CSS.

HTML-in-Canvas-polyfills

Gebruik het volgende polyfill-script om de HTML-in-Canvas API na te bootsen in browsers die deze niet ondersteunen.

  1. Installeer of sluit de bibliotheek in:

    # Install
npm install three-html-render

    # Embed
<script src="https://cdn.jsdelivr.net/npm/three-html-render/dist/polyfill.js"></script>

  2. Voer de methode installHtmlInCanvasPolyfill() uit om HTML-in-Canvas te vertalen.