WebGL-shaders bieden krachtige GPU-versnelde visuele effecten, waardoor geavanceerde mogelijkheden zoals dynamische rimpelvervormingen, belichtingsmodellen, kleurcorrectie en aangepaste hoekpunttransformaties mogelijk zijn. Met de HTML-in-Canvas API kunnen ontwikkelaars WebGL-texturen toepassen op HTML-content. Hiermee kunnen krachtige fragment- en vertex-shaders native worden toegepast op volledig interactieve UI-componenten, zoals knoppen, invoervelden en tekst met opmaak, terwijl de native toegankelijkheid, tekstselectie en DOM-gebeurtenisverwerking behouden blijven.
Hoe wordt dit geïmplementeerd
Controleer of HTML-in-Canvas wordt ondersteund in de browser:
if ('content' in HTMLCanvasElement.prototype) { // Use HTML in Canvas API } else { // Use fallback strategy }Voeg het kenmerk
content="drawable"toe aan het HTML-element<canvas>.Plaats uw HTML-content in het element
<canvas>en voeg het kenmerkdrawabletoe aan elk element dat u tekent. Een element metdrawablelegt de substructuur vast, behalve geneste onderliggende elementen die ookdrawablezijn.<canvas id="canvas" content="drawable"> <div id="html-content" drawable></div> </canvas>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);Wijs de textuurbacking eerst vooraf toe met de methode
texImage2D. De fragmenten in deze handleiding gebruiken een WebGL 2-context (canvas.getContext("webgl2")).
Wijs eerst 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
canvas.captureElementImage(element). Dewidthenheightzijn in canvasrasterpixels (backing store), dus rond ze naar boven af metMath.ceil().captureElementImage()genereert een fout als het element nog geen tekenrecord heeft: roeprequestPaint()aan en probeer het opnieuw bij de volgendepaint-gebeurtenis. - 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.
// 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;
}
// 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 };
Render de HTML-content naar de textuur in een
canvas.onpaint-gebeurtenisverwerker met de methodetexElementSubImage2D. Volg deze regels:- Een element kan pas worden geüpload nadat het canvas het heeft getekend. Upload de factuur via de gebeurtenis
painten belcanvas.requestPaint()om een factuur aan te vragen. - 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 getoond in stap 5.
- Een element kan pas worden geüpload nadat het canvas het heeft getekend. Upload de factuur via de gebeurtenis
// 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 (step 5).
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);
}
};
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 je de textuur alleen 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) {
// Update the texture with uploadElementWebGL()
}
// Render the scene, and sync the element geometry as shown in step 7
};
- Synchroniseer de elementgeometrie.
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. - Geef
{ canvasClip }, eenDOMRectInitin de coördinatenruimte vancanvasTransform, door om het gebied dat kan worden getest op hits te beperken, bijvoorbeeld als maar een deel van het element wordt getekend.
Voorbeeldcode
<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() and allocateElementTexture() are defined in step 5.
// uploadElementWebGL() is defined in step 6.
// computeCanvasTransform() is defined in step 7.
// 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>
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 ALTIJD het kenmerk
drawabletoe aan de directe onderliggende elementen van het canvas. - VERPLICHT: Voeg het kenmerk
drawabletoe aan elk element dat u onafhankelijk van de bovenliggende elementen wilt kunnen tekenen. - VERPLICHT: Gebruik een
onpaint-gebeurtenisverwerker om de HTML-content op het canvas te renderen. - VERPLICHT: Wijs de textuurbuffer vooraf toe met
texImage2D()(wanneer deze wordt geïnitialiseerd of wanneer de elementgrootte verandert). Wijs de textuur alleen opnieuw toe als de grootte verandert en stelTEXTURE_MIN_FILTERin opLINEAR. - VERPLICHT: Gebruik de methode
texElementSubImage2Dom de HTML-content weer te geven in een textuur die u vooraf toewijst mettexImage2D(), met een grootte vancaptureElementImage(). - VERPLICHT: Synchroniseer de geometrie van het HTML-element met de gerenderde content door
canvas.updateElementGeometry(element, { canvasTransform })aan te roepen. - VERPLICHT: Gebruik
ResizeObserverom 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
ResizeObserverNIET binnen de gebeurtenishandleronpaint, 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 polyfill
Gebruik het volgende polyfill-script om de HTML-in-Canvas API na te bootsen in browsers die deze niet ondersteunen.
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>Voer de methode
installHtmlInCanvasPolyfill()uit om HTML-in-Canvas te vertalen.