تعديلات على HTML-in-Canvas: تكرار لتحسين Web API

قدّم الإصداران 150 و155 من Chrome عدة تغييرات على واجهة برمجة التطبيقات HTML-in-Canvas API. وقد استجابت هذه التغييرات لملاحظات المنتدى والمعايير بهدف تحسين سهولة استخدام واجهة برمجة التطبيقات. يوضح منشور المدوّنة هذا التغييرات، وكيفية التأكّد من أنّ عملية التنفيذ التي أجريتها متوافقة معها.

وتشمل التحديثات إعادة تسمية السمات والطرق، وطلب تخصيص مسبق صريح لذاكرة النسيج، وتحديث نماذج مزامنة DOM. بالإضافة إلى ذلك، تم تمديد مرحلة التجربة والتقييم لميزة HTML-in-Canvas. في ما يلي شرح للتغييرات التي سيتم إجراؤها وسببها وكيفية تعديل قاعدة الرموز البرمجية.

التغييرات في الإصدار 150 من Chrome

في الإصدار 150 من Chrome، غيّرنا توقيعات الوسيطات في WebGL وWebGPU لإزالة التكرار والتوافق مع اصطلاحات الرسومات الحديثة.

WebGL

لقد أزلنا الوسيطات المكرّرة (level وsrcFormat وdestType) من texElementImage2D (يمكنك الاطّلاع على مناقشة WebGL لمزيد من التفاصيل):

// 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 في كائنَي sourceDict وdestDict (راجِع GPUWeb PR#6250):

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

التغييرات في الإصدار 155 من Chrome

يقدّم الإصدار 155 من Chrome تحسينات إضافية استنادًا إلى ملاحظات المطوّرين. نحن بصدد تعديل أسماء الطرق، ما يتطلّب تخصيصًا مسبقًا صريحًا لذاكرة الزخرفة، وإتاحة استخدام أشجار DOM الفرعية المعقّدة، وفصل مزامنة DOM.

WebGPU

تمت إعادة تسمية طريقة WebGPU من copyElementImageToTexture إلى drawElementImageToTexture. بالإضافة إلى إعادة التسمية، يتم توسيع إحداثيات المَعلمات (sourceX، sourceWidth)، ويتم تجميع حدود الوجهة في عنصر size (GPUExtent3D) عادي:

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

هناك ثلاثة جوانب للتغييرات في WebGL لـ HTML-in-Canvas:

  • يتغيّر اسم الطريقة من texElementImage2D إلى texElementSubImage2D.`
  • تتغيّر طريقة التوقيع، والأهم من ذلك أنّها تضيف الوسيطتَين xoffset وyoffset للسماح اختياريًا بتحديد إزاحة في النسيج الوجهة الذي سيتم رسم العنصر فيه.
  • لم تعُد الطريقة تخصص مساحة تخزين مؤقتة تلقائيًا لنسيج الوجهة، بل يجب تخصيص مساحة التخزين بشكل صريح قبل استخدام واجهة برمجة التطبيقات. وهذا مشابه لسلوك texSubImage2D.
// 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
);

سمات اللوحة والعناصر الثانوية القابلة للرسم

نحن بصدد تعديل طريقة إعداد لوحة الرسم لعرض HTML.

جارٍ إعادة تسمية "layoutsubtree" إلى "content="drawable""

للتوافق مع اصطلاحات تسمية سمات HTML، تمت إعادة تسمية السمة المنطقية layoutsubtree في العنصر <canvas> إلى content="drawable" (راجِع المشكلة رقم 169 في WICG للاطّلاع على مناقشة تفصيلية).

سمة drawable للعناصر الفرعية

في السابق، كان يتم عرض العناصر الثانوية المباشرة فقط في لوحة الرسم. لإتاحة التسلسلات الهرمية المعقّدة لنموذج DOM بدون تسوية الترميز، يمكنك الآن إضافة السمة drawable بشكل صريح إلى أي عنصر فرعي تريد رسمه بشكل مستقل:

<!-- 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 شجرة فرعية كاملة باستثناء العناصر الفرعية المضمّنة التي تحدّد أيضًا السمة drawable. يتيح ذلك تحريك الحاويات الرئيسية والعناصر الفرعية مثل الأزرار ورسمها في طلبات رسم منفصلة.

مزامنة اختبار مؤشر الماوس

في السابق، كان على المطوّرين تسجيل القيمة المعروضة من طرق الرسم وتوجيهها إلى element.style.transform. تعرض طريقة drawElementImage() الآن void، وتعتمد المزامنة على السياق.

سياقات ثنائية الأبعاد: المزامنة التلقائية

في لوحة الرسم الثنائية الأبعاد، يزامن المتصفّح تلقائيًا حدود اختبار مؤشر الماوس في نموذج العناصر في المستند (DOM) وحلقات التركيز في قارئ الشاشة مع الإحداثيات المرسومة. يمكنك إزالة جميع عمليات تحويل البيانات اليدوية:

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

لإدارة الشكل الهندسي يدويًا في الوضع الثنائي الأبعاد، مرِّر { preserveElementGeometry: true } إلى drawElementImage() وطبِّق عمليات التحويل باستخدام canvas.updateElementGeometry().

السياقات الثلاثية الأبعاد: updateElementGeometry() صريحة

لمزامنة DOM في سياقات WebGL أو WebGPU، أنشئ تحويل DOMMatrix ومرِّره إلى canvas.updateElementGeometry():

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

التوافق بين الإصدارات المختلفة

إذا كان تطبيقك يحتاج إلى دعم المستخدمين على إصدارات Chrome المتعددة خلال الفترة الانتقالية، تحقَّق من توفّر الطرق المعدَّلة في النماذج الأولية واضبط عملية التنفيذ وفقًا لذلك.

تأكَّد من ضبط سمات عنصر <canvas> الصحيحة لكل إصدار من المتصفّح:

// ============================================================================
//  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، افحص القيمة المعروضة لـ drawElementImage() وتحقَّق من سمات النموذج الأوّلي للّوحة لإتاحة كلا الإصدارَين:

// ============================================================================
// 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، استخدِم توقيع الطريقة واسمها المتوافقَين:

// ============================================================================
// 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:

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

إضافة مرحلة التجربة والتقييم

تم تمديد مرحلة التجربة والتقييم لميزة HTML-in-Canvas حتى الإصدار 160 من Chrome. يُرجى التأكّد من تجديد الرمز المميّز لمرحلة التجربة والتقييم لمواصلة تقديم ميزة HTML-in-Canvas للمستخدمين. يُرجى الاطّلاع على مقالة "مرحلة التجربة والتقييم" لمزيد من التفاصيل.

مشاركة ملاحظاتك

يُرجى إعلامنا بكيفية عمل هذه التعديلات في تطبيقاتك من خلال الإبلاغ عن مشكلة في مستودع WICG GitHub. اشترِك في النشرة الإخبارية للمطوّرين للاطّلاع على آخر الأخبار حول HTML-in-Canvas.