Tạo hướng dẫn sử dụng ứng dụng cố định

Tính năng web: Cửa sổ bật lên Định vị neo

Hướng dẫn làm quen với ứng dụng yêu cầu lớp phủ duy trì trong khi người dùng tương tác với các tính năng được làm nổi bật. Không giống như cửa sổ bật lên tự động, cửa sổ bật lên thủ công không đóng khi người dùng nhấp vào vị trí khác trên trang. Việc kết hợp popover="manual" với tính năng Định vị neo CSS cho phép bạn tạo các bước hướng dẫn không theo phương thức và được liên kết.

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

Nguyên tắc triển khai

  • BẮT BUỘC: Sử dụng popover="manual" để ngăn bước hướng dẫn vô tình đóng trong quá trình người dùng tương tác.
  • BẮT BUỘC: Đánh dấu vùng chứa bằng role="dialog" và liên kết tiêu đề của vùng chứa đó thông qua aria-labelledby.
  • BẮT BUỘC: Chuyển tiêu điểm có lập trình vào bên trong cửa sổ bật lên ngay sau khi mở để tránh mất tiêu điểm.
  • NÊN sử dụng CSS Anchor Positioning để liên kết bước hướng dẫn với tính năng cụ thể đang được giải thích.
  • NÊN cung cấp nút "Đóng" hoặc "Tiếp theo" rõ ràng trong cửa sổ bật lên sử dụng popovertargetaction="hide".

Chiến lược dự phòng

Phương án dự phòng và hỗ trợ trình duyệt cho Popover

Popover API chủ yếu là cải tiến tăng dần, nhưng các hành vi xác định của API này (quảng bá lớp trên cùng, đóng nhẹ và gọi popovertarget) không có hành vi tương đương chỉ dùng CSS. Các trình duyệt cũ cần có polyfill hoặc phương án dự phòng thủ công nếu bạn không muốn cung cấp polyfill.

Polyfill: Để hỗ trợ thuộc tính popover trong các trình duyệt cũ, hãy tải @oddbird/popover-polyfill theo điều kiện. BẮT BUỘC: Phát hiện tính năng bằng cách kiểm tra thuộc tính popover trên HTMLElement.prototype và chỉ tải polyfill khi thiếu tính năng hỗ trợ gốc — KHÔNG tải polyfill vô điều kiện.

Với trình đóng gói hoặc bản đồ nhập:

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

Nếu không có trình đóng gói, hãy nhập từ CDN bên trong <script type="module">:

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

Lưu ý về kiểu: Polyfill không thể xác định lớp giả :popover-open thực, vì vậy, lớp này sẽ áp dụng lớp .\:popover-open. BẮT BUỘC: Kết hợp cả hai bằng :is() hoặc :where(), nếu không, các trình duyệt thiếu :popover-open sẽ loại bỏ toàn bộ quy tắc:

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

Ngoài ra, đối với phương án dự phòng cũ không có polyfill, hãy sử dụng position: fixed và tính toán toạ độ theo cách thủ công thông qua getBoundingClientRect() hoặc dựa vào vị trí mặc định bằng inset: auto nếu điều đó phù hợp với trường hợp sử dụng.

anchor-positioning

Để hỗ trợ các trình duyệt không có tính năng định vị neo, bạn có thể chọn sử dụng polyfill hoặc phương án dự phòng CSS thuần tuý.

Cách 1: Dự phòng Polyfill

Bạn có thể dùng polyfill @oddbird/css-anchor-positioning để mô phỏng vị trí neo. Hệ thống không hỗ trợ neo ngầm định, vì vậy, bạn PHẢI thêm tên neo rõ ràng vào điều kiện kích hoạt. Ngoài ra, polyfill không hỗ trợ position-area trên cửa sổ bật lên, vì vậy, bạn PHẢI sử dụng anchor() trên các phần lồng ghép mong muốn thay vì 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);
}
Cách 2: Dự phòng CSS không Polyfill

Nếu không muốn sử dụng polyfill, bạn có thể đặt chú thích mặc định ở một vị trí cố định ở cuối khung nhìn bằng @supports not.

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