KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / JavaScript

IntersectionObserver-opties: root, rootMargin en threshold

`root` kiest het referentiegebied, `rootMargin` past de grenzen ervan aan voor de berekening en `threshold` bepaalt bij welke delen van het doeloppervlak meldingen volgen.

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

Syntax

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

IntersectionObserver is een browser-API, geen onderdeel van ECMAScript. root kiest het referentiegebied: als je de optie weglaat of null doorgeeft, wordt de viewport van het bovenste document gebruikt. Een expliciete root kan een Document of een Element zijn, bijvoorbeeld een scrollcontainer. Bij een element als root moet het doel er een afstammeling van zijn in de keten van omsluitende blokken die de lay-out bepalen.

rootMargin is een tekenreeks met één tot vier absolute CSS-lengtes of percentages, uitgewerkt zoals bij CSS margin: boven, rechts, onder, links. Volgens de specificatie worden absolute lengtes, bijvoorbeeld in cm, bij het verwerken van de tekenreeks naar pixels omgerekend. Gebruik voor compatibiliteit tussen browsers px of %, omdat sommige browsers andere absolute eenheden weigeren. Elke zijde is standaard 0px. Percentages worden berekend op basis van de breedte van de oorspronkelijke rootrechthoek, ook boven en onder. Positieve waarden vergroten de rechthoek voor de berekening; negatieve verkleinen die. Dit verandert de lay-out niet en heft afsnijding door tussenliggende voorouders niet op. Bij doelen met een andere oorsprong wordt de marge genegeerd en is entry.rootBounds gelijk aan null.

threshold accepteert één getal of een array met getallen van 0 tot en met 1. Laat je de optie weg of geef je een lege array mee, dan geldt drempel 0. De constructoroptie heet threshold; de alleen-lezen eigenschap observer.thresholds geeft een numeriek oplopend gesorteerde array terug. Een drempel buiten het bereik levert een RangeError op; een ongeldige rootMargin levert een DOMException met de naam SyntaxError op.

Na observe(target) ontvangt de callback asynchroon een eerste record, ook zonder doorsnijding. Extra records worden in de wachtrij gezet als een drempel in een van beide richtingen wordt gepasseerd of entry.isIntersecting verandert, niet telkens als de verhouding verandert. 0.5 betekent de helft van het oppervlak van de begrenzingsrechthoek van het doel, niet van de root. Randcontact kan isIntersecting: true opleveren bij intersectionRatio: 0. Bij een doelrechthoek met oppervlakte nul is de verhouding 1 als isIntersecting waar is en anders 0. Een geometrische doorsnijding bewijst niet dat de gebruiker het doel kan zien.

De opties liggen vast zodra je de observer aanmaakt. Maak een nieuwe observer om ze te wijzigen. Met unobserve(target) stop je het observeren van één doel, met disconnect() dat van alle doelen. Controleer of de uitvoeromgeving de API ondersteunt.

Voorbeelden

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

Resultaat

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

Sla het voorbeeld op als HTML-bestand, open het in een actief browsertabblad en bekijk de uitvoer in de ontwikkelaarsconsole. Het doel begint 20 px onder de onderrand van de root. De ondermarge van 40 px omvat de helft van de doelhoogte over de volle breedte. Het eerste record meldt daarom `intersectionRatio: 0.5`. De code stopt de observer en verwijdert de demo-elementen.

Gerelateerde lessen

  • JavaScript · Les 30 · Gemiddeld · Versie: 3

Bronnen