Selektoren
Standardmäßig sucht Glaze nach Elementen mit dem Attribut data-animate und erstellt die Animation anhand des Attributwerts. Auf dieser Seite werden die drei Optionen behandelt, die ändern, welche Elemente Glaze liest: dataAttribute, className und element sowie die Selektoren in eckigen Klammern, die eine Animation auf andere Elemente verweisen lassen. Die Hilfsfunktionen innerhalb der Zeichenfolge werden unter Syntax beschrieben.
So werden Elemente gefunden
Wenn glaze() ausgeführt wird sowie bei jeder refresh()- oder Watch-Mode-Neuerstellung durchläuft es alle Elemente innerhalb des Stammelements und behält diejenigen bei, die das konfigurierte Attribut oder im Klassenmodus eine Klasse mit dem konfigurierten Präfix enthalten. Auch das Stammelement selbst wird berücksichtigt, wenn es eines davon enthält. Die Elemente werden in Dokumentreihenfolge gelesen.
Jedes auf diese Weise gefundene Element erhält eine eigene Timeline, sofern es sich nicht innerhalb eines tl-Elements befindet oder mit tl:<id> darauf verweist. In diesem Fall wird es stattdessen dieser Timeline hinzugefügt. Unter Timelines erfährst du, wie die Gruppierung funktioniert.
Benutzerdefiniertes Attribut
Verwende ein anderes Datenattribut:
glaze({
lib: { gsap: { core: gsap } },
dataAttribute: "data-move",
})
Jetzt sucht Glaze nach data-move statt nach data-animate:
<div data-move="from:opacity-0"></div>
Die Option ersetzt das Attribut, statt ein weiteres hinzuzufügen. Mit der obigen Einstellung wird ein Element, das weiterhin data-animate trägt, ignoriert. Verwende sie, wenn ein anderes Skript auf der Seite bereits data-animate ausliest oder wenn das Markup das Attribut nach deinem Projekt benennen soll.
Im Beobachtungsmodus überwacht Glaze das konfigurierte Attribut. Ändert sich der Wert von data-move an einem Element, wird ein Neuaufbau geplant.
Klassensyntax
Bevorzugst du Klassen gegenüber Datenattributen? Aktiviere den Klassenmodus:
glaze({
lib: { gsap: { core: gsap } },
className: "animate",
})
Jetzt kannst du Animationen als Klassen schreiben:
<div class="animate-from:opacity-0|duration-1"></div>
Das funktioniert gut, wenn du bereits utility-first CSS verwendest und deine Animationen ähnlich wirken sollen. Der Klassenmodus ist auch nützlich, wenn du mit einem Templatesystem Klassen zu einem Element hinzufügen kannst, aber keine beliebigen Attribute.
Glaze liest jede Klasse aus, die mit dem Präfix gefolgt von einem Bindestrich beginnt (hier animate-), und entfernt diesen Teil. Klassen ohne das Präfix bleiben unverändert, sodass Animationsklassen neben Styling-Klassen am selben Element stehen können. Du kannst eine Animation auf mehrere Klassen aufteilen:
<div class="card animate-from:opacity-0 animate-from:y-24"></div>
Responsive Klassen akzeptieren den Breakpoint nach oder vor dem Präfix. Beide Varianten werden nur ausgeführt, wenn der lg-Breakpoint zutrifft:
<div class="animate-@lg:from:opacity-0"></div>
<div class="@lg:animate-from:opacity-0"></div>
Voreinstellungen funktionieren in Klassen genauso, zum Beispiel animate-preset-fadeIn.
Der Klassenmodus deaktiviert das Datenattribut nicht. Wenn ein Element beides hat, fügt Glaze sie zu einer Zeichenfolge zusammen: zuerst der Attributwert, dann die Präfixklassen in der Reihenfolge, in der sie im Attribut class vorkommen.
<div
class="animate-from:opacity-0 animate-@lg:from:y-50"
data-animate="from:duration-1"
></div>
Dieses Element animiert sich bei jeder Größe eine Sekunde lang von opacity: 0 aus und außerdem von y: 50, wenn lg zutrifft. Da die Zeichenfolgen zusammengefügt werden, gilt dieselbe Regel wie innerhalb einer einzelnen Zeichenfolge: Wenn zwei Teile dieselbe Eigenschaft festlegen, gewinnt der spätere. Hier überschreibt der Klassenwert den Attributwert für x:
<div class="animate-to:x-100" data-animate="to:x-50|y-20"></div>
Das Element animiert sich zu x: 100 und y: 20.
Wenn watch im Klassenmodus aktiviert ist, beobachtet Glaze auch Änderungen an class. Wird einem Element eine animate--Klasse hinzugefügt oder werden die Klassen eines Elements geändert, das Glaze bereits ausliest oder animiert, wird ein Neuaufbau geplant. Innerhalb eines Elements mit einem relativen Selektor führen auch Klassenänderungen an dessen Nachfahren dazu, da sie beeinflussen können, auf welche Elemente der Selektor zutrifft. Klassenänderungen an anderen Elementen haben keine Auswirkungen. Dazu zählen auch Vorfahren animierter Elemente: Wird eine Klasse für den Dunkelmodus an <html> oder eine Klasse zum Sperren des Scrollens an <body> umgeschaltet, laufen die Animationen ungestört weiter. Auch eine Klassenänderung, durch die ein Element neu auf einen globalen Selektor zutrifft, wird nicht erkannt. Rufe danach refresh() auf.
Suche einschränken
Glaze durchsucht standardmäßig das gesamte document. Übergib element, um nur Elemente innerhalb eines Containers zu animieren:
glaze({
lib: { gsap: { core: gsap } },
element: document.querySelector("#app"),
})
element akzeptiert ein Element oder ein Document. Es begrenzt drei Dinge:
- Nur die Wurzel und ihre Nachfahren werden nach Animations-Utilities durchsucht. Elemente an anderer Stelle auf der Seite werden ignoriert, selbst wenn sie
data-animatetragen. - Der Beobachtungsmodus überwacht nur Änderungen innerhalb der Wurzel.
destroy()räumt nur auf, was diese Instanz erstellt hat, damit Animationen anderer Seitenelemente erhalten bleiben.
Damit ist element die passende Option für Komponenten-Frameworks. Erstelle für jede gemountete Komponente eine Instanz mit dem Wurzelelement der Komponente und rufe beim Unmounten destroy() auf, wie unter Aktualisierung und Bereinigung gezeigt. Gib separaten Instanzen nicht überlappende Wurzeln. Ein Element innerhalb zweier Wurzeln wird von beiden Instanzen animiert.
Andere Elemente auswählen
Die obigen Optionen legen fest, welche Elemente Glaze ausliest. Ein Selektor in eckigen Klammern am Anfang eines Segments legt fest, auf welche Elemente die Animation angewendet wird. Fehlt ein solcher Selektor, zielt die Animation auf das Element, das die Utilities enthält.
Relative Selektoren
Ein Selektor, der mit & beginnt, wird vom Element selbst aus aufgelöst; & steht dabei für dieses Element. Er wird mit querySelectorAll abgefragt und kann daher mehrere Elemente treffen:
<ul data-animate="[&>li]:from:opacity-0|y-20|stagger-0.1">
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
[&>li] trifft auf die direkten li-Kindelemente zu. Der Wert stagger verteilt ihre Startzeiten mit jeweils 0,1 Sekunden Abstand. Verwende dies, wenn ein Element die Animation einer Liste, eines Rasters oder einer Gruppe von Kindelementen steuern soll, ohne jedem Kindelement ein Attribut hinzuzufügen.
Schreibe Leerzeichen als Unterstriche. [&_p] wird zu & p und trifft auf jedes p innerhalb des Elements auf beliebiger Tiefe zu:
<article data-animate="[&_p]:from:opacity-0|stagger-0.2">
<p>First paragraph</p>
<div><p>Nested paragraph</p></div>
</article>
Jeder Unterstrich in einem Selektor wird in ein Leerzeichen umgewandelt. Daher kann ein Klassenname mit Unterstrich auf diesem Weg nicht gefunden werden.
[&] für sich allein verweist auf das Element selbst. Es wird meist als Wert verwendet,
zum Beispiel scrollTrigger.trigger-[&] in ScrollTrigger
und als Standardwert in der Timeline.
Globale Selektoren
Ein Selektor ohne & wird als Zeichenfolge an die Animations-Engine übergeben. Sowohl GSAP als auch Motion lösen ihn im gesamten Dokument auf, nicht relativ zum Element oder zur element-Wurzel:
<h2 data-animate="[.badge]:from:opacity-0|scale-0.5|duration-0.3">Inbox</h2>
<span class="badge">3</span>
Damit werden alle .badge auf der Seite animiert, unabhängig davon, wo sie sich befinden. Verwende in wiederverwendbaren Komponenten lieber relative Selektoren, da ein globaler Selektor auch Kopien der Komponente an anderen Stellen der Seite trifft.
Einschränkungen
Jedes Element hat ein Ziel. Wenn mehrere Segmente einen Selektor enthalten, gilt der letzte für alle Zustände des Elements. Hier werden sowohl from als auch to auf p angewendet, nicht auf h1:
<div data-animate="[&>h1]:from:opacity-0 [&>p]:to:x-20">
<h1>Title</h1>
<p>Text</p>
</div>
Um zwei Gruppen unterschiedlich zu animieren, platziere die Utilities direkt auf den Kindelementen oder gruppiere sie in einer Timeline.
Ein Selektor endet beim ersten ]. Selektoren mit eckigen Klammern, etwa Attributselektoren wie [&>[data-item]], werden daher nicht unterstützt. Verwende stattdessen einen Klassen- oder Elementselektor.
Selektoren werden mit Breakpoints in der unter Syntax beschriebenen Reihenfolge kombiniert, zum Beispiel @lg:[&>div]:from:opacity-0.