Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / JavaScript

Volby IntersectionObserver: root, rootMargin a threshold

`root` vybírá referenční oblast, `rootMargin` upravuje její hranice pro výpočet a `threshold` určuje, při jakých podílech plochy cíle má pozorovatel posílat oznámení.

Verze: ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

new IntersectionObserver(callback, { root: null, rootMargin: "0px", threshold: [0, 0.5, 1] })

IntersectionObserver je API prohlížeče, nikoli součást ECMAScriptu. root vybírá referenční oblast: pokud volbu vynecháš nebo předáš null, použije se výřez dokumentu nejvyšší úrovně. Výslovně můžeš zadat Document nebo Element, třeba posuvný kontejner. Pokud je kořenem prvek, cíl musí být jeho potomkem v řetězci obsahujících bloků rozvržení.

rootMargin je řetězec jedné až čtyř hodnot zadaných jako absolutní délky CSS nebo procenta, které se rozepíšou jako CSS margin: nahoře, vpravo, dole, vlevo. Podle specifikace se absolutní délky, například v cm, při zpracování řetězce převádějí na pixely. Kvůli kompatibilitě mezi prohlížeči používej px nebo %, protože některé prohlížeče jiné absolutní jednotky odmítají. Výchozí hodnota každé strany je 0px. Procenta se i nahoře a dole počítají ze šířky původního obdélníku kořene. Kladné hodnoty obdélník pro výpočet rozšiřují, záporné ho zmenšují. Rozvržení se nemění a oříznutí mezilehlými předky zůstává v platnosti. U cílů z jiného zdroje se okraj ignoruje a entry.rootBounds je null.

threshold přijímá jedno číslo nebo pole čísel od 0 do 1 včetně. Vynechání volby nebo předání prázdného pole nastaví práh na 0. Volba konstruktoru se jmenuje threshold; vlastnost pouze pro čtení observer.thresholds vrací pole seřazené číselně vzestupně. Práh mimo rozsah vyvolá RangeError, neplatný rootMargin vyvolá DOMException s názvem SyntaxError.

Po observe(target) obdrží zpětná funkce asynchronně první záznam, i když k průniku nedochází. Další záznamy se zařadí do fronty při překročení prahu oběma směry nebo při změně entry.isIntersecting, nikoli při každé změně podílu. 0.5 označuje polovinu plochy ohraničujícího obdélníku cíle, ne kořene. Při dotyku hran může být isIntersecting: true a zároveň intersectionRatio: 0. Má-li obdélník cíle nulovou plochu, podíl je 1, pokud je isIntersecting pravda, jinak 0. Geometrický průnik nedokazuje, že uživatel cíl vidí.

Volby jsou pevně dané při vytvoření pozorovatele. Ke změně vytvoř nového pozorovatele. unobserve(target) ukončí sledování jednoho cíle, disconnect() sledování všech cílů. Ověř, že prostředí, ve kterém kód poběží, API podporuje.

Příklady

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IntersectionObserver options</title>
</head>
<body>
<script>
{
  const root = document.createElement("div");
  const spacer = document.createElement("div");
  const target = document.createElement("div");
  root.style.cssText = "width: 120px; height: 100px; overflow: hidden";
  spacer.style.height = "120px";
  target.style.cssText = "height: 40px; background: teal";
  root.append(spacer, target);
  document.body.append(root);

  const observer = new IntersectionObserver(([entry], observer) => {
    console.log(`root matches: ${observer.root === root}`);
    console.log(`rootMargin: ${observer.rootMargin}`);
    console.log(`thresholds: ${JSON.stringify(observer.thresholds)}`);
    console.log(`isIntersecting: ${entry.isIntersecting}`);
    console.log(`intersectionRatio: ${entry.intersectionRatio}`);
    observer.disconnect();
    root.remove();
  }, {
    root,
    rootMargin: "0px 0px 40px",
    threshold: [1, 0, 0.5],
  });
  observer.observe(target);
}
</script>
</body>
</html>

Výsledek

root matches: true
rootMargin: 0px 0px 40px 0px
thresholds: [0,0.5,1]
isIntersecting: true
intersectionRatio: 0.5

Ulož příklad jako soubor HTML, otevři ho v aktivní kartě prohlížeče a zkontroluj výstup ve vývojářské konzoli. Cíl začíná 20 px pod dolním okrajem kořene. Dolní rozšíření o 40 px zahrne polovinu výšky cíle v celé jeho šířce. První záznam proto uvádí `intersectionRatio: 0.5`. Kód pozorovatele odpojí a odstraní ukázkové prvky.

Související lekce

  • JavaScript · Lekce 30 · Středně pokročilá · Verze: 3

Zdroje