به‌روزرسانی‌های HTML-in-Canvas: تکرار به‌سمت میانای برنامه‌سازی کاربردی وب بهتر

Chrome 150 و 155 چندین تغییر در 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

‫Chrome 155 براساس بازخورد توسعه‌دهندگان، اصلاحات بیشتری را معرفی می‌کند. درحال به‌روزرسانی نام‌های روش هستیم، پیش‌تخصیص صریح حافظه بافت را الزامی می‌کنیم، از زیردرخت‌های پیچیده 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 را اضافه می‌کند تا به‌طور اختیاری امکان تعیین افست در بافت مقصد را که عنصر در آن ترسیم می‌شود فراهم کند.
  • این روش دیگر به‌طور خودکار فضای ذخیره‌سازی میان‌گیر را برای بافت مقصد اختصاص نمی‌دهد؛ فضای ذخیره‌سازی باید به‌طور صریح قبل‌از استفاده از 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" تغییر نام داده است (برای بحث مفصل، به مشکل 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', '');
  }
}

برای زمینه دوبعدی، مقدار برگشتی 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 تا Chrome 160 تمدید شده است. حتماً کد آزمایش معرفی ویژگی جدید را تمدید کنید تا همچنان بتوانید ویژگی HTML-in-Canvas را به کاربران ارائه دهید. برای جزئیات بیشتر، مقاله «آزمایش معرفی ویژگی جدید» را ببینید.

هم‌رسانی بازخورد

با ثبت مشکل در مخزن GitHub مربوط به WICG، به ما اطلاع دهید که این به‌روزرسانی‌ها چگونه در برنامه‌هایتان کار می‌کنند. به خبرنامه توسعه‌دهندگان بپیوندید تا از جدیدترین اخبار HTML-in-Canvas مطلع شوید.