نمایش نکته‌ابزار هنگام نگه داشتن اشاره‌گر

ویژگی‌های وب: فراخوان‌های Interest Popover popover="hint" موقعیت‌یابی لنگر

کاربران انتظار دارند اطلاعات مرتبط بیشتری را بدون تغییر کامل بافت ببینند. وقتی کاربر به اطلاعات بیشتری نیاز دارد، نمایش نکته‌ابزار می‌تواند برای ارائه تعریف یک اصطلاح، شفاف‌سازی کنشی که دکمه فقط نماد انجام می‌دهد، یا ارائه راهنمایی بیشتر برای فیلد فرم مفید باشد.

درحال ایجاد نکته‌ابزار

با افزودن مشخصه popover="hint" به <div> یا عنصر مناسب معنایی دیگر، می‌توانید یک پاپ‌اور با رفتار موردنیاز ایجاد کنید. وقتی کاربر نکته‌ابزار را باز می‌کند، این کار نکته‌ابزارهای popover="hint" دیگر را پنهان می‌کند، اما نکته‌ابزارهای auto یا manual را پنهان نمی‌کند. It also handles dismissing nested tooltips.

همچنین رفتار رد کردن ساده را ارائه می‌دهد، بنابراین وقتی کاربر کلیک می‌کند یا به‌نحوی دیگر خارج از popover تمرکز می‌کند، popover رد می‌شود.

عنصر نکته‌ابزار باید مشخصه id با مقدار یکتا داشته باشد:

<!-- MANDATORY: The tooltip container `<div>` must have a `popover` attribute.
     the value of `"hint"` ensures it can be "light dismissed". -->
<div popover="hint" id="tooltip">Tooltip content</div>

کاربر با نگه داشتن نشانگر یا تمرکز روی عنصر <a> یا <button>، به اطلاعات تکمیلی ابراز علاقه می‌کند. عنصر باید مشخصه interestfor داشته باشد که با مشخصه id نکته‌ابزار مطابقت داشته باشد.

<!-- The `interestfor` attribute can be applied to a `<button>` element: -->
<button interestfor="tooltip">Tooltip trigger</button>

<!-- The `interestfor` attribute can also be applied to an `<a>` element: -->
<a interestfor="tooltip" href="">Tooltip trigger</a>

راه‌انداز باید نشانگر تصویری داشته باشد تا نشان دهد که با تعامل با راه‌انداز، اطلاعات بیشتری دردسترس است.

دسترس‌پذیری در interestfor تعبیه شده است

وقتی از interestfor استفاده می‌کنید، مرورگر سیم‌کشی فناوری کمکی را برای شما مدیریت می‌کند:

  • معناشناسی ضمنی: هدف با popover="hint" حداقل نقش ضمنی tooltip را به‌دست می‌آورد. role="tooltip" را خودتان تنظیم نکنید.
  • ارتباط ضمنی: وقتی هدف نوشتار ساده باشد، مرورگر به‌طور ضمنی عنصر منبع را ازطریق aria-describedby با هدف مرتبط می‌کند، یا وقتی هدف حاوی محتوای تعاملی باشد، این کار را ازطریق aria-details انجام می‌دهد. aria-describedby یا aria-details را به راه‌انداز اضافه نکنید.
  • محتوای تعاملی: چون درصورت نیاز، ارتباط به aria-details تغییر می‌کند، هدف می‌تواند محتوای تعاملی داشته باشد (مثلاً پیوند درون «کارت علاقه»).

محدودیت‌های دسترس‌پذیری (WCAG 1.4.13)

حتی اگر interestfor معناشناسی بالا را مدیریت کند، پیاده‌سازی شما همچنان باید WCAG 1.4.13 (محتوا در حالت نگه داشتن نشانگر یا فوکوس) را برآورده کند:

  • قابل‌بستن: کاربران باید بتوانند نکته‌ابزار را بدون حرکت دادن نشانگر شناور یا تمرکز صفحه‌کلید ببندند (مثلاً با فشار دادن کلید Escape). ویژگی بومی popover این اتصال را به‌طور خودکار مدیریت می‌کند.
  • نگه‌داشتن نشانگر: نشانگر باید بتواند روی محتوای نکته‌ابزار حرکت کند بدون اینکه نکته‌ابزار ناپدید شود. این کار به کاربران دارای ابزارهای درشت‌نمایی امکان می‌دهد نوشتار نکته‌ابزار را به‌طور ایمن بخوانند.
  • ماندگار: نکته‌ابزار باید تا زمانی‌که ماشه نگه داشتن نشانگر یا تمرکز برداشته شود، کاربر صریحاً آن را ببندد، یا محتوای آن دیگر معتبر نباشد، نمایان بماند.

موقعیت‌یابی نکته‌ابزار

نکته‌ابزار بااستفاده از موقعیت‌یابی لنگر CSS قرار داده شده است. وقتی نکته‌ابزار بااستفاده از interestfor باز می‌شود، عنصر راه‌انداز به‌طور خودکار به لنگر ضمنی برای پاپ‌اور تبدیل می‌شود.

در مرورگرهای نو که از موقعیت‌یابی لنگر بومی پشتیبانی می‌کنند، نیازی به تعریف anchor-name در راه‌انداز یا position-anchor در نکته‌ابزار ندارید. می‌توانید نکته‌ابزار را مستقیماً نسبت به لنگر ضمنی آن بااستفاده از position-area قرار دهید و وارونگی برخورد را با position-try-fallbacks مدیریت کنید:

[popover] {
  /* Implicit anchor from interestfor: no anchor-name or position-anchor needed */
  position-area: top;
  position-try-fallbacks: flip-block;
  margin: unset;
}

راهبردهای جایگزین

پشتیبانی مرورگر و بازگشت به حالت قبل برای فراخوان‌های Interest

فراخوان‌های Interest باید به‌صورت مشروط بااستفاده از بسته شبیه‌ساز مرورگر interestfor از NPM شبیه‌سازی شوند. ترجیحاً شبیه‌ساز مرورگر را به‌جای استفاده از CDN بسته‌بندی کنید.

اجباری: ویژگی را با بررسی کردن ویژگی interestForElement در HTMLButtonElement.prototype شناسایی کنید و شبیه‌ساز مرورگر را فقط زمانی بار کنید که پشتیبانی بومی وجود ندارد.

<script type="module">
  if (!HTMLButtonElement.prototype.hasOwnProperty("interestForElement")) {
    // CDN link only used for example, prefer bundling.
    await import("https://unpkg.com/interestfor@latest");
  }
</script>

هشدارهای شبیه‌ساز مرورگر CSS

هنگام استفاده از شبیه‌ساز مرورگر، CSS API کمی تغییر می‌کند تا عدم پشتیبانی از کلاس کاذب و ویژگی بومی را جبران کند:

  • شبه‌کلاس‌ها: شبیه‌ساز مرورگر نمی‌تواند شبه‌کلاس‌های واقعی :interest-source و :interest-target را تعریف کند، بنابراین به‌جای آن‌ها کلاس‌های .interest-source و .interest-target را اعمال می‌کند. اجباری: آن‌ها را با :is() ترکیب کنید تا از هر دو حالت بومی و شبیه‌سازی‌شده پشتیبانی شود.
/* Styles to apply when the effect is being previewed */
:is(:interest-source, .interest-source) { /* ... */ }
:is(:interest-target, .interest-target) { /* ... */ }
  • ویژگی‌های CSS: برای interest-delay، interest-delay-start، و interest-delay-end، شبیه‌ساز مرورگر به استفاده از متغیرهای CSS نیاز دارد زیرا نمی‌تواند ویژگی‌های سفارشی را مستقیماً در همه مرورگرها بخواند.
/* Adjust the start and end delay for interest invokers */
[interestfor] {
  --interest-delay-start: 0.2s;
  interest-delay-start: var(--interest-delay-start);
  --interest-delay-end: 0.1s;
  interest-delay-end: var(--interest-delay-end);
}

پشتیبانی مرورگر و بازگشت به حالت قبلی برای Popover

«میانای برنامه‌سازی کاربردی Popover» عمدتاً ارتقای پیش‌رو است، اما رفتارهای تعریف‌کننده آن (ارتقای لایه بالایی، رد کردن با کلیک در خارج از عنصر، و فراخوانی popovertarget) معادل CSS-only ندارند. مرورگرهای قدیمی‌تر به شبیه‌ساز مرورگر نیاز دارند، یا اگر ترجیح می‌دهید شبیه‌ساز مرورگر ارسال نکنید، به بازگشت دستی نیاز دارند.

شبیه‌ساز مرورگر: برای پشتیبانی از مشخصه popover در مرورگرهای قدیمی‌تر، @oddbird/popover-polyfill را به‌صورت شرطی بار کنید. اجباری: ویژگی را با بررسی کردن ویژگی popover در HTMLElement.prototype شناسایی کنید و شبیه‌ساز مرورگر را فقط زمانی بار کنید که پشتیبانی بومی وجود ندارد — آن را بدون قیدوشرط بار نکنید.

با بسته‌بندی یا نقشه واردات:

// 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>

هشدار سبک‌بندی: شبیه‌ساز مرورگر نمی‌تواند کلاس کاذب واقعی :popover-open را تعریف کند، بنابراین به‌جای آن کلاس .\:popover-open را اعمال می‌کند. اجباری: این دو را با :is() یا :where() ترکیب کنید، درغیراین‌صورت مرورگرهایی که فاقد :popover-open هستند کل قانون را نادیده می‌گیرند:

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

یا برای بازگشت به نسخه قدیمی بدون شبیه‌ساز مرورگر، از position: fixed استفاده کنید و مختصات را به‌صورت دستی ازطریق getBoundingClientRect() محاسبه کنید یا اگر برای مورد استفاده قابل‌قبول است، به موقعیت‌یابی پیش‌فرض با inset: auto تکیه کنید.

‫popover-polyfill رفتار اشاره را در مرورگرهایی که از popover پشتیبانی می‌کنند اما از popover="hint" پشتیبانی نمی‌کنند شبیه‌سازی نمی‌کند. برای این مرورگرها، نکته‌ابزاری که ازطریق تمرکز باز شده است ممکن است وقتی نکته‌ابزار دوم ازطریق نگه داشتن نشانگر باز می‌شود، باز بماند.

برای پشتیبانی از مرورگرهای بدون موقعیت‌یابی لنگر، می‌توانید از شبیه‌ساز مرورگر @oddbird/css-anchor-positioning استفاده کنید. همچنین می‌توانید از @supports برای مشخص کردن موقعیت بازگشت استفاده کنید.

هنگام استفاده از شبیه‌ساز مرورگر @oddbird/css-anchor-positioning برای پشتیبانی از مرورگر قدیمی، توجه داشته باشید که شبیه‌ساز مرورگر از لنگرهای ضمنی یا position-area در منوهای بالاپر پشتیبانی نمی‌کند. به‌طور صریح anchor-name را روی راه‌انداز تنظیم کنید، position-anchor را روی popover تنظیم کنید، و به‌جای position-area، از توابع درج anchor() برای موقعیت‌یابی استفاده کنید: 

<!-- MANDATORY: Conditionally install the anchor positioning polyfill -->
<script type="module">
  if (!("anchorName" in document.documentElement.style)) {
    await import("https://unpkg.com/@oddbird/css-anchor-positioning");
  }
</script>

button[interestfor="tooltip-attrs"] {
  /* MANDATORY: Each trigger and popover pair must have a unique anchor name, referenced by `anchor-name` on the trigger and `position-anchor` on the popover. */
  anchor-name: --tooltip-attrs;
}
#tooltip-attrs {
  position-anchor: --tooltip-attrs;
  /* If using the anchor positioning polyfill with a popover, DO use `anchor()` functions, and not `position-area. */
  top: anchor(bottom);
  left: anchor(right);
  margin: unset;
}