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

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

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

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

يتضمّن 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، ولكن لا شيء آخر:

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

تبديل إذن الوصول: السمة open

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

السمة 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 الذي يمكن استخدامه داخل فقرة.

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

في الخيارين السابقين من رموز الترميز، ستلاحظ السهم إلى حرف البداية المضمَّنة (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> العنصر الثانوي الأول لأي عنصر؟

<fieldset>
<p>
<details>