Canvas içeriğini tarayıcı özelliklerine gösterme

Normal <canvas> içeriği; ekran okuyucular, dizine ekleme, çeviri araçları, erişilebilirlik için yardımcı araçlar, sayfada bul, yazdır gibi tarayıcı özelliklerine açık değildir. HTML in canvas ile gerçek DOM'u doğrudan bir canvas öğesinde oluşturabilirsiniz. <canvas> HTML öğesine content="drawable" özelliğini eklediğinizde alt HTML öğeleri düzenlenir. drawable özelliği ise tuvalin oluşturma bağlamında oluşturabileceğiniz öğeleri işaretler. Bu API'yi kullanarak tuvaldeki metinleri biçimlendirebilir ve düzenleyebilir, tuval içeriğini tarayıcı özelliklerine (ör. erişilebilirlik, çeviri veya sayfada bulma) sunabilir ve HTML'ye 2D ve 3D efektler uygulayabilirsiniz.

Nasıl uygulanır?

1. Tarayıcıda HTML-in-Canvas'ın desteklenip desteklenmediğini kontrol edin:

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

2. <canvas> HTML öğesine content="drawable" özelliğini ekleyin.

3. HTML içeriğinizi <canvas> öğesinin içine yerleştirin ve çizdiğiniz her öğeye drawable özelliğini ekleyin. drawable içeren bir öğe, kendisi de drawable olan iç içe yerleştirilmiş alt öğeler hariç olmak üzere alt ağacını yakalar.

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

4. Bulanıklığı önlemek için tuval ızgaranızı cihazın ölçeklendirme faktörüne uyacak şekilde ölçeklendirin:

   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. HTML içeriğini, bir canvas.onpaint etkinlik işleyicinin içindeki tuvalde oluşturun. Bir öğe yalnızca tuval tarafından boyandıktan sonra çizilebilir: paint etkinliği istemek için canvas.requestPaint() yöntemini çağırın.

• 2D bağlamda drawElementImage yöntemini kullanın. CSS dönüşümlerinden önce, öğenin kenarlık kutusundan başlayarak bir drawable öğesinin ve çizilebilir alt ağacının son anlık görüntüsünü çizer:

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

• WebGL ve WebGPU bağlamlarında öğeyi bir dokuya kopyalarsınız. Dokuyu canvas.captureElementImage(element) olarak boyutlandırın. width ve height değerleri, tuval ızgarası (yedekleme deposu) piksel cinsinden olduğundan Math.ceil() ile yukarı yuvarlayın. Öğenin henüz boyama kaydı yoksa captureElementImage() hata verir: requestPaint() yöntemini çağırın ve bir sonraki paint etkinliğinde tekrar deneyin.

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

• WebGL bağlamında, önce texImage2D yöntemini kullanarak doku desteğini önceden tahsis edin. Bu kılavuzdaki snippet'ler WebGL 2 bağlamını (canvas.getContext("webgl2")) kullanır. Piksel verileri yerine null ile texImage2D() yöntemini çağırarak doku depolama alanı ayırın. Bu yöntem, piksel yüklemeden belirli boyut ve biçimdeki GPU belleğini ayırır. Aşağıdaki kurallara uyun:
  • Yukarıda gösterildiği gibi dokuyu captureElementImage() boyutuna getirin.
  • Yeniden tahsis etme işlemi dokuyu temizlediğinden, 0. seviyeyi yalnızca ilk yüklemede veya boyut değiştiğinde tahsis edin. Değişebilir depolama alanı kullanın: Değişmez texStorage2D() depolama alanı, öğenin boyutu değiştiğinde yeniden boyutlandırılamaz.

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

• Ardından, WebGL bağlamında texElementSubImage2D yöntemini kullanarak HTML içeriğini dokuya dönüştürün. Aşağıdaki kurallara uyun:
  • Yapılandırmada { width, height } değerini iletin. Tuvalin nasıl ölçeklendirildiğine bakılmaksızın kopyanın ayrılan dokuyu doldurmasını sağlar.
  • Yukarıda gösterildiği gibi, boyut değiştiyse dokuyu yeniden tahsis edin.

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

• WebGPU bağlamında drawElementImageToTexture yöntemini kullanın. Aşağıdaki kurallara uyun:
  • Dokuyu COPY_DST ve RENDER_ATTACHMENT kullanımıyla oluşturun ve gölgelendiricilerde örneklemek için TEXTURE_BINDING ekleyin. Yanlış kullanım, istisna olarak değil, WebGPU doğrulama hatası olarak bildirilir.
  • Doku boyutunu size olarak iletin. size olmadan, daha büyük bir öğe dokuya kırpılır. size ile öğe, doldurulacak şekilde ölçeklendirilir.
  • WebGPU dokuları yeniden boyutlandırılamaz. Öğe boyutu değiştiğinde dokuyu yeniden oluşturun ve dokuya referans veren bağlama gruplarını yeniden oluşturun.

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

Sahneyi oluşturmak için requestAnimationFrame döngüsü kullanırken HTML içeriğinin tuvalde oluşturulmasını sağlamak için döngü içinde canvas.requestPaint() yöntemini çağırın. event.changedElements, oluşturma işlemi değişen öğeleri listeler. Alt HTML öğelerinde bir güncelleme yapıldıysa yalnızca öğeyi yeniden çizdiğinizden veya dokusunu yeniden yüklediğinizden emin olun:

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. Öğe geometrisini senkronize edin.

Tarayıcının, HTML öğesinin nerede çizildiğini bilmesi gerekir. Böylece DOM konumu, çizilen pikselleriyle eşleşir. Örneğin, tıklamalar ve metin seçimi için isabet testi ve erişilebilirlik bu geometriyi kullanır: Geometrisi güncellenmeyen bir drawable öğesi, geometri bilgisi olmadan erişilebilirlik ağacına maruz kalmaya devam eder. Tuval, yalnızca 2D drawElementImage() yöntemiyle çizilen veya updateElementGeometry() ile kaydedilen öğeleri isabet testine tabi tutar.

• 2D bağlam durumunda tarayıcı, öğeyi otomatik olarak senkronize eder. drawElementImage(), DOM isabet testi sınırlarını ve ekran okuyucu odak halkalarını çizilen koordinatlarla hizalar. Bu nedenle style.transform değerini ayarlamanız gerekmez. Geometriyi manuel olarak yönetmek için (örneğin, aynı öğeyi birden fazla kez çizdiğinizde) { preserveElementGeometry: true } değerini drawElementImage() değerine iletin ve canvas.updateElementGeometry() ile dönüşümleri uygulayın.

• WebGL veya WebGPU ile 3D durumunda, tuval HTML öğesinin nerede çizildiğini anlayamaz. Bu nedenle, bunu sizin belirtmeniz gerekir. Öğenin kenarlık kutusunu CSS pikseli cinsinden tuvale (CSS pikseli cinsinden) eşleyen bir DOMMatrix hesaplayın. Tarayıcının, görüntü alanı dönüşümü kullanarak 3D koordinat alanından CSS koordinat alanına eşleme yapması gerekir. Bunu kolaylaştırmak için aşağıdakileri yapın:

  • HTML öğesini normalleştirin. HTML öğeleri piksel cinsinden boyutlandırılır (ör. 200 piksel genişlik). Ancak WebGL, nesneleri genellikle "birim kareler" olarak ele alır (ör. -0,5 ile 0,5 arasında). Normalleştirme yapmazsanız 200 piksellik düğmeniz 200 kat daha büyük görünür. Bu adımda Y ekseni de ters çevrilir. CSS'de aşağı yön pozitifken WebGL'de yukarı yön pozitiftir.
  • WebGL MVP matrisini DOM matrisine dönüştürün.
  • Tuval görüntü alanıyla eşleştirin. Bu adım, "yeniden ölçeklendirme" aşamasıdır: Bu birim uzay matematiğini ekrandaki <canvas> öğenizin CSS piksel boyutlarıyla eşleşecek şekilde yeniden genişletir ve Y eksenini geri çevirir.
  • Nihai dönüşümü hesaplayın. Matrisleri şu sırayla çarpın: Görüntü alanı * MVP * Normalleştirme. Bunları tek bir nihai dönüşümde birleştirmek, tarayıcıya HTML öğesinin 3D çizimle hizalanması için tam olarak nerede bulunması gerektiğini söyleyen bir "harita" oluşturur. Tarayıcı, perspektif bölme işlemini gerçekleştirir.

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

Ardından dönüşümü canvas.updateElementGeometry() öğesine canvasTransform olarak iletin. Bu işlem, HTML öğesini doğrudan oluşturulan piksellerinin üzerine taşır. Bu sayede, kullanıcı bir düğmeyi tıkladığında veya metin seçtiğinde gerçek HTML öğesine ulaşır. Tarayıcı, öğenin erişilebilirlik sınırları için de dönüşümü kullanır (ör. ekran okuyucu odak halkaları için):

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

İsabet testini kontrol etmek için aşağıdaki seçenekleri kullanın:

• Her updateElementGeometry() çağrısı, öğeyi isabet testi sırasının en üstüne taşır. { preserveHitTestOrder: true } kartı, konumunu koruyacak.
• Bir öğeyi isabet testinden kaldırmak için (ör. gizlediğinizde) canvas.clearElementGeometry(element) yöntemini çağırın.

Örnek kod

2B Tuval

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

En İyi Uygulamalar

• ZORUNLU: HTML-in-Canvas API'yi kullanmadan önce tarayıcı desteğini kontrol edin.
• ZORUNLU: <canvas> öğesine her zaman content="drawable" özelliğini ekleyin.
• ZORUNLU: Tuvalin doğrudan alt öğeleri de dahil olmak üzere çizdiğiniz her öğeye drawable özelliğini ekleyin.
• ZORUNLU: HTML içeriğini tuvalde oluşturmak için bir onpaint etkinlik işleyici kullanın.
• ZORUNLU: HTML içeriğini tuvalde oluşturmak için 2D'de drawElementImage yöntemini veya WebGPU'da drawElementImageToTexture yöntemini kullanın.
• ZORUNLU: WebGL'de, doku arabelleğini texImage2D() ile bir kez önceden tahsis edin (başlatıldığında veya öğe boyutu değiştiğinde). Dokuyu yalnızca boyut değiştiğinde yeniden tahsis edin ve TEXTURE_MIN_FILTER değerini LINEAR olarak ayarlayın.
• ZORUNLU: WebGL'de, HTML içeriğini texImage2D() ile önceden tahsis ettiğiniz ve captureElementImage() boyutunda bir dokuya dönüştürmek için texElementSubImage2D yöntemini kullanın.
• ZORUNLU: WebGPU'da dokuyu captureElementImage() boyutuna getirin ve yalnızca boyut değiştiğinde yeniden oluşturun. Dokuyu COPY_DST ve RENDER_ATTACHMENT kullanımıyla oluşturun ve doku boyutunu size olarak iletin.
• ZORUNLU: HTML öğesinin geometrisini, oluşturulan içerikle senkronize edin. 2D'de drawElementImage bunu otomatik olarak yapar. WebGL ve WebGPU'da canvas.updateElementGeometry(element, { canvasTransform }) yöntemini çağırın.
• ZORUNLU: Ekran boyutunu gözlemlemek ve tuval boyutunu cihaz pikselleriyle eşleşecek şekilde güncellemek için ResizeObserver kullanın.
• Desteklenmediği için çapraz kaynaklı içerikleri tuvale YERLEŞTİRMEYİN.
• Bellek sızıntılarına yol açabileceğinden ResizeObserver öğesini onpaint etkinlik işleyicisinde ilk kullanıma hazırlamayın.

Yedek stratejiler

HTML-in-Canvas API şu anda tüm modern tarayıcılarda desteklenmediğinden genellikle bir yedek strateji gerekir.

Ancak bu API'nin sağladığı performans avantajları göz önüne alındığında, tarayıcı destekliyorsa HTML-in-Canvas kullanılmalıdır.

Yedek strateji, kullanım alanına bağlıdır. Örneğin, tuvaldeki etkileşimli bir HTML içeriği için Tuvalde HTML desteklenmiyorsa HTML içeriğini CSS kullanarak tuvalin üstüne yerleştirin.

Tuval içinde HTML polyfill'leri

HTML-in-Canvas API'yi desteklemeyen tarayıcılarda bu API'yi taklit etmek için aşağıdaki polyfill komut dosyasını kullanın.

1. Kitaplığı yükleyin veya yerleştirin:

   # Install
   npm install three-html-render
   

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

2. HTML-in-Canvas'ı çevirmek için installHtmlInCanvasPolyfill() yöntemini çalıştırın.