Canvas-Inhalte für Browserfunktionen verfügbar machen

Webfunktionen: HTML in Canvas

Reguläre <canvas>-Inhalte sind für Browserfunktionen wie Screenreader, Indexierung, Übersetzungstools, Bedienungshilfen, die Suche auf der Seite, Drucken usw. nicht zugänglich. Mit HTML in canvas können Sie echtes DOM direkt in einem Canvas-Element rendern. Wenn Sie das Attribut content="drawable" einem HTML-Element <canvas> hinzufügen, werden die untergeordneten HTML-Elemente angeordnet. Mit dem Attribut drawable werden die Elemente markiert, die im Rendering-Kontext des Canvas gerendert werden können. Sie können damit Text in einem Canvas formatieren und anordnen, Canvas-Inhalte für Browserfunktionen wie Bedienungshilfen, Übersetzung oder Suche auf der Seite verfügbar machen und 2D- und 3D-Effekte auf HTML anwenden.

Implementierung

  1. Prüfen Sie, ob HTML-in-Canvas im Browser unterstützt wird:

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

  2. Fügen Sie dem HTML-Element <canvas> das Attribut content="drawable" hinzu.

  3. Platziere deinen HTML-Inhalt innerhalb des <canvas>-Elements und füge jedem Element, das du zeichnest, das Attribut drawable hinzu. Ein Element mit drawable erfasst seinen Unterbaum, mit Ausnahme von verschachtelten Nachfolgerelementen, die ebenfalls drawable sind.

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

  4. Skalieren Sie das Canvas-Raster so, dass es dem Skalierungsfaktor des Geräts entspricht, um Unschärfe zu vermeiden:

    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. Rendern Sie den HTML-Inhalt im Canvas innerhalb eines canvas.onpaint-Event-Handlers. Ein Element kann erst gezeichnet werden, nachdem es vom Canvas gerendert wurde. Rufe canvas.requestPaint() auf, um ein paint-Ereignis anzufordern.

  • Verwenden Sie im 2D-Kontext die Methode drawElementImage. Es zeichnet den letzten Snapshot eines drawable-Elements und seines zeichenbaren Unterbaums, beginnend am Rahmen des Elements, vor CSS-Transformationen:
canvas.onpaint = () => {
  ctx.reset();
  // Draw the form element at x:0, y:0
  ctx.drawElementImage(form_element, 0, 0);
};
  • In WebGL- und WebGPU-Kontexten kopieren Sie das Element in eine Textur. Größe der Textur von canvas.captureElementImage(element) festlegen. Die Werte für width und height werden in Pixeln des Zeichenflächenrasters (Backing Store) angegeben. Runden Sie sie daher mit Math.ceil() auf. captureElementImage() löst einen Fehler aus, wenn das Element noch keinen Paint-Eintrag hat: Rufen Sie requestPaint() auf und versuchen Sie es beim nächsten paint-Ereignis noch einmal.
// 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;
}
  • Weisen Sie im WebGL-Kontext zuerst die Texturunterstützung mit der Methode texImage2D vorab zu. Die Snippets in diesem Leitfaden verwenden einen WebGL 2-Kontext (canvas.getContext("webgl2")). Weisen Sie Texturspeicher zu, indem Sie texImage2D() mit null anstelle von Pixeldaten aufrufen. Dadurch wird GPU-Speicher der angegebenen Größe und des angegebenen Formats reserviert, ohne dass Pixel hochgeladen werden. Beachten Sie dabei folgende Regeln:
    • Passen Sie die Größe der Textur von captureElementImage() an, wie oben gezeigt.
    • Weisen Sie Ebene 0 nur beim ersten Upload oder bei einer Größenänderung zu, da die Textur durch die Neuzuweisung gelöscht wird. Veränderlichen Speicher verwenden: Die Größe von unveränderlichem texStorage2D()-Speicher kann nicht geändert werden, wenn sich die Größe des Elements ändert.
// 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 };
  • Rendern Sie dann im WebGL-Kontext den HTML-Inhalt mit der Methode texElementSubImage2D in die Textur. Beachten Sie dabei folgende Regeln:
    • Übergeben Sie { width, height } in der Konfiguration. Die Kopie füllt die zugewiesene Textur aus, unabhängig davon, wie der Canvas skaliert wird.
    • Weisen Sie die Textur neu zu, wenn sich die Größe geändert hat, wie oben gezeigt.
// 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);
  }
};
  • Verwenden Sie im WebGPU-Kontext die Methode drawElementImageToTexture. Beachten Sie dabei folgende Regeln:
    • Erstelle die Textur mit der Verwendung COPY_DST und RENDER_ATTACHMENT und füge TEXTURE_BINDING hinzu, um sie in Shadern zu sampeln. Eine falsche Verwendung wird als WebGPU-Validierungsfehler und nicht als Ausnahme gemeldet.
    • Übergeben Sie die Texturgröße als size. Ohne size wird ein größeres Element auf die Textur zugeschnitten. Bei size wird das Element so skaliert, dass es den Bereich ausfüllt.
    • Die Größe von WebGPU-Texturen kann nicht geändert werden. Die Textur wird neu erstellt, wenn sich die Elementgröße ändert, und die Bindungsgruppen, die darauf verweisen, werden neu erstellt.
// 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);
  }
};

Wenn Sie eine requestAnimationFrame-Schleife zum Rendern der Szene verwenden, rufen Sie canvas.requestPaint() innerhalb der Schleife auf, damit der HTML-Inhalt auf dem Canvas gerendert wird. event.changedElements listet die Elemente auf, deren Rendering sich geändert hat. Achten Sie darauf, dass Sie das Element nur dann neu zeichnen oder seine Textur neu hochladen, wenn die untergeordneten HTML-Elemente aktualisiert wurden:

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. Synchronisieren Sie die Elementgeometrie.

Der Browser muss wissen, wo das HTML-Element gezeichnet wird, damit die DOM-Position mit den gezeichneten Pixeln übereinstimmt. Die Trefferprüfung, z. B. für Klicks und Textauswahl, und die Barrierefreiheit im Internet verwenden diese Geometrie: Ein drawable-Element, dessen Geometrie nicht aktualisiert wird, wird weiterhin im Baum für die Barrierefreiheit im Internet angezeigt, jedoch ohne Geometrieinformationen. Ein Canvas führt nur Trefferprüfungen für Elemente durch, die mit der 2D-Methode drawElementImage() gezeichnet oder mit updateElementGeometry() registriert wurden.

  • Im Fall des 2D-Kontexts synchronisiert der Browser das Element automatisch. drawElementImage() richtet die DOM-Trefferprüfungsgrenzen und die Fokusringe des Screenreaders an den gezeichneten Koordinaten aus, sodass Sie style.transform nicht festlegen müssen. Wenn Sie die Geometrie manuell verwalten möchten, z. B. wenn Sie dasselbe Element mehrmals zeichnen, übergeben Sie { preserveElementGeometry: true } an drawElementImage() und wenden Sie Transformationen mit canvas.updateElementGeometry() an.

  • Im 3D-Fall mit WebGL oder WebGPU kann das Canvas nicht erkennen, wo das HTML-Element gezeichnet wird. Sie müssen es also angeben. Berechnen Sie eine DOMMatrix, die die Rahmenbox des Elements in CSS-Pixeln dem Canvas in CSS-Pixeln zuordnet. Der Browser muss den 3D-Koordinatenraum mithilfe einer Darstellungsbereichstransformation in den CSS-Koordinatenraum umwandeln. Gehen Sie dazu so vor:

    • Normalisieren Sie das HTML-Element. Die Größe von HTML-Elementen wird in Pixeln angegeben (z. B. 200 px breit). WebGL behandelt Objekte jedoch normalerweise als „Einheitsquadrate“, z.B.im Bereich von -0,5 bis 0,5. Wenn Sie die Werte nicht normalisieren, wird die 200 Pixel große Schaltfläche 200-mal größer dargestellt. In diesem Schritt wird auch die Y-Achse umgedreht, da in CSS nach unten positiv ist, in WebGL jedoch nach oben.
    • Konvertieren Sie die WebGL-MVP-Matrix in eine DOM-Matrix.
    • Ordnen Sie die Daten dem Darstellungsbereich des Canvas zu. Dieser Schritt ist die „Neuskalierungsphase“: Die mathematischen Werte des Einheitsraums werden wieder so gestreckt, dass sie den CSS-Pixelabmessungen des <canvas>-Elements auf dem Bildschirm entsprechen, und die Y-Achse wird wieder umgedreht.
    • Berechnen Sie die endgültige Transformation. Multiplizieren Sie die Matrizen in der folgenden Reihenfolge: Darstellungsbereich * MVP * Normalisierung. Wenn Sie sie zu einer endgültigen Transformation kombinieren, entsteht eine „Karte“, die dem Browser genau mitteilt, wo sich das HTML-Element befinden soll, damit es mit der 3D-Zeichnung übereinstimmt. Der Browser führt die perspektivische Teilung durch.
    // 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);
}

Übergeben Sie dann die Transformation als canvasTransform an canvas.updateElementGeometry(). Dadurch wird das HTML-Element direkt über den gerenderten Pixeln platziert. So wird sichergestellt, dass Nutzer, die auf eine Schaltfläche klicken oder Text auswählen, tatsächlich das echte HTML-Element treffen. Der Browser verwendet die Transformation auch für die Grenzen der Barrierefreiheit des Elements, z. B. für Fokusringe von Screenreadern:

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

Mit diesen Optionen können Sie die Trefferprüfung steuern:

  • Mit jedem updateElementGeometry()-Aufruf wird das Element an den Anfang der Trefferprüfungsreihenfolge verschoben. Karte/Ticket „{ preserveHitTestOrder: true }“ behält die Position.
  • Rufen Sie canvas.clearElementGeometry(element) auf, um ein Element aus der Trefferprüfung zu entfernen, z. B. wenn Sie es ausblenden.

Beispielcode

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>

Best Practices

  • OBLIGATORISCH: Prüfen Sie die Browserunterstützung für die HTML-in-Canvas API, bevor Sie sie verwenden.
  • OBLIGATORISCH: Fügen Sie dem <canvas>-Element immer das Attribut content="drawable" hinzu.
  • ERFORDERLICH: Fügen Sie jedem Element, das Sie zeichnen, das Attribut drawable hinzu, einschließlich direkter untergeordneter Elemente des Canvas.
  • OBLIGATORISCH: Verwenden Sie einen onpaint-Event-Handler, um den HTML-Inhalt auf dem Canvas zu rendern.
  • VERPFLICHTEND: Verwenden Sie die Methode drawElementImage in 2D oder drawElementImageToTexture in WebGPU, um den HTML-Inhalt auf dem Canvas zu rendern.
  • OBLIGATORISCH: In WebGL muss der Texturpuffer einmalig mit texImage2D() vorab zugewiesen werden (bei der Initialisierung oder wenn sich die Elementgröße ändert). Weisen Sie die Textur nur dann neu zu, wenn sich die Größe ändert, und setzen Sie TEXTURE_MIN_FILTER auf LINEAR.
  • ERFORDERLICH: Verwenden Sie in WebGL die Methode texElementSubImage2D, um den HTML-Inhalt in einer Textur zu rendern, die Sie vorab mit texImage2D() zuweisen und deren Größe Sie mit captureElementImage() festlegen.
  • OBLIGATORISCH: In WebGPU muss die Größe der Textur aus captureElementImage() stammen und die Textur darf nur neu erstellt werden, wenn sich die Größe ändert. Erstellen Sie die Textur mit der Verwendung COPY_DST und RENDER_ATTACHMENT und übergeben Sie die Texturgröße als size.
  • OBLIGATORISCH: Synchronisieren Sie die Geometrie des HTML-Elements mit dem gerenderten Inhalt. In 2D erledigt drawElementImage das automatisch. Rufen Sie in WebGL und WebGPU canvas.updateElementGeometry(element, { canvasTransform }) auf.
  • OBLIGATORISCH: Verwenden Sie ResizeObserver, um die Bildschirmgröße zu beobachten und die Canvas-Größe an die Gerätepixel anzupassen.
  • Betten Sie KEINE ursprungsübergreifenden Inhalte in einen Canvas ein, da dies nicht unterstützt wird.
  • Initialisieren Sie ResizeObserver NICHT im onpaint-Event-Handler, da dies zu Speicherlecks führen kann.

Fallback-Strategien

Die HTML-in-Canvas API wird derzeit nicht in allen modernen Browsern unterstützt. Daher ist in der Regel eine Fallback-Strategie erforderlich.

Aufgrund der verbesserten Leistung dieser API sollte HTML-in-Canvas jedoch verwendet werden, wenn der Browser dies unterstützt.

Die Fallback-Strategie hängt vom Anwendungsfall ab. Wenn HTML-in-Canvas beispielsweise nicht unterstützt wird, platzieren Sie den HTML-Inhalt mithilfe von CSS über dem Canvas.

HTML-in-Canvas-Polyfills

Verwenden Sie das folgende Polyfill-Skript, um die HTML-in-Canvas API in Browsern zu simulieren, die sie nicht unterstützen.

  1. Installieren oder binden Sie die Bibliothek ein:

    # Install
npm install three-html-render

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

  2. Führen Sie die Methode installHtmlInCanvasPolyfill() aus, um HTML-in-Canvas zu übersetzen.