עדכונים ב-HTML-in-Canvas: שיפורים ב-Web API

בגרסאות 150 ו-155 של Chrome, הוספנו כמה שינויים ל-HTML-in-Canvas API. השינויים האלה בוצעו בתגובה למשוב מהקהילה ומהתקנים, במטרה לשפר את הארגונומיה של ה-API. בפוסט הזה בבלוג מתוארים השינויים ומוסבר איך לוודא שההטמעה שלכם מעודכנת בהתאם.

העדכונים כוללים שינוי שמות של מאפיינים ושיטות, דרישה להקצאה מראש של זיכרון טקסטורה מפורש ועדכון של מודלים לסנכרון DOM. בנוסף, גרסת המקור לניסיון של HTML-in-Canvas הורחבה. בהמשך מוסבר מה משתנה, למה ואיך לעדכן את בסיס הקוד.

שינויים ב-Chrome 150

בגרסת Chrome 150, שינינו את חתימות הארגומנטים ב-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);

שינויים ב-Chrome 155

בגרסה 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.`
  • חתימת ה-method משתנה. השינוי המשמעותי ביותר הוא הוספת הארגומנטים xoffset ו-yoffset, שמאפשרים לציין היסט (offset) בטקסטורת היעד שבה רוצים לשרטט את הרכיב.
  • השיטה כבר לא מקצה באופן אוטומטי אחסון במאגר לטקסטורת היעד. צריך להקצות את האחסון באופן מפורש לפני השימוש ב-API. ההתנהגות הזו דומה לזו של 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
);

מאפייני קנבס ורכיבי צאצא שניתן לצייר

אנחנו מעדכנים את האופן שבו אתם מכינים את ה-canvas לעיבוד 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. כך אפשר להנפיש ולשרטט קונטיינרים הורים ורכיבי צאצא כמו כפתורים בבקשות נפרדות להזזת פריט גרפי (draw call).

סנכרון של בדיקת מיקום המצביע

בעבר, המפתחים היו צריכים לתעד את הערך המוחזר משיטות השרטוט ולהעביר אותו אל element.style.transform. השיטה drawElementImage() מחזירה עכשיו void, והסנכרון תלוי בהקשר.

הקשרים דו-ממדיים: סנכרון אוטומטי

ב-Canvas בדו-ממד, הדפדפן מסנכרן באופן אוטומטי את גבולות בדיקת מיקום המצביע ב-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', '');
  }
}

בהקשר דו-ממדי, בודקים את הערך המוחזר של drawElementImage() ואת מאפייני אב הטיפוס של ה-canvas כדי לתמוך בשתי הגרסאות:

// ============================================================================
// 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 ב-Canvas", חשוב לחדש את האסימון של גרסת המקור לניסיון. פרטים נוספים זמינים במאמר בנושא גרסת מקור לניסיון.

שיתוף משוב

נשמח לקבל מכם משוב על העדכונים האלה באפליקציות שלכם. אתם יכולים לדווח על בעיה במאגר GitHub של WICG. כדאי להירשם לניוזלטר למפתחים כדי להתעדכן בכל החדשות בנושא HTML ב-Canvas.