التفاصيل والملخص

اكتشِف طريقة عمل التفاصيل المفيدة للغاية وعناصر الملخّص وأماكن استخدامها.

أداة الإفصاح هي عنصر تحكّم في واجهة المستخدم يخفي المحتوى ويعرضه. إذا كنت تقرأ هذا على web.dev، وكان إطار العرض أقل من 106 ميل، يؤدي النقر على "في هذه الصفحة" أعلى هذه الفقرة إلى إظهار جدول المحتويات لهذا القسم. وإذا لم يظهر لك هذا الخيار، يمكنك تصغير المتصفّح لعرض جدول المحتويات أثناء التنقّل في هذه الصفحة على أنّه تطبيق مصغّر للإفصاح.

واجهة المستخدم الرسومية accordion هي سلسلة من أدوات الإفصاح عموديًا. من حالات الاستخدام الشائعة لواجهة مستخدم accordion هي صفحة الأسئلة الشائعة (FAQ) على العديد من المواقع. تحتوي الأسئلة الشائعة حول أكورديون على قائمة بالأسئلة المرئية؛ يؤدي النقر على السؤال إلى توسيع، أو "يكشف"، الإجابة عن هذا السؤال.

يتضمّن jQuery نمط واجهة مستخدم أكورديون منذ عام 2009 على الأقل. تضمّن حل أكورديون الأصلي الخالي من JavaScript ضبط كل سؤال من أسئلة الأسئلة الشائعة على <label> متبوعًا بعلامة الاختيار بجانبه، ثم عرض الإجابة <div> عند وضع علامة على علامة الاختيار. بدت خدمة مقارنة الأسعار (CSS) على النحو التالي:

#FAQ [type="checkbox"] + div.answer {
  /* all the answer styles */
  display: none;
}
#FAQ [type="checkbox"]:checked + div.answer {
  display: block;
}

ما السبب في هذا التاريخ؟ تُعدّ أدوات الإفصاح، مثل أكورديون، التي لا تحتوي على JavaScript أو عناصر تحكّم في النماذج إضافة حديثة نسبيًا، حيث لم تتم إتاحة العنصرَين <details> و<summary> بشكل كامل إلا في جميع المتصفّحات الحديثة منذ كانون الثاني (يناير) 2020. يمكنك الآن إنشاء تطبيقات مصغّرة فعّالة، وإن كانت أقل من الجاذبية، يمكنك استخدامها باستخدام ترميز HTML الدلالي فقط. يمكنك استخدام العنصرَين <details> و<summary> لتوفير كل ما تحتاج إليه، إذ إنّهما يوفّران طريقة مدمَجة للتعامل مع توسيع المحتوى وتصغيره. عندما ينقر المستخدم على <summary> أو عندما يضغط على مفتاح Enter عند التركيز على <summary>، يتم تبديل محتوى عنصر <details> الرئيسي.

ومثل كل المحتوى الدلالي، يمكنك التحسين تدريجيًا للمظهر والميزات التلقائية. في هذه الحالة، تمت إضافة جزء صغير من CSS، ولكن لا شيء آخر:

وستلاحظ أن برامج Codepens هذه لا تحتوي على JavaScript.

تبديل مستوى العرض: سمة open

العنصر <details> هو حاوية أداة الإفصاح. السمة <summary> هي الملخّص أو وسيلة الإيضاح للعنصر الرئيسي <details>. يتم عرض الملخص دائمًا، ليكون بمثابة زر يبدّل عرض بقية المحتوى التابع للوالدَين. يؤدي التفاعل مع <summary> إلى تبديل عرض ملخص المصنَّف ذاتيًا عن طريق تبديل سمة open للعنصر <details>.

السمة open هي سمة منطقية. في حال توفّرها، بغض النظر عن قيمتها أو نقصها، فإنها تشير إلى عرض جميع محتويات <details> للمستخدم. في حال عدم توفّر السمة open، سيتم عرض محتوى <summary> فقط.

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

يمكنك إنشاء قائمة أكورديون تحتوي على قائمة تتضمّن عناصر <details> متعدّدة، ويتضمّن كل منها عنصر <summary> فرعي. في حال عدم تضمين السمة open في HTML، سيتم تصغير جميع العناصر في <details> أو إغلاقها، مع ظهور عناوين الملخّصات فقط عند تحميل الصفحة، ويكون كل عنوان افتتاحًا لبقية المحتوى في عنصر <details> الرئيسي. إذا ضمّنت السمة open في ترميز HTML، سيتم عرض السمة <details> بشكل موسّع مع عرض المحتوى عند تحميل الصفحة.

يمكن البحث عن المحتوى المخفي في الحالة المصغّرة في بعض المتصفّحات بدون غيرها، على الرغم من أنّ المحتوى الذي تم تصغيره ليس جزءًا من DOM. إذا كنت تبحث في Edge أو Chrome، سيتم توسيع التفاصيل التي تحتوي على عبارة بحث لعرض موضع الورود. لا يتم تكرار هذا السلوك في Firefox أو Safari.

يجب أن يكون <summary> هو العنصر الثانوي الأول للعنصر <details>، ويمثل ملخصًا أو شرحًا أو وسيلة إيضاح لبقية محتوى العنصر <details> الرئيسي المُدمج فيه. يمكن أن يكون محتوى العنصر <summary> أي محتوى عنوان أو نصًا عاديًا أو HTML يمكن استخدامه داخل فقرة.

تبديل علامة الملخّص

في اثنين من رموز Codepens السابقة، ستلاحظ السهم في جانب inline-start في الملخّص. يتم عادةً عرض أداة الإفصاح على الشاشة باستخدام مثلث صغير يدور (أو يلتف) للإشارة إلى الحالة "مفتوح/مغلق"، مع وضع علامة بجانب المثلث. يصنّف محتوى العنصر <summary> أداة الإفصاح. السهم الدوّار في أعلى كل قسم هو عبارة عن ::marker تم ضبطه على عنصر <summary>. على غرار عناصر القائمة، يتيح العنصر <summary> استخدام السمة المختصرة list-style وخصائصها الطويلة، بما في ذلك list-style-type. يمكنك تصميم مثلث الإفصاح باستخدام CSS، بما في ذلك تغيير العلامة المستخدمة من مثلث إلى أي نوع تعداد نقطي آخر، بما في ذلك صورة تحتوي على list-style-image.

لتطبيق أنماط أخرى، استخدِم أداة اختيار مشابهة للسمة details summary::marker. ولا يقبل ::marker العنصر الزائف إلا عددًا محدودًا من الأنماط. ومن الشائع إزالة ::marker واستبداله بالسمة ::before الأسهل في التصميم، حيث تغيّر أنماط CSS نمط المحتوى الذي يتم إنشاؤه قليلاً استنادًا إلى توفُّر (أو عدم) السمة open. يمكنك إزالة رمز أداة الإفصاح من خلال ضبط list-style: none أو ضبط محتوى العلامة على none، مع تضمين دائمًا مؤشرات مرئية لإعلام المستخدمين المبصرين بأنّ محتوى الملخّص هو زر تبديل يتيح إظهار المحتوى وإخفاؤه عند التفعيل.

details summary::before {
  /* all the styles */
}
details[open] summary::before {
  /* changes applied when open only */
}

يؤدي هذا المثال إلى إزالة العلامة التلقائية وإضافة المحتوى الذي تم إنشاؤه لإنشاء + عند إغلاق التفاصيل و- عندما تكون التفاصيل مفتوحة.

إذا كنت تريد فتح مجموعة التفاصيل تلقائيًا، ضمِّن السمة open في علامة <details> الافتتاحية. يمكنك أيضًا إضافة مسافة بين كل مربع حوار ونقل تدوير العلامة التي تم إنشاؤها بالمحتوى الذي تم إنشاؤه لتحسين المظهر:

كيفية معالجة الأخطاء

إذا لم تضمِّن <summary>، سينشئ المتصفّح خريطة لك باستخدام علامة وكلمة "تفاصيل". يمثّل هذا الملخّص جزءًا من جذر الظل، وبالتالي لن يتم تطبيق أنماط ملخّصات CSS للمؤلفين. للأسف، لا يتضمن Safari التفاصيل في ترتيب تركيز لوحة المفاتيح.

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

واجهة HTMLDetailsElement

مثل جميع عناصر HTML، تكتسِب HTMLDetailsElement جميع الخصائص والطرق والأحداث من HTMLElement، كما تُضيف خاصية النسخة الافتراضية open وحدث toggle. السمة HTMLDetailsElement.open هي قيمة منطقية تُظهر سمة HTML open، وتوضح ما إذا كان سيتم عرض محتوى العنصر (ولا يتم احتساب <summary>) للمستخدم أم لا. يتم تنشيط حدث الإيقاف/التفعيل عند تبديل عنصر <details> إلى الوضع "فتح" أو "مغلق". يمكنك الاستماع إلى هذا الحدث باستخدام addEventListener().

إذا كنت تريد كتابة نص برمجي لإغلاق التفاصيل المفتوحة عندما يفتح المستخدم أي تفاصيل أخرى، أزِل السمة open باستخدام removeAttribute("open"):

هذا هو المثال الوحيد لاستخدام JavaScript. لست بحاجة إلى JavaScript على الأرجح باستثناء هذه الوظيفة التي تتمثل في إغلاق أدوات الإفصاح الأخرى المفتوحة.

يمكن ارتداء "<details>" و"<summary>" بتصميم غني ويمكن استخدامهما لإنشاء نصائح حول الأدوات. ومع ذلك، إذا كنت ستستخدم هذه العناصر الدلالية لحالات الاستخدام التي تكون فيها الدلالات الأصلية غير متطابقة، تأكَّد دائمًا من الحفاظ على تسهيل الاستخدام. يمكن الوصول تلقائيًا إلى رموز HTML في معظم الأحيان. ومهمتنا كمطوّرين هي ضمان إمكانية الوصول إلى المحتوى الخاص بنا.

التحقق من فهمك

اختبر معلوماتك بالتفاصيل والملخص.

يجب أن يكون <summary> العنصر الثانوي الأول لأي عنصر؟

<p>

يُرجى إعادة المحاولة.

<details>

إجابة صحيحة

<fieldset>

يُرجى إعادة المحاولة.