{"id":"l-a11y-4-3","courseId":"web-accessibility","lang":"ar","kind":"lesson","summary":"توقّع الاسم المتاح والوصف اللذين يحسبهما المتصفّح لأي عنصر تحكّم، وأعطِ أزرار الأيقونات والأزرار المكرّرة أسماء فريدة تطابق تسميتها المرئية.","html":"

في صفحة الفعالية في Ticketly ثلاثة أزرار كلها تقول “Book now”، وزر إغلاق يُظهر “×”، وزر بحث لا يحتوي إلا أيقونة SVG لعدسة مكبّرة، وزر للنشرة البريدية ضبط أحد المطوّرين اسمه إلى “newsletter-cta” لأغراض التحليلات. في قائمة الأزرار لدى قارئ الشاشة، تُقرأ الصفحة هكذا: “Book now, Book now, Book now, times, button, newsletter-cta”. كل واحدة من هذه مشكلة تسمية، وتُصلحها كلها بفهم خوارزمية واحدة.

\n

كيف يحسب المتصفّح الاسم

\n

تحدّد مواصفة Accessible Name and Description Computation الصادرة عن W3C بدقة كيف يختار المتصفّح الاسم المتاح (accessible name). وبتبسيط، يجرّب هذه المصادر بالترتيب ويأخذ أول مصدر يُنتج نصًا:

\n
    \n
  1. aria-labelledby: نص العناصر المُشار إليها، مضمومًا بمسافات، بترتيب الـ ids.
    2. \n
  2. aria-label: النص المكتوب في الخاصية.
    3. \n
  3. التسمية الأصلية: عنصر <label> لحقول النماذج، وalt للصور، و<legend> للـ fieldset، و<caption> للجدول، و<title> للـ SVG.
    4. \n
  4. المحتوى، للأدوار التي تسمح بذلك: الأزرار، والروابط، والعناوين، والتبويبات، وخلايا الجداول، وعناصر القوائم، والخيارات. النص الداخلي، مضافًا إليه alt الصور الداخلية، ومستبعدًا منه كل ما عليه aria-hidden="true".
    5. \n
  5. title (وplaceholder لحقول الإدخال) كملاذ أخير.
    6. \n
\n
\n سلّم من خمس درجات من الأعلى أولوية إلى الأدنى: aria-labelledby، ثم aria-label، ثم التسمية الأصلية مثل label أو alt أو legend، ثم المحتوى للأزرار والروابط والعناوين، وأخيرًا title أو placeholder. أول درجة تُنتج نصًا تصبح الاسم.\n \n 1 aria-labelledby\n \n 2 aria-label\n \n 3 label، alt، legend، caption\n \n 4 المحتوى (زر، رابط، عنوان)\n \n 5 title، placeholder\n \n أولوية\n أدنى\n
من أين يأتي الاسم، الأعلى أولوية أولًا
\n

نتيجتان تهمّان كل يوم. أولًا، تسمية ARIA تتجاوز النص المرئي: ما إن تضيف aria-label حتى يُتجاهَل محتوى الزر نفسه. ثانيًا، الأسماء لا تندمج: إن وُجدت aria-labelledby، تُتخطّى aria-label الخاصة بالعنصر. مع استثناء واحد: إن ضمّت aria-labelledby معرّف العنصر نفسه، فإن هذه الإشارة الذاتية تُحسب بقيمة aria-label إن وُجدت، لا بمحتوى العنصر. ويمكنك التحقّق من أي نتيجة في المتصفّح: لوحة Accessibility في Chrome وAccessibility Inspector في Firefox كلتاهما تعرضان الاسم المحسوب.

\n

أزرار الأيقونات فقط

\n

الزر الذي لا يحتوي إلا أيقونة ليس له محتوى نصي، فليس له اسم، إلا إن أعطيته واحدًا. ثلاثة خيارات، بترتيب الأفضلية:

\n
ticketly/header.html
<!-- 1. Visible text next to the icon: best for everyone -->\n<button type=\"button\" class=\"search\">\n  <svg aria-hidden=\"true\" viewBox=\"0 0 24 24\">…</svg>\n  Search\n</button>\n\n<!-- 2. Visually hidden text: the design stays icon-only -->\n<button type=\"button\" class=\"close\">\n  <span aria-hidden=\"true\">×</span>\n  <span class=\"visually-hidden\">Close banner</span>\n</button>\n\n<!-- 3. aria-label: fine, but invisible to translation tools that skip attributes -->\n<button type=\"button\" class=\"close\" aria-label=\"Close banner\">\n  <span aria-hidden=\"true\">×</span>\n</button>
\n

لاحظ aria-hidden="true" على الرمز “×”. من دونها، سيكون اسم الخيار 2 هو “× Close banner”، وتقرؤه بعض قارئات الشاشة “times Close banner”.

\n\n

الأزرار المكرّرة ومعيار Label in Name

\n

ثلاثة أزرار “Book now” مقبولة بصريًا، لأن كل واحد منها يقع في بطاقته. لكنها في قائمة الأزرار لا يمكن التمييز بينها. تريد أسماء مثل “Book now, Friday pass” دون تغيير التصميم المرئي. يمكن لـ aria-labelledby أن تشير إلى الزر نفسه إضافةً إلى عنوان البطاقة:

\n
HTML
<article>\n  <h3 id=\"fri-title\">Friday pass</h3>\n  <button type=\"button\" id=\"fri-book\" aria-labelledby=\"fri-book fri-title\">Book now</button>\n</article>
\n

يصبح الاسم “Book now Friday pass”. تأتي الكلمات المرئية أولًا، وهذا مهم لمعيار 2.5.3 Label in Name ‏(A): يجب أن يحتوي الاسم المتاح التسمية المرئية، وأفضل ممارسة أن يبدأ بها. تقول دينا، التي تستخدم التحكّم الصوتي، “click Book now”؛ فيجد برنامجها التطابقات الثلاثة ويرقّمها لتختار منها. لو كان الاسم “Reserve Friday” لما كان أمامها أي طريقة لنقره بنطق ما تراه. وهذا بالضبط ما كان خاطئًا في زر “newsletter-cta”: الكلمة المرئية “Subscribe” ليست في الاسم إطلاقًا. احذف الـ aria-label فيعود المحتوى ليمنح الاسم الصحيح.

\n

الأوصاف

\n

الوصف (description) معلومات ثانوية تُعلَن بعد الاسم والدور، عادةً بعد توقّف قصير. تعمل aria-describedby مثل aria-labelledby لكنها تغذّي الوصف بدلًا من الاسم:

\n
HTML
<label for=\"promo\">Promo code</label>\n<input id=\"promo\" aria-describedby=\"promo-hint\">\n<p id=\"promo-hint\">Codes are 8 letters, for example HARBOUR8.</p>
\n

يقرأ NVDA: “Promo code, edit text, Codes are 8 letters, for example HARBOUR8.” استخدم الأوصاف للتلميحات والصيغ ورسائل الخطأ، كما فعلت في درس النماذج. اجعل الاسم قصيرًا والوصف اختياريًا: يستطيع المستخدمون تخطّي الوصف، لكنهم لا يستطيعون تخطّي الاسم.

\n\n

صار لكل عنصر تحكّم في Ticketly اسم يستطيع الإنسان نطقه. وينظر الدرس الأخير في هذا القسم في الكلمات نفسها: اللغة البسيطة، وخصائص اللغة التي تجعل محتوى Ticketly العربي يُنطق بشكل صحيح.

\n","toc":[{"id":"sec-1","text":"كيف يحسب المتصفّح الاسم","level":2},{"id":"sec-2","text":"أزرار الأيقونات فقط","level":2},{"id":"sec-3","text":"الأزرار المكرّرة ومعيار Label in Name","level":2},{"id":"sec-4","text":"الأوصاف","level":2}],"takeaways":["يحسب المتصفّح اسم عنصر التحكّم بترتيب ثابت: aria-labelledby، ثم aria-label، ثم التسمية الأصلية (label وalt وlegend وcaption)، ثم محتوى العنصر، ثم title.","aria-labelledby وaria-label تتجاوزان كل ما سواهما، بما في ذلك النص المرئي، فاستخدمهما بحذر.","يجب أن تظهر التسمية المرئية داخل الاسم المتاح (2.5.3 Label in Name)، ويُفضَّل أن تكون في بدايته، ليستطيع مستخدمو التحكّم الصوتي نطق ما يرونه.","aria-describedby تضيف معلومات ثانوية تُقرأ بعد الاسم والدور؛ وهي للتلميحات والأخطاء، لا للاسم نفسه."],"further":[{"title":"W3C: Accessible Name and Description Computation 1.2","url":"https://www.w3.org/TR/accname-1.2/"},{"title":"W3C APG: Providing Accessible Names and Descriptions","url":"https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/"},{"title":"W3C: Understanding 2.5.3 Label in Name","url":"https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html"}],"quiz":[{"q":"

ما الاسم المتاح لهذا الزر؟

\n
HTML
<h3 id=\"fri\">Friday pass</h3>\n<button id=\"b1\" aria-label=\"Buy\" aria-labelledby=\"b1 fri\">Book now</button>
\n","options":[{"text":"“Buy”","why":"aria-labelledby أعلى أولوية من aria-label على الزر، فيضمّ الاسم أيضًا العنوانَ المُشار إليه."},{"text":"“Book now”","why":"المحتوى هنا هو المصدر الأدنى أولوية. وخاصيتا ARIA كلتاهما أعلى منه."},{"text":"“Buy Friday pass”","why":"صحيح. تفوز aria-labelledby وتضمّ نصوص العناصر المُشار إليها بالترتيب. وحين تصل الخوارزمية إلى الزر نفسه عبر تلك القائمة، تتخطّى aria-labelledby (تجنّبًا للدوران في حلقة) وتأخذ المصدر التالي، أي aria-label بقيمة “Buy”. فلا يدخل النص المرئي “Book now” في الاسم إطلاقًا، وهذا يخالف أيضًا معيار Label in Name."},{"text":"“Book now Friday pass”","why":"هذا ما ستحصل عليه لو لم تكن هناك aria-label. أما معها، فالإشارة إلى الزر نفسه تُحسب “Buy” لا محتواه."}],"answer":2},{"q":"

يقول مستخدم تحكّم صوتي “click Get tickets”. فلا يحدث شيء. لماذا؟

\n
HTML
<a href=\"/tickets\" aria-label=\"Purchase festival passes\">Get tickets</a>
\n","options":[{"text":"لا يمكن تفعيل الروابط بالتحكّم الصوتي","why":"التحكّم الصوتي يفعّل الروابط طوال الوقت. يكفي أن تطابق الكلمات الاسم."},{"text":"الـ aria-label يحلّ محلّ النص المرئي، فلا يحتوي الاسم “Get tickets”","why":"صحيح. هذا يخالف معيار 2.5.3 Label in Name. احذف الـ aria-label، أو ابدأه بالكلمات المرئية، مثل “Get tickets for Harbour Lights”."},{"text":"يحتاج الرابط إلى role=“button” ليمكن التحكّم فيه صوتيًا","why":"إنه ينقل المستخدم، فهو رابط عن حق. والدور لا علاقة له بالمطابقة الصوتية."}],"answer":1},{"q":"

أيّ عنصر يأتي اسمه المتاح من محتواه؟

","options":[{"text":"<button>Search</button>","why":"صحيح. الأزرار والروابط والعناوين والتبويبات وأدوار قليلة أخرى تأخذ اسمها من محتواها، بما في ذلك نص alt للصور التي بداخلها."},{"text":"<input type="text"> وبجانبه كلمة Search مكتوبة في span","why":"حقول النص لا تأخذ اسمها أبدًا من النص المجاور. إنها تحتاج إلى label أو aria-labelledby أو aria-label."},{"text":"<div aria-label="Search area">…</div>","why":"للـ div العادي دور عامّ (generic)، وARIA تمنع تسمية العناصر العامة. وقارئات الشاشة تتجاهل هذه التسمية عادةً."},{"text":"<nav> يحتوي رابط بحث","why":"الـ landmarks لا تأخذ اسمها من محتواها؛ وإلا لقُرئت القائمة كلها كاسم. سمِّ الـ nav بـ aria-label أو aria-labelledby."}],"answer":0}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"
\n

Early-bird prices end Friday.

\n \n
\n\n
\n Ticketly\n \n
\n\n
\n
\n

Friday pass

\n \n
\n
\n

Saturday pass

\n \n
\n
\n

Weekend pass

\n \n
\n
\n\n","css":".banner { display: flex; justify-content: space-between; align-items: center; background: #fff4d6; padding: 4px 12px; border-radius: 8px; }\n.banner p { margin: 0; }\n.bar { display: flex; justify-content: space-between; align-items: center; margin-block: 12px; }\n.cards { display: grid; gap: 8px; }\n.card { border: 1px solid #c9c4dc; border-radius: 12px; padding: 8px 12px; }\n.card h3 { margin: 0 0 6px; font-size: 1rem; }\nbutton { font: inherit; min-block-size: 32px; min-inline-size: 32px; border-radius: 8px; border: 1px solid #5b3cc4; background: #fff; color: #5b3cc4; }\nfooter { margin-block-start: 12px; display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }\n.visually-hidden { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }\n","js":""},"solution":{"html":"
\n

Early-bird prices end Friday.

\n \n
\n\n
\n Ticketly\n \n
\n\n
\n
\n

Friday pass

\n \n
\n
\n

Saturday pass

\n \n
\n
\n

Weekend pass

\n \n
\n
\n\n","css":".banner { display: flex; justify-content: space-between; align-items: center; background: #fff4d6; padding: 4px 12px; border-radius: 8px; }\n.banner p { margin: 0; }\n.bar { display: flex; justify-content: space-between; align-items: center; margin-block: 12px; }\n.cards { display: grid; gap: 8px; }\n.card { border: 1px solid #c9c4dc; border-radius: 12px; padding: 8px 12px; }\n.card h3 { margin: 0 0 6px; font-size: 1rem; }\nbutton { font: inherit; min-block-size: 32px; min-inline-size: 32px; border-radius: 8px; border: 1px solid #5b3cc4; background: #fff; color: #5b3cc4; }\nfooter { margin-block-start: 12px; display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }\n.visually-hidden { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }\n","js":""},"checks":[{"id":"close-named","test":"const textOf = (node) => { let out = ''; for (const n of node.childNodes) { if (n.nodeType === 3) out += n.textContent; else if (n.nodeType === 1) { if (n.getAttribute('aria-hidden') === 'true') continue; const cs = getComputedStyle(n); if (cs.display === 'none' || cs.visibility === 'hidden') continue; const tag = n.tagName.toLowerCase(); if (tag === 'img') out += ' ' + (n.getAttribute('alt') || '') + ' '; else if (tag === 'svg') { const t = n.querySelector('title'); out += ' ' + (n.getAttribute('aria-label') || (t ? t.textContent : '')) + ' '; } else out += ' ' + (n.getAttribute('aria-label') || textOf(n)) + ' '; } } return out.replace(/\\s+/g, ' ').trim(); }; const nameOf = (el) => { const lb = (el.getAttribute('aria-labelledby') || '').trim(); if (lb) { const t = lb.split(/\\s+/).map((id) => { const r = document.getElementById(id); return r ? (r.getAttribute('aria-label') || textOf(r)) : ''; }).join(' ').replace(/\\s+/g, ' ').trim(); if (t) return t; } const al = (el.getAttribute('aria-label') || '').trim(); if (al) return al; const c = textOf(el); return c || (el.getAttribute('title') || '').trim(); }; const b = $('.close'); return !!b && /close|dismiss/i.test(nameOf(b)) && !/×/.test(nameOf(b));"},{"id":"search-named","test":"const textOf = (node) => { let out = ''; for (const n of node.childNodes) { if (n.nodeType === 3) out += n.textContent; else if (n.nodeType === 1) { if (n.getAttribute('aria-hidden') === 'true') continue; const cs = getComputedStyle(n); if (cs.display === 'none' || cs.visibility === 'hidden') continue; const tag = n.tagName.toLowerCase(); if (tag === 'img') out += ' ' + (n.getAttribute('alt') || '') + ' '; else if (tag === 'svg') { const t = n.querySelector('title'); out += ' ' + (n.getAttribute('aria-label') || (t ? t.textContent : '')) + ' '; } else out += ' ' + (n.getAttribute('aria-label') || textOf(n)) + ' '; } } return out.replace(/\\s+/g, ' ').trim(); }; const nameOf = (el) => { const lb = (el.getAttribute('aria-labelledby') || '').trim(); if (lb) { const t = lb.split(/\\s+/).map((id) => { const r = document.getElementById(id); return r ? (r.getAttribute('aria-label') || textOf(r)) : ''; }).join(' ').replace(/\\s+/g, ' ').trim(); if (t) return t; } const al = (el.getAttribute('aria-label') || '').trim(); if (al) return al; const c = textOf(el); return c || (el.getAttribute('title') || '').trim(); }; const b = $('.search'); return !!b && /search/i.test(nameOf(b));"},{"id":"book-unique","test":"const textOf = (node) => { let out = ''; for (const n of node.childNodes) { if (n.nodeType === 3) out += n.textContent; else if (n.nodeType === 1) { if (n.getAttribute('aria-hidden') === 'true') continue; const cs = getComputedStyle(n); if (cs.display === 'none' || cs.visibility === 'hidden') continue; const tag = n.tagName.toLowerCase(); if (tag === 'img') out += ' ' + (n.getAttribute('alt') || '') + ' '; else if (tag === 'svg') { const t = n.querySelector('title'); out += ' ' + (n.getAttribute('aria-label') || (t ? t.textContent : '')) + ' '; } else out += ' ' + (n.getAttribute('aria-label') || textOf(n)) + ' '; } } return out.replace(/\\s+/g, ' ').trim(); }; const nameOf = (el) => { const lb = (el.getAttribute('aria-labelledby') || '').trim(); if (lb) { const t = lb.split(/\\s+/).map((id) => { const r = document.getElementById(id); return r ? (r.getAttribute('aria-label') || textOf(r)) : ''; }).join(' ').replace(/\\s+/g, ' ').trim(); if (t) return t; } const al = (el.getAttribute('aria-label') || '').trim(); if (al) return al; const c = textOf(el); return c || (el.getAttribute('title') || '').trim(); }; const bs = $$('.book'); if (bs.length !== 3) return false; const names = bs.map(nameOf); const passes = ['Friday', 'Saturday', 'Weekend']; return new Set(names).size === 3 && bs.every((b, i) => names[i].includes(passes[i]));"},{"id":"label-in-name","test":"const textOf = (node) => { let out = ''; for (const n of node.childNodes) { if (n.nodeType === 3) out += n.textContent; else if (n.nodeType === 1) { if (n.getAttribute('aria-hidden') === 'true') continue; const cs = getComputedStyle(n); if (cs.display === 'none' || cs.visibility === 'hidden') continue; const tag = n.tagName.toLowerCase(); if (tag === 'img') out += ' ' + (n.getAttribute('alt') || '') + ' '; else if (tag === 'svg') { const t = n.querySelector('title'); out += ' ' + (n.getAttribute('aria-label') || (t ? t.textContent : '')) + ' '; } else out += ' ' + (n.getAttribute('aria-label') || textOf(n)) + ' '; } } return out.replace(/\\s+/g, ' ').trim(); }; const nameOf = (el) => { const lb = (el.getAttribute('aria-labelledby') || '').trim(); if (lb) { const t = lb.split(/\\s+/).map((id) => { const r = document.getElementById(id); return r ? (r.getAttribute('aria-label') || textOf(r)) : ''; }).join(' ').replace(/\\s+/g, ' ').trim(); if (t) return t; } const al = (el.getAttribute('aria-label') || '').trim(); if (al) return al; const c = textOf(el); return c || (el.getAttribute('title') || '').trim(); }; const bs = [...$$('.book'), $('.subscribe')]; return bs.every((b) => { const visible = b.innerText.replace(/\\s+/g, ' ').trim().toLowerCase(); const name = nameOf(b).toLowerCase(); return name.includes(visible); }) && $$('.book').every((b) => /^book now/i.test(nameOf(b)));"},{"id":"subscribe","test":"const textOf = (node) => { let out = ''; for (const n of node.childNodes) { if (n.nodeType === 3) out += n.textContent; else if (n.nodeType === 1) { if (n.getAttribute('aria-hidden') === 'true') continue; const cs = getComputedStyle(n); if (cs.display === 'none' || cs.visibility === 'hidden') continue; const tag = n.tagName.toLowerCase(); if (tag === 'img') out += ' ' + (n.getAttribute('alt') || '') + ' '; else if (tag === 'svg') { const t = n.querySelector('title'); out += ' ' + (n.getAttribute('aria-label') || (t ? t.textContent : '')) + ' '; } else out += ' ' + (n.getAttribute('aria-label') || textOf(n)) + ' '; } } return out.replace(/\\s+/g, ' ').trim(); }; const nameOf = (el) => { const lb = (el.getAttribute('aria-labelledby') || '').trim(); if (lb) { const t = lb.split(/\\s+/).map((id) => { const r = document.getElementById(id); return r ? (r.getAttribute('aria-label') || textOf(r)) : ''; }).join(' ').replace(/\\s+/g, ' ').trim(); if (t) return t; } const al = (el.getAttribute('aria-label') || '').trim(); if (al) return al; const c = textOf(el); return c || (el.getAttribute('title') || '').trim(); }; const b = $('.subscribe'); return !!b && /subscribe/i.test(nameOf(b)) && !/cta/i.test(nameOf(b));"}],"title":"سمِّ كل زر في صفحة الفعالية","prompt":"

يعرض قارئ الشاشة أزرار Ticketly هكذا: “times, button, Book now, Book now, Book now, newsletter-cta”. أصلح الأسماء دون تغيير ما يراه المبصرون:

\n
    \n
  1. زر الإغلاق .close ‏"×" يحتاج إلى اسم يحتوي “Close” (أو “Dismiss”)؛ ولا ينبغي أن يُقرأ الرمز “×” نفسه.
    2. \n
  2. زر البحث .search الذي لا يحتوي إلا أيقونة يحتاج إلى الاسم “Search”.
    3. \n
  3. كل زر .book يحتاج إلى اسم فريد يبدأ بـ “Book now” ويتضمّن تذكرته (Friday أو Saturday أو Weekend).
    4. \n
  4. اسم زر .subscribe يجب أن يحتوي كلمته المرئية “Subscribe”.
    5. \n
\n","hints":["أخفِ الرمز × بـ ، ثم أضِف نصًا مخفيًا بصريًا أو aria-label على الزر.","أعطِ كل عنوان وكل زر Book now ‏id، ثم ضع aria-labelledby=“button-id heading-id” على الزر.","لزر Subscribe، أبسط إصلاح هو حذف الـ aria-label ليصبح محتوى الزر اسمه."],"explanation":"

صار اسم زر الإغلاق يأتي من نص مخفي بصريًا (أو من aria-label)، والرمز × مخفي فلا يُقرأ “times”. ويحصل زر البحث على اسمه من aria-label لأنه بلا محتوى نصي، وأيقونة الـ SVG الزخرفية فيه مخفية. ويستخدم كل زر Book now خاصية aria-labelledby ليشير إلى نفسه وإلى عنوان بطاقته، فينتج “Book now Friday pass”: اسم فريد في قائمة الأزرار، وما زال يبدأ بالكلمات المرئية، فيستطيع مستخدمو التحكّم الصوتي قول “click Book now” (2.5.3 Label in Name). وكان زر Subscribe الأسهل: حذف aria-label خاطئة سمح للنص المرئي بأن يعود ليكون الاسم.

\n","checkLabels":{"close-named":"زر الإغلاق اسمه Close (أو Dismiss) والرمز × لا يُقرأ","search-named":"زر البحث اسمه Search","book-unique":"لأزرار Book now الثلاثة أسماء فريدة تتضمّن تذكرة كلٍّ منها","label-in-name":"كل اسم يحتوي نصه المرئي، وأسماء Book now تبدأ به","subscribe":"اسم زر Subscribe يحتوي “Subscribe”"}},"words":615,"readMinutes":4}