الدليل التقني

التثبيت والإعداد والتكامل. وإن أردت قراءة الشيفرة، فالأداة كلها ملف واحد موثّق بالتعليقات.

التثبيت

ألصق وسمًا واحدًا قبل وسم إغلاق body. ولا حاجة لشيء آخر: لا خطوة بناء ولا مدير حزم ولا إطار عمل.

<script src="https://a11y.elixtechs.com/a11y/v1/loader.js?k=YOUR_SITE_KEY" async></script>

موقع واحد، بكل الميزات، وبدون بطاقة. وُجدت لتضع الأداة على صفحة حقيقية وترى التحليلات تتكوّن.

الاستضافة الذاتية

<script src="/assets/a11y/accessibility.js"
        data-a11y-auto
        data-a11y-lang="ar"
        data-a11y-fonts="/assets/a11y/fonts/"></script>

خيارات الإعداد

اضبط هذه من البوابة لكل موقع، أو مرّرها إلى المُهيِّئ مباشرة إن كنت تستضيف الأداة بنفسك.

خيارات الإعداد
Option	Default	Notes
`position`	`bottom-right`	Logical: right means the inline-end side, so it flips in RTL.
`lang`	`auto`	Resolves config → `<html lang>` → `navigator.language` → `en`.
`translations`	`null`	Merged over the built-ins, so a partial table falls back to the shipped strings.
`fontsPath`	next to the script	Where the woff2 files live.
`shortcut`	`alt+shift+a`	Matched by physical key too, so it survives a keyboard layout change.
`features`	`null`	Allowlist of feature ids. `null` means all.
`exclude`	`null`	Blocklist, applied after the allowlist.
`colorFilterTarget`	`html`	Leave this alone. See the trade-offs below.
`autoApplyOsPreferences`	`false`	When false, OS preferences are offered rather than imposed.
`statementUrl`	`null`	Optional link in the panel footer.
`zIndex`	`2147483000`	Below max int32, so a host can still deliberately go above it.

واجهة جافاسكربت

A11y.init(options)
A11y.get()                    // whole state
A11y.get('fontSize')          // one value
A11y.set('fontSize', 1.5)
A11y.patch({ contrast: 'high', highlightLinks: true })
A11y.applyProfile('dyslexia')
A11y.reset()
A11y.open() / .close() / .toggle()
A11y.setLanguage('ar')
A11y.announce('message')      // into the panel's live region
A11y.env()                    // detected OS / browser / OS preferences
A11y.features() / A11y.profiles()
A11y.destroy()                // removes every trace

الأحداث

document.addEventListener('a11y:ready',  e => e.detail); // { state, env }
document.addEventListener('a11y:change', e => e.detail); // { id, value, state }
document.addEventListener('a11y:open',   e => e.detail); // { state }
document.addEventListener('a11y:close',  e => e.detail); // { state }

A batch change — a profile or a reset — reports id as '*' with an array of the ids that changed.

مقايضات معروفة

موثّقة لأن مفاجأة في بيئة التشغيل أسوأ من تحفّظ مكتوب في الدليل.

مرشحات اللون والتثبيت

العنصر الذي يُطبَّق عليه مرشِّح يصبح الحاوية المرجعية لأبنائه المثبّتين، فتنزلق الترويسات الثابتة مع التمرير. ويُستثنى العنصر الجذر لأن المرشِّح عليه يُطبَّق على مساحة الرسم ولا ينشئ حاوية مرجعية. ولهذا يكون الجذر هو الهدف الافتراضي، وتغييره هو الخطوة الخطرة لا الآمنة.

التكبير لا يصلح كل تصميم

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

إزالة التشتيت متحفظة

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

دعم المتصفحات

كروم وإيدج 90 وما بعده، وفايرفوكس 90 وما بعده، وسفاري 15.4 وما بعده. والمتصفحات الأقدم تفقد قوة العزل أو تفصيلًا شكليًا، لا الوظيفة.

ما هي هذه الأداة، وما ليست هي

هذه الأداة مساعدة تُضاف فوق الموقع. تساعد الزائر على تكييف الصفحة مع طريقة قراءته، وتصلح مجموعة محددة من العيوب الشائعة. لكنها لا تجعل الموقع مطابقًا لمعايير WCAG أو ADA أو EN 301 549، ولا نبيعها على هذا الأساس. فعيوب الشيفرة تبقى عيوبًا: تستطيع الأداة إضافة تسمية ناقصة، لكنها لا تعرف معنى أيقونة غير مسمّاة، ولا تصلح ترتيب عناوين خاطئًا، ولا تُزيل مصيدة لوحة مفاتيح.