Biblioteka ScrollReveal.js

1. Wprowadzenie

ScrollReveal to biblioteka JavaScript do łatwego implementowania animacji przewijania stron internetowych.

1.1. Instalacja biblioteki ScrollReveal

Najprostszym sposobem jest wklejenie tego elementu HTML zaraz przed zamykającym znacznikiem </body>.

<script src="https://cdn.jsdelivr.net/scrollreveal.js/3.3.1/scrollreveal.min.js"></script>

Inne sposoby to:

pobranie plików w archiwum ZIP
npm install scrollreveal
bower install scrollreveal

1.2. Podstawy

Podstawowym API jest metoda reveal(), za pomocą której można z łatwością tworzyć i konfigurować różne rodzaje animacji.

<!-- HTML -->
<div class="foo"> Foo </div>
<div class="bar"> Bar </div>

// JavaScript
window.sr = ScrollReveal();
sr.reveal('.foo');
sr.reveal('.bar');

1.3. Łączenie wywołań metod

Konstruktor ScrollReveal i główne metody można łączyć w łańcuchy wywołań.

window.sr = ScrollReveal();
sr.reveal('.foo');
sr.reveal('.bar');

// powyższe jest tożsame z tym
window.sr = ScrollReveal().reveal('.foo, .bar');

2. Konfiguracja

Przekazując do konstruktora ScrollReveal() obiekt konfiguracyjny, można zmienić ustawienia domyślne wszystkich animacji, natomiast przekazując obiekt konfiguracyjny do metody reveal() można zdefiniować dodatkowe ustawienia.

2.1. Praktyczny przykład

// zmiana ustawień domyślnych
window.sr = ScrollReveal({ reset: true });

// dostosowywanie ustawień
sr.reveal('.foo', { duration: 200 });

2.2. Początkowe ustawienia domyślne

// 'bottom', 'left', 'top', 'right'
origin: 'bottom',

// może być dowolna jednostka długości CSS, np. '5rem', '10%', '20vw' itd.
distance: '20px',

// czas w milisekundach
duration: 500,
delay: 0,

// początkowe kąty w stopniach; nastąpi przejście od tych wartości do 0 na wszystkich osiach
rotate: { x: 0, y: 0, z: 0 },

// początkowa wartość przezroczystości, stosowana przed przejściem do obliczonej przezroczystości
opacity: 0,

// początkowa wartość skalowania; nastąpi przejście od tej wartości do 1
scale: 0.9,

// przyjmuje dowolną funkcję przebiegu animacji CSS, np. ease, ease-in-out, linear itd.
easing: 'cubic-bezier(0.6, 0.2, 0.1, 1)',

// domyślnym kontenerem jest element html. Można przekazać:
// węzeł DOM, np.: document.querySelector('.fooContainer')
// selektor, np.: '.fooContainer'
container: window.document.documentElement,

// do wyboru są wartości true i false, włączające i wyłączające animacje w urządzeniach mobilnych
mobile: true,

// true:  animacja jest włączana za każdym razem, gdy elementy stają się widoczne
// false: animacja jest włączana tylko przy pierwszym wyświetleniu elementów
reset: false,

// 'always' — opóźnienie wszystkich animacji
// 'once'   — opóźnienie tylko pierwszej animacji
// 'onload' - opóźnienie tylko tych animacji, które są włączane przy pierwszym ładowaniu
useDelay: 'always',

// pozwala określić, kiedy element ma zostać uznany za obecny w polu widoku Domyślna wartość
// 0.20 oznacza, że animacja zostanie włączona, gdy na stronie pojawi się 20% elementu
viewFactor: 0.2,

// wartości pikselowe określające granice kontenera
// np.: ustaw `{ top: 48 }`, jeśli masz stały pasek narzędzi o wysokości 48 pikseli
// --
// Wskazówka wizualna: https://scrollrevealjs.org/assets/viewoffset.png
viewOffset: { top: 0, right: 0, bottom: 0, left: 0 },

// Metody zwrotne wywoływane przed każdą animacją elementu i resetem
beforeReveal: function (domEl) {},
beforeReset: function (domEl) {},

// Metody zwrotne wywoływane po każdej animacji elementu i resecie
afterReveal: function (domEl) {},
afterReset: function (domEl) {}

3. Przykłady zaawansowane

3.1. Animacje sekwencyjne

Do metody reveal() można przekazać odstęp czasowy (w milisekundach), aby utworzyć animację sekwencyjną.

// przekazanie odstępu czasowego do metody reveal()
window.sr = ScrollReveal({ duration: 2000 });
sr.reveal('.box', 50);

// lub...

// przekazanie odstępu czasowego i obiektu konfiguracji do metody reveal()
window.sr = ScrollReveal();
sr.reveal('.box', { duration: 2000 }, 50);

3.2. Zmienianie konfiguracji

Metoda reveal() obsługuje wywołania na tym samym elemencie, dzięki czemu programista łatwo może zmienić jego konfigurację.

<div class="foo"> Foo </div>
<div class="foo" id="chocolate"> Chip </div>

var fooReveal = {
  delay    : 200,
  distance : '90px',
  easing   : 'ease-in-out',
  rotate   : { z: 10 },
  scale    : 1.1
};

window.sr = ScrollReveal();
sr.reveal('.foo', fooReveal);
sr.reveal('#chocolate', { delay: 500, scale: 0.9 });

3.3. Praca z węzłami DOM

W pracy z metodą reveal() nie trzeba ograniczać się do używania samych selektorów. Metoda ta jako pierwszy argument przyjmuje też węzły i listy węzłów.

sr.reveal(document.getElementById('foo'));
sr.reveal(document.querySelectorAll('.bar'));

3.4. Własne i dodatkowe kontenery

Domyślnym kontenerem jest obszar widoku, ale do każdego zestawu animacji można przypisać dowolny inny kontener.

<div id="fooContainer">
  <div class="foo"> Foo 1 </div>
  <div class="foo"> Foo 2 </div>
  <div class="foo"> Foo 3 </div>
</div>

<div id="barContainer">
  <div class="bar"> Bar 1 </div>
  <div class="bar"> Bar 2 </div>
  <div class="bar"> Bar 3 </div>
</div>

window.sr = ScrollReveal();

// jako węzeł DOM...
var fooContainer = document.getElementById('fooContainer');
sr.reveal('.foo', { container: fooContainer });

// jako selektor...
sr.reveal('.bar', { container: '#barContainer' });

3.5. Treść asynchroniczna

Metoda sync() stosuje animacje do asynchronicznie ładowanej treści.

Przykład:

<!-- index.html -->
<div id="fooContainer">
  <div class="foo">foo</div>
  <div class="foo">foo</div>
  <div class="foo">foo</div>
</div>

<!-- ajax.html -->
<div class="foo">foo async</div>
<div class="foo">foo async</div>
<div class="foo">foo async</div>

var fooContainer, content, sr, xmlhttp;

fooContainer = document.getElementById('fooContainer');

sr = ScrollReveal();
sr.reveal('.foo', { container: fooContainer });

// utworzenie nowego żądania asynchronicznego...
xmlhttp = new XMLHttpRequest();
xmlhttp.onreadystatechange = function() {
  if (xmlhttp.readyState == XMLHttpRequest.DONE) {
    if (xmlhttp.status == 200) {

      // zamiana odpowiedzi na HTML...
      var content = document.createElement('div');
      content.innerHTML = xmlhttp.responseText;
      content = content.childNodes;

      // dodanie każdego elementu do DOM...
      for (var i = 0; i < content.length; i++) {
        fooContainer.appendChild(content[ i ]);
      };

      // W końcu!
      sr.sync();
    }
  }
}

xmlhttp.open('GET', 'ajax.html', true);
xmlhttp.send();

4. Porady

4.1. Kolejność ma znaczenie

Wywołania metody reveal() powinny być wykonywane jak najbliżej końca strony, aby:

elementy strony zdążyły się załadować,
wszystkie inne biblioteki zdążyły wykonać swoje zadania,
inne style zdefiniowane dla elementów nie zostały przesłonięte.

Przykład:

<!DOCTYPE html>
<html>
  <head>
    <!-- najpierw ładujemy i tworzymy egzemplarz ScrollReveal -->
    <script src="js/scrollreveal.min.js"></script>
    <script>
      window.sr = ScrollReveal();
    </script>
  </head>
  <body>

    <div class="fooContainer">
      <div class="fooReveal"> Foo </div>
      <div class="fooReveal"> Foo </div>
      <div class="fooReveal"> Foo </div>
    </div>

<!-- wywołania metody reveal() wykonujemy na końcu -->
    <script>
      sr.reveal('.fooReveal', { container: '.fooContainer' });
    </script>

  </body>
</html>

4.2. Udogodnienia dla użytkownika

W większości przypadków elementy początkowo mają ustawienie opacity: 0, dzięki czemu mogą się powoli pojawiać. Ponieważ jednak JavaScript ładuje się po rozpoczęciu renderowania strony, elementy te mogą na chwilę się pokazać, zanim zostaną ukryte przez skrypt ScrollReveal.

Najlepszym rozwiązaniem tego problemu jest ukrycie animowanych elementów za pomocą odpowiednich ustawień w sekcji head strony, aby pozostawały ukryte podczas ładowania skryptów JavaScript.

Kontynuacja przykładu z sekcji 4.1.

<!DOCTYPE html>
<html>
  <head>
    <!-- najpierw ładujemy i tworzymy egzemplarz ScrollReveal -->
    <script src="js/scrollreveal.min.js"></script>
    <script>
      window.sr = ScrollReveal();

      // dodanie klasy do elementu html, jeśli obsługiwana jest biblioteka ScrollReveal
      if (sr.isSupported()) {
        document.documentElement.classList.add('sr');
      }

    </script>

    <style>

      /* ukrycie elementów do czasu uruchomienia biblioteki ScrollReveal */
      .sr .fooReveal { visibility: hidden; }

    </style>

  </head>
  <body>

    <div class="fooContainer">
      <div class="fooReveal"> Foo </div>
      <div class="fooReveal"> Foo </div>
      <div class="fooReveal"> Foo </div>
    </div>

    <!-- wywołania metody reveal() wykonujemy na końcu -->
    <script>
      sr.reveal('.fooReveal', { container: '.fooContainer' });
    </script>

  </body>
</html>

4.3. Dodawanie perspektywy do rotacji trójwymiarowej

Biblioteka ScrollReveal obsługuje rotację trójwymiarową, ale czasami dla podkreślenia efektu dobrze jest zdefiniować własność perspektywy kontenera.

Kontynuacja przykładu z sekcji 4.2.

<!DOCTYPE html>
<html>
  <head>
    <!-- najpierw ładujemy i tworzymy egzemplarz ScrollReveal -->
    <script src="js/scrollreveal.min.js"></script>
    <script>
      window.sr = ScrollReveal();

      // dodanie klasy do elementu html, jeśli obsługiwana jest biblioteka ScrollReveal
      if (sr.isSupported()) {
        document.documentElement.classList.add('sr');
      }

    </script>

    <style>

      /* ukrycie elementów do czasu uruchomienia biblioteki ScrollReveal */
      .sr .fooReveal { visibility: hidden; }

      /* dodanie perspektywy do kontenera */
      .fooContainer { perspective: 800px; }

    </style>

  </head>
  <body>

    <div class="fooContainer">
      <div class="fooReveal"> Foo </div>
      <div class="fooReveal"> Foo </div>
      <div class="fooReveal"> Foo </div>
    </div>

  <!-- wywołania metody reveal() wykonujemy na końcu -->
    <script>
      // zastosowanie rotacji
      sr.reveal('.fooReveal', { container: '.fooContainer', rotate: {x: 65} });
    </script>

  </body>
</html>

5. Informacje końcowe

5.1. Zgodność z przeglądarkami

Biblioteka ScrollReveal działa w każdej przeglądarce obsługującej JavaScript oraz transformacje i przejścia CSS. Do grupy tej zalicza się Internet Explorer 10+ i większość nowoczesnych przeglądarek dla komputerów stacjonarnych i przenośnych.

5.2. Podziękowania

Inspiracją do napisania biblioteki ScrollReveal był dla mnie skrypt cbpScroller.js Manoeli Ilic.