Eksportowanie treści HTML z obszaru roboczego

Aplikacje internetowe często muszą przechwytywać i eksportować rozbudowane treści HTML, takie jak dostosowane panele, stylizowane dokumenty czy interaktywne wykresy, jako obrazy statyczne lub nagrania wideo. W przeszłości wymagało to użycia dużych bibliotek innych firm, które ręcznie analizowały węzły DOM i właściwości CSS, aby odtworzyć wizualną kopię na elemencie canvas. To podejście jest kosztowne pod względem obliczeniowym, podatne na błędy i często nie obsługuje nowoczesnych funkcji układu CSS. Dzięki interfejsowi HTML-in-Canvas API deweloperzy mogą renderować rzeczywiste elementy DOM bezpośrednio w kontekście Canvas. Ponieważ natywny mechanizm renderowania przeglądarki renderuje poddrzewo HTML z dokładnością co do piksela, przechwytywanie dokładnych danych wyjściowych w postaci obrazu lub strumienia wideo jest bardzo wydajne dzięki wbudowanym metodom canvas, takim jak toDataURL(), toBlob() lub captureStream().

Jak to zrobić?

1. Sprawdź, czy przeglądarka obsługuje HTML-in-Canvas:

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

2. Zainicjuj obszar roboczy, aby obsługiwał renderowanie elementów HTML potomnych, dodając atrybut content="drawable" do elementu HTML <canvas>. Umieść zawartość HTML w elemencie <canvas> i dodaj atrybut drawable do każdego elementu, który rysujesz. Element z atrybutem drawable przechwytuje swoje poddrzewo, z wyjątkiem zagnieżdżonych elementów podrzędnych, które również mają atrybut drawable:

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

3. Aby zapobiec rozmyciu, przeskaluj siatkę obszaru roboczego, aby dopasować ją do współczynnika skalowania urządzenia:

   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);
   

4. Wyrenderuj treść HTML na obszarze roboczym w module obsługi zdarzeń canvas.onpaint.

5. W kontekście 2D użyj metody drawElementImage. Rysuje ostatni zrzut elementu drawable i jego poddrzewo możliwe do narysowania (z wyłączeniem innych elementów podrzędnych możliwych do narysowania), zaczynając od pola obramowania elementu, przed przekształceniami CSS:

canvas.onpaint = () => {
  ctx.reset();
  // Draw the form element at x:0, y:0
  ctx.drawElementImage(form_element, 0, 0);
};

• W kontekstach WebGL i WebGPU kopiujesz element do tekstury. Rozmiar tekstury: canvas.captureElementImage(element). Wartości width i height są podane w pikselach siatki obszaru roboczego (magazynu zapasowego), więc zaokrąglij je w górę za pomocą Math.ceil(). captureElementImage() zgłasza błąd, jeśli element nie ma jeszcze rekordu renderowania: wywołaj requestPaint() i spróbuj ponownie przy następnym zdarzeniu paint.

// 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;
}

• W kontekście WebGL najpierw wstępnie przydziel podkład tekstury za pomocą metody texImage2D. We fragmentach kodu w tym przewodniku używany jest kontekst WebGL 2 (canvas.getContext("webgl2")). Przydziel miejsce na tekstury, wywołując texImage2D() z null zamiast danych pikseli, co spowoduje zarezerwowanie pamięci GPU o określonym rozmiarze i formacie bez przesyłania pikseli. Przestrzegaj tych zasad:
  • Zmień rozmiar tekstury na captureElementImage(), jak pokazano powyżej.
  • Przydzielaj poziom 0 tylko przy pierwszym przesłaniu lub gdy zmieni się rozmiar, ponieważ ponowne przydzielenie powoduje wyczyszczenie tekstury. Używaj pamięci zmiennej: rozmiaru niezmiennej pamięci texStorage2D() nie można zmienić, gdy zmienia się rozmiar elementu.

// 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 };

• Następnie w kontekście WebGL wyrenderuj zawartość HTML do tekstury za pomocą metody texElementSubImage2D. Przestrzegaj tych zasad:
  • Przekaż { width, height } w konfiguracji. Sprawia, że kopia wypełnia przydzieloną teksturę niezależnie od tego, jak skalowany jest obszar roboczy.
  • Jeśli rozmiar się zmienił, ponownie przydziel teksturę, jak pokazano powyżej.

// 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);
  }
};

• W kontekście WebGPU użyj metody drawElementImageToTexture. Przestrzegaj tych zasad:
  • Utwórz teksturę z użyciem COPY_DST i RENDER_ATTACHMENT, a następnie dodaj TEXTURE_BINDING, aby próbkować ją w programach do cieniowania. Nieprawidłowe użycie jest zgłaszane jako błąd weryfikacji WebGPU, a nie jako wyjątek.
  • Przekaż rozmiar tekstury jako size. Bez size większy element jest przycinany do tekstury. W przypadku wartości size element jest skalowany, aby wypełnić obszar.
  • Odtwórz teksturę, gdy zmieni się rozmiar elementu, i ponownie utwórz grupy powiązań, które się do niej odwołują.

// 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);
  }
};

Jeśli do renderowania sceny używasz pętli requestAnimationFrame, wywołaj w niej funkcję canvas.requestPaint(), aby mieć pewność, że treść HTML zostanie wyrenderowana na elemencie canvas. event.changedElements zawiera listę elementów, których renderowanie uległo zmianie. Pamiętaj, aby przerysować element lub ponownie przesłać jego teksturę tylko wtedy, gdy nastąpiła aktualizacja podrzędnych elementów HTML:

  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 5
  };

1. Zsynchronizuj geometrię elementu.

Przeglądarka musi wiedzieć, gdzie jest rysowany element HTML, aby jego pozycja DOM odpowiadała narysowanym pikselom, np. aby użytkownicy mogli go kliknąć i wpisać w nim tekst. Obszar roboczy testuje pozycję wskaźnika tylko w przypadku elementów narysowanych za pomocą metody 2D drawElementImage() lub zarejestrowanych za pomocą updateElementGeometry().

• W przypadku kontekstu 2D przeglądarka automatycznie synchronizuje element. drawElementImage() dopasowuje granice testu pozycji wskaźnika DOM i pierścienie zaznaczenia czytnika ekranu do narysowanych współrzędnych, więc nie musisz ustawiać style.transform. Aby ręcznie zarządzać geometrią, np. gdy rysujesz ten sam element więcej niż raz, przekaż { preserveElementGeometry: true } do drawElementImage() i zastosuj przekształcenia za pomocą canvas.updateElementGeometry().

• W przypadku 3D z WebGL lub WebGPU element canvas nie może określić, gdzie jest rysowany element HTML, więc musisz mu to wskazać. Oblicz DOMMatrix, który mapuje obramowanie elementu w pikselach CSS na obszar roboczy w pikselach CSS. Przeglądarka musi zmapować przestrzeń współrzędnych 3D na przestrzeń współrzędnych CSS za pomocą przekształcenia widocznego obszaru. Aby to zrobić:

  • Znormalizuj element HTML. Rozmiary elementów HTML są podawane w pikselach (np. szerokość 200 pikseli). WebGL zwykle traktuje obiekty jako „kwadraty jednostkowe”, na przykład w zakresie od -0,5 do 0,5. Jeśli nie znormalizujesz, przycisk o rozmiarze 200 pikseli będzie wyglądał na 200 razy większy. Ten krok odwraca też oś Y, ponieważ w CSS kierunek w dół jest dodatni, a w WebGL – w górę.
  • Przekształć macierz MVP WebGL w macierz DOM.
  • Mapowanie na widoczny obszar obszaru roboczego. Ten krok to faza „ponownego skalowania”: rozciąga matematykę przestrzeni jednostkowej z powrotem, aby dopasować ją do wymiarów pikseli CSS elementu <canvas> na ekranie, i odwraca oś Y.
  • Oblicz ostateczne przekształcenie. Pomnóż macierze w kolejności: widoczny obszar * MVP * normalizacja. Połączenie ich w jedną ostateczną transformację tworzy „mapę”, która dokładnie wskazuje przeglądarce, gdzie powinien znajdować się element HTML, aby był wyrównany z rysunkiem 3D. Przeglądarka wykonuje podział perspektywy.

  // 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);
  }
  

Następnie przekaż przekształcenie do canvas.updateElementGeometry() jako canvasTransform. Spowoduje to przeniesienie elementu HTML bezpośrednio na wyrenderowane piksele. Dzięki temu, gdy użytkownik kliknie przycisk lub zaznaczy tekst, faktycznie trafi na rzeczywisty element HTML. Przeglądarka używa też przekształcenia do określenia granic ułatwień dostępu elementu, na przykład w przypadku pierścieni zaznaczenia czytnika ekranu:

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

Do kontrolowania testu pozycji wskaźnika służą te opcje:

• Każde wywołanie updateElementGeometry() przenosi element na górę kolejności testu pozycji wskaźnika. Przekaż { preserveHitTestOrder: true }, aby utrzymać pozycję.
• Wywołaj canvas.clearElementGeometry(element), aby usunąć element z testu pozycji wskaźnika, np. gdy go ukryjesz.

1. Użyj zwykłych metod eksportowania obszaru roboczego, takich jak toDataURL(), toBlob() lub captureStream(). Wyeksportowane dane będą zawierać wyrenderowaną zawartość HTML.

Przykładowy kod

<body>
    <canvas id="canvas" style="width: 400px; height: 200px;" content="drawable">
        <input id="element" drawable>
    </canvas>
    
    <button id="download">Download Image</button>

    <script>
        const canvas = document.getElementById('canvas');
        const ctx = canvas.getContext('2d');
        const element = document.getElementById('element');
        const download = document.getElementById('download');

        canvas.onpaint = (event) => {
            ctx.reset();
            // Draw the element into the canvas. The browser synchronizes its
            // DOM position for hit testing (typing).
            ctx.drawElementImage(element, 10, 10);
        };

        download.onclick = () => {
            // Export the canvas content as an image
            const dataURL = canvas.toDataURL('image/png');
            const link = document.createElement('a');
            link.download = 'exported-canvas.png';
            link.href = dataURL;
            link.click();
        };

        // Re-initialize canvas size on screen resize
        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>
</body>

Sprawdzone metody

• OBOWIĄZKOWO: przed użyciem interfejsu HTML-in-Canvas API sprawdź, czy przeglądarka go obsługuje.
• OBOWIĄZKOWO: zawsze dodawaj atrybut content="drawable" do elementu <canvas>.
• OBOWIĄZKOWO: dodaj atrybut drawable do każdego rysowanego elementu, w tym do elementów podrzędnych obszaru roboczego.
• OBOWIĄZKOWO: użyj modułu obsługi zdarzeń onpaint, aby wyrenderować zawartość HTML na elemencie canvas.
• OBOWIĄZKOWE: użyj metody drawElementImage w przypadku 2D lub drawElementImageToTexture w przypadku WebGPU, aby wyrenderować zawartość HTML na elemencie canvas.
• OBOWIĄZKOWO: w WebGL wstępnie przydziel bufor tekstury za pomocą texImage2D() (podczas inicjowania lub zmiany rozmiaru elementu). Zmieniaj przydział tekstury tylko wtedy, gdy zmienia się rozmiar, i ustaw TEXTURE_MIN_FILTER na LINEAR.
• OBOWIĄZKOWO: w WebGL użyj metody texElementSubImage2D, aby wyrenderować zawartość HTML do tekstury wstępnie przydzielonej za pomocą texImage2D() o rozmiarze captureElementImage().
• OBOWIĄZKOWE: w WebGPU określ rozmiar tekstury na podstawie captureElementImage() i twórz ją ponownie tylko wtedy, gdy rozmiar się zmieni. Utwórz teksturę z użyciem COPY_DST i RENDER_ATTACHMENT, a następnie przekaż rozmiar tekstury jako size.
• OBOWIĄZKOWO: zsynchronizuj geometrię elementu HTML z wyrenderowaną treścią. W trybie 2D drawElementImage robi to automatycznie. W WebGL i WebGPU wywołaj canvas.updateElementGeometry(element, { canvasTransform }).
• OBOWIĄZKOWO: użyj ResizeObserver, aby sprawdzić rozmiar ekranu i zaktualizować rozmiar obszaru roboczego, aby pasował do pikseli urządzenia.
• NIE umieszczaj treści z innych domen w obszarze roboczym, ponieważ nie jest to obsługiwane.
• NIE inicjuj ResizeObserver w module obsługi zdarzeń onpaint, ponieważ może to prowadzić do wycieków pamięci.

Strategie zastępcze

Interfejs HTML-in-Canvas API nie jest obecnie obsługiwany we wszystkich nowoczesnych przeglądarkach, dlatego zwykle wymagana jest strategia zastępcza. Jednak ze względu na lepszą wydajność tego interfejsu API należy używać HTML-in-Canvas, jeśli przeglądarka go obsługuje.

W przypadku, gdy zawartość HTML musi zostać wyeksportowana z elementu canvas, użyj bibliotek takich jak html2canvas, dom-to-image lub snapdom.

Aby rejestrować interakcje HTML klatka po klatce, np. na potrzeby strumieniowania, rejestruj mutacje DOM za pomocą bibliotek takich jak rrweb.

Możesz też wyświetlić ostrzeżenie, że eksportowanie multimediów HTML nie jest obsługiwane w przeglądarce, ponieważ nie obsługuje ona HTML-in-Canvas.