إنشاء جولات مستمرة في التطبيق

تتطلّب جولات الإعداد تراكبات تظل ظاهرة أثناء تفاعل المستخدمين مع الميزات المميّزة. على عكس النوافذ المنبثقة التلقائية، لا يتم إغلاق النوافذ المنبثقة اليدوية عندما ينقر المستخدم في مكان آخر على الصفحة. يتيح لك الجمع بين popover="manual" وCSS Anchor Positioning إنشاء خطوات جولة مرتبطة وغير مشروطة.

عمليات التنفيذ المقترَحة

HTML

<div id="feature-target">Highlight this feature</div>

<!-- MANDATORY: Enforce overlay dialog semantics and accessible name bindings -->
<div id="tour-step" popover="manual" role="dialog" aria-labelledby="tour-title">
  <!-- Assume an <h1> precedes this element in the full document outline -->
  <h2 id="tour-title">Step 1</h2>
  <p>Learn how to use this feature.</p>
  <button popovertarget="tour-step" popovertargetaction="hide">Got it</button>
</div>

CSS

#feature-target {
  anchor-name: --feature-target;
}

#tour-step {
  popover: manual;
  position-anchor: --feature-target;
  position-area: right center;
  inset: auto;
  margin: 1rem;
  padding: 1rem;
  border: 1px solid blue;
  border-radius: 0.5rem;
  background: aliceblue;
}

JavaScript

const tourStep = document.getElementById('tour-step');
tourStep.showPopover();
// MANDATORY: Programmatically route focus into the non-modal popover so keyboard/assistive technology users immediately perceive the new context
tourStep.querySelector('button').focus();

إرشادات التنفيذ

• MANDATORY: Use popover="manual" to prevent the tour step from closing accidentally during user interaction.
• مطلوب: ضَع علامة على الحاوية باستخدام role="dialog" واربط عنوانها من خلال aria-labelledby.
• إجراء إلزامي: يجب نقل التركيز البرمجي إلى داخل النافذة المنبثقة فور فتحها لمنع فقدان التركيز.
• يجب استخدام CSS Anchor Positioning لربط خطوة الجولة بالميزة المحدّدة التي يتم شرحها.
• يجب توفير زر "إغلاق" أو "التالي" صريح ضمن النافذة المنبثقة التي تستخدم popovertargetaction="hide".

استراتيجيات احتياطية

الخيارات الاحتياطية وتوافق المتصفّحات مع Popover

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

Polyfill: لإتاحة السمة popover في المتصفّحات القديمة، يمكنك تحميل @oddbird/popover-polyfill بشكل مشروط. إجراء إلزامي: يجب رصد الميزة من خلال التحقّق من السمة popover في HTMLElement.prototype، وتحميل polyfill فقط في حال عدم توفّر الدعم الأصلي، ويجب عدم تحميله بدون شروط.

باستخدام حزمة أو خريطة استيراد:

// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
if (!("popover" in HTMLElement.prototype)) {
  import("@oddbird/popover-polyfill");
}

بدون حزمة، يمكنك الاستيراد من شبكة توصيل محتوى (CDN) داخل <script type="module">:

<script type="module">
  if (!("popover" in HTMLElement.prototype)) {
    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
  }
</script>

تحذير بشأن التنسيق: لا يمكن لـ polyfill تحديد الفئة الزائفة :popover-open الحقيقية، لذا يتم تطبيق فئة .\:popover-open بدلاً من ذلك. إجراء إلزامي: ادمج السمتَين مع :is() أو :where()، وإلا ستتجاهل المتصفحات التي لا تتضمّن :popover-open القاعدة بأكملها:

[popover]:is(:popover-open, .\:popover-open) {
  display: block;
}

بدلاً من ذلك، يمكنك استخدام position: fixed واحتساب الإحداثيات يدويًا من خلال getBoundingClientRect() أو الاعتماد على تحديد الموضع التلقائي باستخدام inset: auto إذا كان ذلك مقبولاً لحالة الاستخدام، وذلك كحل بديل قديم بدون polyfill.

anchor-positioning

لإتاحة المتصفّحات التي لا تتضمّن ميزة تحديد موضع الارتساء، يمكنك الاختيار بين استخدام polyfill أو عنصر احتياطي في CSS فقط.

الخيار 1: استخدام polyfill كحلّ احتياطي

يمكن استخدام polyfill @oddbird/css-anchor-positioning لمحاكاة تحديد موضع الارتساء. لا تتيح هذه الميزة استخدام علامات الارتساء الضمنية، لذا يجب إضافة أسماء علامات ارتساء صريحة إلى عامل التفعيل. بالإضافة إلى ذلك، لا يتيح polyfill استخدام السمة position-area في النوافذ المنبثقة، لذا يجب استخدام السمة anchor() في العناصر المضمّنة المطلوبة بدلاً من position-area.

<script type="module">
  if (!CSS.supports('anchor-name: --foo')) {
    await import("https://unpkg.com/@oddbird/css-anchor-positioning");
  }
</script>

#tour-step {
  /* If using the anchor positioning polyfill with a popover, DO use `anchor()` functions instead of `position-area`. */
  left: anchor(right);
  top: anchor(top);
}

الخيار 2: استخدام CSS احتياطي غير متوافق مع Polyfill

إذا كنت تفضّل عدم استخدام polyfill، يمكنك ضبط تلميح الشاشة تلقائيًا على موضع ثابت في أسفل إطار العرض باستخدام @supports not.

@supports not (anchor-name: --foo) {
  #tour-step {
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    width: 100%;
    margin: 0;
    border-radius: 0;
  }
}