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

في البنية منذ اليوم الأوّل

محتوى الـ canvas غير مرئيّ لقارئات الشاشة بطبيعته. ولا يتعامل doper مع إمكانية الوصول بوصفها طبقة تُضاف بعد الإطلاق: تحتفظ النواة بشجرة دلالية (role / label / value / bounds / focusable)، وتحوّلها ‏@dopejs/pingo-a11y تزايديًا إلى شجرة DOM ظلّية مطلقة الموضع بجوار الـ canvas.

العناصر الظلّية شفّافة بصريًا لكنّها موجودة في شجرة إمكانية الوصول وفي ترتيب التنقّل بمفتاح Tab، ويُحوَّل التركيز عليها إلى جلسة التحرير في المحرّك، فيتمكّن مستخدم لوحة المفاتيح من تشغيل حقول الإدخال داخل الـ canvas فعليًا.

إعلان الدلالة

<container semanticRole="region" semanticLabel="لوحة الدفع">
  <text value="الدفع" semanticRole="heading" semanticLabel="الدفع" />
  {TextField({ semanticLabel: "المستلِم", value, revision })}
</container>

يملك editableText دلالة textbox افتراضيًا. ولا تدخل قيمة حقل كلمة المرور أبدًا في الشجرة الدلالية.

اختبارات E2E قائمة على الدلالة

لأنّ الشجرة الدلالية تُعكس إلى DOM حقيقي، تستطيع اختبارات E2E اختيار العناصر بالدور والاسم بدل مقارنة البكسلات:

import { getByRole, queryAllByRole } from "@dopejs/pingo";

const email = getByRole(document.body, "textbox", { name: "المستلِم" });
email.focus(); // يُحوَّل إلى جلسة التحرير في المحرّك
expect(queryAllByRole(document.body, "textbox")).toHaveLength(2);

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

مراقبة الشجرة الدلالية

const root = await createHostedCanvasRoot(canvas, {
  onSemantics: (nodes) => inspect(nodes),
  accessibility: true, // مفعّل افتراضيًا، ويعطّل false الشجرة الظلّية
});

تعطي كلّ عقدة nodeId وrole وlabel وvalue وbounds في إحداثيات العالم وfocusable وfocused وراية password. ويتيح dirtySemanticsNodes في تشخيص الإطار مراقبة وتيرة الإبطال الدلالي.

تأهيل المنصّة

تغطّي الأتمتة تصدير الشجرة الدلالية، وتحويلها إلى الشجرة الظلّية، ومحدِّدات الدور والتسمية، وعقد لوحة المفاتيح. أمّا مصفوفة سلوك قارئات الشاشة الحقيقية (VoiceOver وNVDA وTalkBack) فتندرج تحت تأهيل المنصّة، وتُتابَع على حدة ولا تُحتسب شرطًا لإنهاء العمل الهندسي. وهذا الفصل يمنع تقديم استنتاجات غير مُتحقَّق منها عن الأجهزة على أنّها وعد بالدعم.

يمكنك قراءة الشجرة الدلالية الحالية مباشرةً في عرض الدلالة داخل Playground.