HTML-in-Canvas güncellemeleri: Daha iyi bir Web API'si için yineleme

Chrome 150 ve 155 sürümlerinde HTML-in-Canvas API'de çeşitli değişiklikler yapıldı. Bu değişiklikler, API'nin ergonomisini iyileştirmek amacıyla topluluk ve standartlarla ilgili geri bildirimlere yanıt olarak yapılmıştır. Bu blog yayınında, değişiklikler ve uygulamanızın bu değişikliklerle güncel olmasını nasıl sağlayabileceğiniz açıklanmaktadır.

Güncellemeler arasında özelliklerin ve yöntemlerin yeniden adlandırılması, açık doku belleği ön tahsisinin zorunlu kılınması ve DOM senkronizasyon modellerinin güncellenmesi yer alıyor. Ayrıca, HTML-in-Canvas kaynak denemesi uzatıldı. Aşağıda nelerin değiştiği, neden değiştiği ve kod tabanınızı nasıl güncelleyeceğiniz açıklanmaktadır.

Chrome 150'deki değişiklikler

Chrome 150'de, WebGL ve WebGPU'daki bağımsız değişken imzalarını değiştirerek fazlalıkları ortadan kaldırdık ve modern grafik kurallarına uygun hale getirdik.

WebGL

texElementImage2D öğesinden gereksiz bağımsız değişkenleri (level, srcFormat, destType) kaldırdık (daha fazla bilgi için WebGL tartışmasına bakın):

// Old implementation (Chrome < 150)
const level = 0;
const internalFormat = gl.RGBA;
const srcFormat = gl.RGBA;
const destType = gl.UNSIGNED_BYTE;

gl.texElementImage2D(
  gl.TEXTURE_2D,
  level,
  internalFormat,
  srcFormat,
  destType,
  element
);

// New implementation (from Chrome 150)
const internalFormat = gl.RGBA8;
gl.texElementImage2D(gl.TEXTURE_2D, internalFormat, element);

WebGPU

copyElementImageToTexture parametrelerini sourceDict ve destDict nesneleri olarak standartlaştırdık (GPUWeb PR#6250 adresini inceleyin):

// Old implementation (Chrome < 150)
GPUQueue.copyElementImageToTexture(
  element,
  width,
  height,
  { texture: texture }
);

// New implementation (from Chrome 150)
const sourceDict = { source: element };
const destDict = {
  destination: { texture: texture },
  width: width,
  height: height
};

GPUQueue.copyElementImageToTexture(sourceDict, destDict);

Chrome 155'teki değişiklikler

Chrome 155, geliştirici geri bildirimlerine dayalı daha fazla iyileştirme sunuyor. Yöntem adlarını güncelliyor, açık doku belleği ön tahsisini zorunlu kılıyor, karmaşık DOM alt ağaçlarını destekliyor ve DOM senkronizasyonunu ayırıyoruz.

WebGPU

copyElementImageToTexture olan WebGPU yönteminin adı drawElementImageToTexture olarak değiştirildi. Yeniden adlandırmanın yanı sıra parametre koordinatları genişletilir (sourceX, sourceWidth) ve hedef sınırları standart bir size (GPUExtent3D) nesnesinde gruplandırılır:

// BEFORE (Chrome 150)
const sourceDict = {
  source: myElement,
  sx: 0,
  sy: 0,
  swidth: 100,
  sheight: 100
};
const destDict = {
  destination: { texture: myTexture },
  width: 300,
  height: 200
};

queue.copyElementImageToTexture(sourceDict, destDict);

// AFTER (Chrome 155+)
const sourceDict = {
  source: myElement,
  sourceX: 0,
  sourceY: 0,
  sourceWidth: 100,
  sourceHeight: 100
};
const destDict = {
  texture: myTexture,
  size: { width: 300, height: 200 }
};

queue.drawElementImageToTexture(sourceDict, destDict);

WebGL

HTML-in-Canvas için WebGL'deki değişikliklerin üç yönü vardır:

  • Yöntem adı texElementImage2D yerine texElementSubImage2D olarak değiştirildi.`
  • Yöntem imzası değişir. En önemlisi, isteğe bağlı olarak öğenin çizileceği hedef dokuya bir ofset belirtilmesine olanak tanıyan xoffset ve yoffset bağımsız değişkenlerini ekler.
  • Yöntem artık hedef doku için otomatik olarak arabellek depolama alanı ayırmaz. Depolama alanı, API kullanılmadan önce açıkça ayrılmalıdır. Bu, texSubImage2D davranışına benzer.
// 1. Capture natural layout size of the element
const elementImage = canvas.captureElementImage(element);

// 2. Pre-allocate texture backing once (or when element resizes)
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texImage2D(
  gl.TEXTURE_2D,
  0,
  gl.RGBA8,
  Math.ceil(elementImage.width),
  Math.ceil(elementImage.height),
  0,
  gl.RGBA,
  gl.UNSIGNED_BYTE,
  null // null reserves VRAM without uploading pixels
);

// 3. Upload DOM into pre-allocated VRAM
gl.texElementSubImage2D(
  gl.TEXTURE_2D,
  0,                  // level
  0,                  // xoffset
  0,                  // yoffset
  element             // pass DOM element
);

Canvas özellikleri ve çizilebilir alt öğeler

HTML oluşturmak için tuvalinizi hazırlama şeklinizi güncelliyoruz.

layoutsubtree, content="drawable" olarak yeniden adlandırılıyor

HTML özellik adlandırma kurallarına uymak için <canvas> öğesindeki boole layoutsubtree özelliği content="drawable" olarak yeniden adlandırıldı (ayrıntılı bilgi için WICG Sorun #169 sayfasına bakın).

Alt öğeler için drawable özelliği

Daha önce yalnızca bir tuvalin doğrudan alt öğeleri oluşturuluyordu. İşaretlemeyi düzleştirmeden karmaşık DOM hiyerarşilerini desteklemek için artık bağımsız olarak çizmek istediğiniz tüm alt öğelere drawable özelliğini açıkça ekleyebilirsiniz:

<!-- BEFORE -->
<canvas layoutsubtree>
  <div id="badge">
    <h2>Player Stats</h2>
    <button id="actionBtn">Equip</button>
  </div>
</canvas>

<!-- AFTER (Chrome 155+) -->
<canvas content="drawable">
  <!-- Subtree A (Body and heading) -->
  <div id="badge" drawable>
    <h2>Player Stats</h2>
    <!-- Subtree B (Excluded from Subtree A; drawn and animated independently) -->
    <button id="actionBtn" drawable>Equip</button>
  </div>
</canvas>

drawable içeren bir öğe, drawable belirten iç içe yerleştirilmiş alt öğeler hariç tüm alt ağacını yakalar. Bu sayede, üst kapsayıcılar ve düğmeler gibi alt öğeler ayrı çekim çağrılarında canlandırılıp çizilebilir.

İsabet testi senkronizasyonu

Daha önce geliştiriciler, çizim yöntemlerinden döndürülen değeri yakalayıp element.style.transform yöntemine aktarmak zorundaydı. drawElementImage() yöntemi artık void döndürüyor ve senkronizasyon bağlama bağlı.

2D Bağlamlar: Otomatik Senkronizasyon

2D tuvalde tarayıcı, DOM isabet testi sınırlarını ve ekran okuyucu odak halkalarını çizilen koordinatlarla otomatik olarak senkronize eder. Tüm manuel dönüşüm borularını kaldırabilirsiniz:

// BEFORE
const transform = ctx.drawElementImage(element, x, y);
element.style.transform = transform.toString();

// AFTER (Chrome 155+)
ctx.drawElementImage(element, x, y);
// No style update needed: position & hit-testing sync automatically

2D'de geometriyi manuel olarak yönetmek için { preserveElementGeometry: true } değerini drawElementImage() öğesine iletin ve canvas.updateElementGeometry() kullanarak dönüşümleri uygulayın.

3D Bağlamlar: Açık updateElementGeometry()

WebGL veya WebGPU bağlamlarında DOM'yi senkronize etmek için bir DOMMatrix dönüşümü oluşturun ve bunu canvas.updateElementGeometry()'e iletin:

canvas.addEventListener('paint', () => {
  // 1. Upload element snapshot to GPU texture
  device.queue.drawElementImageToTexture({ source: element }, { texture });

  // 2. Render 3D scene...
  drawScene();

  // 3. Construct transform matrix as needed
  const canvasTransform = new DOMMatrix().translate(x, y);

  // 4. Update DOM hit-testing and accessibility bounding boxes
  canvas.updateElementGeometry(element, { canvasTransform });
});

Sürümler arası uyumluluk

Uygulamanızın geçiş döneminde birden fazla Chrome sürümündeki kullanıcıları desteklemesi gerekiyorsa prototiplerinde güncellenmiş yöntemlerin olup olmadığını kontrol edin ve uygulamanızı buna göre ayarlayın.

Her tarayıcı sürümü için doğru <canvas> öğe özelliklerini ayarladığınızdan emin olun:

// ============================================================================
//  Cross-version canvas markup
// ============================================================================
if (!canvas.hasAttribute('content') && !canvas.hasAttribute('layoutsubtree')) {
  if ('content' in HTMLCanvasElement.prototype) {
    // Chrome 155+ (New standardized attribute)
    canvas.setAttribute('content', 'drawable');
  } else {
    // Chrome < 155 (Legacy boolean attribute)
    canvas.setAttribute('layoutsubtree', '');
  }
}

2D bağlam için drawElementImage() işlevinin döndürdüğü değeri inceleyin ve her iki sürümü de desteklemek için tuval prototip özelliklerini kontrol edin:

// ============================================================================
// Cross-version 2D drawing & synchronization
// ============================================================================
function draw2DElement(ctx, element, x, y) {
  // Execute the 2D draw call
  const result = ctx.drawElementImage(element, x, y);

  if (result !== undefined && typeof result?.toString === 'function') {
    // Chrome < 155: drawElementImage returned a DOMMatrix
    // Requires manual transform piping to align DOM hit-test bounds:
    element.style.transform = result.toString();
  } else {
    // Chrome 155+: drawElementImage returns void / undefined
    // The browser automatically aligns DOM positioning, clicks, and a11y bounds!
    // If you previously had element.style.transform logic here, clear it:
    if (element.style.transform) {
      element.style.transform = "";
    }
  }
}

WebGPU için uyumlu yöntem imzasını ve adını kullanın:

// ============================================================================
// WebGPU cross-version support
// ============================================================================
if ('drawElementImageToTexture' in GPUQueue.prototype) {
  // Chrome 155+ (Latest implementation)
  queue.drawElementImageToTexture(
    { source: element, sourceX: 0, sourceY: 0, sourceWidth: w, sourceHeight: h },
    { texture: myTexture, size: { width: w, height: h } }
  );
} else if (typeof queue.copyElementImageToTexture === "function") {
  // Chrome 150 - 154: Try the Chrome 150+ dictionary signature first,
  // then fall back to the Chrome < 150 signature
  try {
    queue.copyElementImageToTexture(
      { source: element },
      { destination: { texture: myTexture }, width: w, height: h }
    );
  } catch (err) {
    // Chrome < 150
    queue.copyElementImageToTexture(element, { texture: myTexture });
  }
}

WebGL için tarayıcı uyumluluğunu kontrol ettiğinizden emin olun:

// ============================================================================
// WebGL cross-version support
// ============================================================================
if ('texElementSubImage2D' in WebGL2RenderingContext.prototype) {
  // Chrome 155+ (Explicit pre-allocation + sub-image)
  gl.texElementSubImage2D(gl.TEXTURE_2D, 0, 0, 0, element);
} else if (gl.texElementImage2D && gl.texElementImage2D.length === 3) {
  // Chrome 150-154 (3-argument signature)
  gl.texElementImage2D(gl.TEXTURE_2D, gl.RGBA8, element);
} else if (gl.texElementImage2D) {
  // Chrome < 150 (6-argument signature)
  gl.texElementImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, element);
}

Kaynak denemesi uzantısı

HTML-in-Canvas kaynak denemesi, Chrome 160'a kadar uzatıldı. Kullanıcılarınıza HTML-in-Canvas özelliğini sunmaya devam etmek için kaynak denemesi jetonunuzu yenilemeyi unutmayın. Daha fazla bilgi için kaynak denemesi makalesini inceleyin.

Görüşlerinizi paylaşın

WICG GitHub deposunda sorun bildirerek bu güncellemelerin uygulamalarınızda nasıl çalıştığını bize bildirin. HTML-in-Canvas ile ilgili haberleri takip etmek için geliştirici bültenine abone olun.