Membuat Tur Aplikasi Persisten

Fitur web: Popover Pemosisian anchor

Tur orientasi memerlukan overlay yang tetap ada saat pengguna berinteraksi dengan fitur yang ditandai. Tidak seperti popover otomatis, popover manual tidak akan ditutup saat pengguna mengklik di tempat lain di halaman. Dengan menggabungkan popover="manual" dengan CSS Anchor Positioning, Anda dapat membuat langkah tur yang ditambatkan dan non-modal.

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();

Panduan Penerapan

  • WAJIB: Gunakan popover="manual" untuk mencegah langkah tur tertutup secara tidak sengaja selama interaksi pengguna.
  • WAJIB: Tandai penampung dengan role="dialog" dan tautkan judulnya melalui aria-labelledby.
  • WAJIB: Alihkan fokus terprogram ke dalam popover segera setelah dibuka untuk mencegah pengabaian fokus.
  • LAKUKAN penggunaan CSS Anchor Positioning untuk menambatkan langkah tur ke fitur tertentu yang sedang dijelaskan.
  • BERIKAN tombol "Tutup" atau "Berikutnya" yang jelas dalam popover yang menggunakan popovertargetaction="hide".

Strategi penggantian

Penggantian & dukungan browser untuk Popover

Popover API sebagian besar merupakan progressive enhancement, tetapi perilaku penentuannya — promosi lapisan atas, penutupan ringan, dan pemanggilan popovertarget — tidak memiliki padanan khusus CSS. Browser lama memerlukan polyfill, atau penggantian manual jika Anda tidak ingin mengirimkannya.

Polyfill: Untuk mendukung atribut popover di browser lama, muat @oddbird/popover-polyfill secara bersyarat. WAJIB: Deteksi fitur dengan memeriksa properti popover di HTMLElement.prototype, dan muat polyfill hanya jika dukungan native tidak ada — JANGAN memuatnya tanpa syarat.

Dengan bundler atau peta impor:

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

Tanpa bundler, impor dari CDN di dalam <script type="module">:

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

Peringatan gaya: Polyfill tidak dapat menentukan pseudo-class :popover-open yang sebenarnya, sehingga menerapkan class .\:popover-open. WAJIB: Gabungkan keduanya dengan :is() atau :where(). Jika tidak, browser yang tidak memiliki :popover-open akan menghapus seluruh aturan:

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

Atau, untuk penggantian lama tanpa polyfill, gunakan position: fixed dan hitung koordinat secara manual melalui getBoundingClientRect() atau andalkan pemosisian default dengan inset: auto jika hal itu dapat diterima untuk kasus penggunaan.

anchor-positioning

Untuk mendukung browser tanpa pemosisian anchor, Anda dapat memilih antara menggunakan polyfill atau penggantian CSS murni.

Opsi 1: Penggantian Polyfill

Polyfill @oddbird/css-anchor-positioning dapat digunakan untuk mengemulasi pemosisian anchor. Atribut ini tidak mendukung anchor implisit, jadi Anda HARUS menambahkan nama anchor eksplisit ke pemicu. Selain itu, position-area tidak didukung di popover oleh polyfill, jadi Anda HARUS menggunakan anchor() pada inset yang diinginkan, bukan 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);
}
Opsi 2: Penggantian CSS Non-Polyfill

Jika tidak ingin menggunakan polyfill, Anda dapat menetapkan tooltip ke posisi tetap di bagian bawah area pandang menggunakan @supports not.

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