Orbitvu VIEWER (wersje SUN, Free i Infinity360) obsługuje API, które umożliwia dostosowanie interfejsu użytkownika przeglądarki. W tym samouczku zaimplementujemy przyciski Viewer, aby wyglądały jak poniżej.
Prosimy zwrócić uwagę, że ten samouczek jest przeznaczony dla osób posiadających co najmniej podstawową wiedzę z zakresu tworzenia stron internetowych (HTML, JavaScript, CSS).
Układ strony
Zaczynamy od zdefiniowania układu naszej strony i naszych własnych przycisków. Będziemy pracować z prezentacją demo z serwera SUN.
Jest kilka ciekawych rzeczy do odnotowania w powyższym kodzie:
Linia 10: Ładujemy bibliotekę Font Awesome, aby uzyskać ładne ikony dla naszych przycisków.
Linie 16-23: Osadzony kod skopiowany z Orbitvu Sun
Linie 15, 25, 27-231: zauważ, że id tych elementów jest ustawiony na unikalny przy użyciu uid prezentacji z Orbitvu Sun (WZarBpyJ7hHX77zaF49Rb9 w tym przypadku). Będzie to przydatne, jeśli mamy wiele prezentacji na tej samej stronie.
Być może zastanawiasz się, dlaczego na najwyższym poziomie są dwa elementy <div>:
Jest to wymagane, aby przycisk Fullscreen działał poprawnie na niektórych starszych przeglądarkach. Więcej szczegółów na ten temat znajdziesz póżniej, kiedy będziemy dodawać obsługę przycisków pełnoekranowych.
Jeżeli zamierzasz używać prezentacji hostowanej na własnym serwerze (nie z Orbitvu SUN), to musisz zamieścić swoją prezentację w sposób opisany w niniejszej dokumentacji.
Dodamy teraz kilka stylów, aby uzyskać pożądany układ strony.
Nasza strona wygląda teraz jak poniżej. Możesz ją zobaczyć w osobnym oknie i sprawdzić źródło klikając tutaj.
Dostęp do API VIEWER
Mamy zdefiniowany układ strony, więc teraz nadszedł czas na na połączenie z API Viewer. Aby to zrobić, najpierw musimy zdefiniować funkcję callback, która będzie otrzymywała obiekt API zaraz po zainicjalizowaniu API VIEWER-a. Można to zrobić za pomocą parametru viewer_api_init. Zacznijmy od napisania naszej funkcji callback (kod funkcji należy umieścić przed kodem osadzającym SUN, np. tuż przed zamykającym znacznikiem </head>):
Początkowo wyświetli tylko tekst 'api initialized'.
Teraz podłączymy naszą funkcję callback do VIEWER-a. Ponieważ używamy kodu osadzającego z Orbitvu SUN, do querystring dodamy po prostu viewer_api_init, w ten sposób: &viewer_api_init=api_init (zobacz podświetloną część kodu poniżej)
Teraz powinieneś zobaczyć tekst 'api initialized', wysłany do konsoli. Jeśli to nie działa, sprawdź, czy w konsoli nie ma błędów, a w przypadku gdy nie używasz SUN, czy Twój VIEWER wspiera API.
Możliwość ponownego użycia kodu
Funkcja callback, którą zdefiniowaliśmy ma jeden mały problem. Jest ona zdefiniowana jako funkcja globalna, zwana api_init, więc jeśli chcemy dodać kolejną prezentację 360 na stronę, będziemy musieli upewnić się, że nazwa funkcji callback jest unikalna (tak, byśmy mogli połączyć się z właściwą instancją przeglądarki).
Będziemy używać uid prezentacji: WZarBpyJ7hHX77zaF49Rb9 jako części nazwy funkcji callback. Zmienimy także nasz kod w klasę, tak aby można go było łatwo ponownie wykorzystać.
Naszym identyfikatorem funkcji callback będzie teraz 'api_init_WZarBpyJ7hHX77zaF49Rb9'. A kod osadzający VIEWER będzie miał postać:
Nasza klasa JavaScript zostanie zdefiniowana w następujący sposób:
Używamy klas ES6 i arrow functions. Jeśli potrzebujesz wsparcia dla starszych przeglądarek upewnij się, że używasz kompilata, takiego jak Babel, aby kod był kompatybilny wstecz.
Korzystanie z API VIEWER
Teraz możemy zrobić coś użytecznego z naszym obiektem API. Być może zauważyłeś (zwłaszcza, jeśli korzystasz z wolniejszej sieci lub masz ograniczoną prędkość sieciową w Developer Tools), że po załadowaniu naszej strony niestandardowe przyciski są wyświetlane natychmiast, a VIEWER jest inicjalizowany nieco później.
Nie jest to pożądane zachowanie ponieważ nie możęmy użyć przycisków zanim VIEWER nie został zainicjowany. To co powinniśmy zrobić to ukryć na wstępie nasze przyciski i wyświetlać je dopiero po inicjalizacji VIEWER-a. Można to łatwo zrobić korzystając ze zdarzenia partially_initialized, które jest wyzwalane przez VIEWER w momencie gdy zostały załadowane pierwsze 4 klatki (jeśli partial_load jest włączony).
Istnieje również wywołanie zwrotne viewer_initialized, które jest wywoływane po załadowaniu wszystkich klatek.
Najpierw dodamy display: none do naszego elementu kontenera dla przycisków:
Następnie dodamy event handler, który pokaże przyciski w chwili inicjalizacji VIEWER.
Linia 14: powiązanie wywołania zwrotnego ze zdarzeniem partially_initialized
Linia 19: definicja wywołania zwrotnego
Linia 20: przechowywanie obiektu API w zmiennej
Linia 24: pokazanie panelu przycisków poprzez zmianę stylu wyświetlania na flex
Powstała w ten sposób strona wygląda teraz jak poniżej. Możesz ją otworzyć w nowym oknie i sprawdzić kod źródłowy tutaj.
Ponowna implementacja panelu sterowania
Czas na zrobienie czegoś bardziej użytecznego. Zacznijmy ponownie implementować przyciski VIEWER-a.
Przycisk automatycznego obracania (autorotate)
Niektóre wymagania dotyczące implementacji przycisku Autorotate:
- rozpocznij automatyczną rotację (jeśli nie jest uruchomiona)
- zatrzymaj automatyczną rotację (jeśli jest uruchomiona)
- zmień kolor przycisku, gdy uruchomiona jest autorotacja
- zmień kolor przycisku, gdy automatyczna rotacja jest zatrzymana
Zdarzenia i wywołania API, z których będziemy korzystać:
- autorotate - wywołanie API w celu rozpoczęcia/zatrzymania automatycznej rotacji
- autorotate_stop - zdarzenie wyzwalane po zatrzymaniu autorotacji
- autorotate_start - zdarzenie wyzwalane po uruchomieniu autorotacji
Nasz kod zdefiniuje funkcję callback dla zdarzeń autorotate_start oraz autorotate_stop w celu "poznania" aktualnego stanu autoobrotu - stan ten zostanie zapisany w zmiennej, oraz w celu zmiany koloru przycisku. Kliknięcie przycisku spowoduje automatyczne rozpoczęcie/zatrzymanie obrotu, w zależności od jego aktualnego stanu.
- Linia 7: zapisuje aktualny stan autoobrotu
- Linie 24-29: wiąże funkcję callback z VIEWER-em
- Linie 36-43: wywołanie autorotate_start oraz autorotate_stop - zaktualizowanie bieżącego stanu i ponowne narysowanie przycisku
- Linie 51-58: obsługa kliknięcia dla przycisku autorotate - wywołuje VIEWER API: autorotate
- Linie 61-69: zmiana koloru przycisku w zależności od aktualnego stanu autoobrotu (używa aktywnej klasy CSS)
Zobacz jak to działa teraz. Pełnoekranowy przykład można znaleźć tutaj.
Przybliżanie i oddalanie
Pierwsza, trywialna implementacja może być następująca (aby poprawić czytelność, poniższy kod nie zawiera implementacji przycisku autorotate):
Zobacz poniżej jak to działa (pełnoekranowy przykład można znaleźć tutaj):
Przyciski powiększania i pomniejszania działają, ale trzeba je wielokrotnie klikać za każdym razem, gdy chcesz przybliżyć lub oddalić obiekt. Byłoby lepiej (i zgodnie z oryginalną implementacją), gdybyśmy mogli kliknąć przycisk, przytrzymać go i aby powiększanie/pomniejszanie działało aż do momentu zwolnienia przycisku.
W tym celu użyjemy biblioteki Hammer.js do obsługi zdarzeń click and touch w ustandaryzowany sposób, następnie użyjemy setInterval na początku zdarzeń touch/click aby uzyskać ciągłość powiększania, aż do momentu zakończenia operacji click/touch (cleverInterval).
Nie zagłębimy się tutaj w szczegóły biblioteki Hammer.js, wystarczy powiedzieć, że definiuje ona trzy zdarzenia, których używamy: tap, press i pressup. Po użyciu tap (czyli po prostu naciśnięciu i zwolnieniu przycisku) po prostu uruchamiamy akcję jednorazowego powiększenia. W przypadku zdarzenia press, które identyfikuje dłuższe naciśnięcie przycisku, uruchamiamy funkcję callback setInterval , które w sposób ciągły powiększa prezentację (do momentu zwolnienia przycisku - zdarzenie pressup).
- Linie 20-25: funkcja pomocnicza do wyzerowania interwałów
- Linie 28-30: nawet jeśli mamy wywołania zwrotne ustawione przez Hammer, nadal musimy zablokować domyślne zachowanie onClick
- Linie 33-47: dodatkowe handlery dla zdarzeń mouseout/pointerout. Może się zdarzyć, ze użytkownik kliknie prawym przyciskiem myszy podczas powiększania i w takiej sytuacji zdarzenie pressup nie zostanie wywołane. Z tego powodu nasłuchujemy tych dodatkowych zdarzeń, aby natychmiast przerwać powiększanie.
- Linie 61, 67, 71: wywołanie API VIEWER w celu powiększenia
- Linie 111, 117, 121: wywołanie API Viewer w celu pomniejszenia
Rezultat można zobaczyć na stronie tutaj:
Przeciągnij/obróć przycisk
Przeciągnij/obróć przycisk zmienia sposób w jaki działa przeciąganie myszą nad prezentacją. Może ono powodować obrót prezentacji lub przesuwanie bieżącej klatki. Domyślnie VIEWER będzie w trybie rotate, ale po powiększeniu automatycznie przełączy się w tryb drag (tylko jeśli auto_drag_switch jest włączony (domyślnie)).
Aby ponownie zaimplementować ten przycisk musimy zmienić jego wygląd w chwili zmiany trybu działania (zdarzenie mode_changed) i przełączyć tryb na kliknięcie.
Linia 9: zapisuje aktualną wartość trybu działania przycisku
Linie 26-28: funkcja callback dla zdarzenia mode_changed jest rejestrowana
Linie 32-35: funkcja callback aktualizuje bieżący stan i przycisk jest odświeżany
Linie 45-56: handler dla kliknięcia na przycisku, wywołuje metodę API VIEWER
Tak to działa:
Przycisk wejścia w tryb pełnoekranowy
Ostatnim przyciskiem do wykonania jest przycisk Fullscreen. Zanim wgłębimy się w szczegóły, musimy zastanowić się nad kilkoma ważnymi kwestiami. Przede wszystkim należy zauważyć, że Fullscreen API nie jest obsługiwane przez każdą przeglądarkę. Oznacza to, że w niektórych przeglądarkach w ogóle nie będziemy używać pełnoekranowego trybu lub zaimplementujemy jakieś obejścia (np. zmiana rozmiaru niektórych elementów na stronie).
W tym tutorialu będziemy trzymać się tylko przeglądarek obsługujących Fullscreen API i w celu ułatwienia korzystania z niego będziemy używać biblioteki Screenfull.
Drugą rzeczą, nad która musimy się zastanowić jest element, który zostanie przełączony w tryb pełnoekranowy. Fullscreen API działa poprzez zmianę stylów (CSS) wybranego elementu i wprowadzenie go do Fullscreen. Oznacza to, że możemy przełączyć ORBITVU VIEWER w tryb pełnoekranowy, ale nasze przyciski, które są zdefiniowane poza VIEWER-em pozostaną poza trybem pełnoekranowym i tym samym pozostaną niewidoczne. Tak więc, to co możemy zrobić, to stworzyć własny element, zawierający zarówno VIEWER jak i nasze własne przyciski, oraz użyć na nim Fullscreen API. To właśnie zamierzamy zrobić w tym tutorialu. Elementem, który zostanie przełączony na tryb pełnoekranowym będzie: viewer-container-WZarBpyJ7hHX77zaF49Rb9.
Jest jeszcze jeden problem przy tym podejściu. Jeśli przełączymy zewnętrzny (dla VIEWER-a) element w tryb Fullscreen, to sam VIEWER "nie wie" o tym. Ważne jest, aby VIEWER "wiedział" o przejściu w tryb fullscreen ze względu na fakt, że ma zmienić swoje wymiary, nawet jeśli zostały one wymuszone np. poprzez ustawienie wyraźnej szerokości i wysokości (innymi słowy, możesz chcieć mieć małe okno VIEWER na stronie (np 200px x 350px), ale przełączając się na pełny ekran chcesz, aby skalować je do całej dostępnej przestrzeni. Z tego powodu będziemy musieli poinformować VIEWER o przejściu w tryb pełnoekranowy i będzie to wykonane przy użyciu wywołania metody fullscreen z API VIEWER-a.
Spójrz na kod:
Linia 13: zapamiętuje aktualny stan ekranu
Linia 32: w momencie zmiany trybu pełnoekranowego, jeśli włączony jest tryb pełnoekranowy, wywołuje metodę 'fullscreen: enter' z VIEWER API
Linia 35: w momencie zmiany trybu pełnoekranowego, jeśli tryb pełnoekranowy jest wyłączony, wywołuje metodę 'fullscreen: cancel' z VIEWER API
Linia 46: w chwili kliknięcia na przycisk fullscreen wywołuje metodę 'fullscreen:pre' z VIEWER API.
Linia 47: przełączanie trybu pełnoekranowego
Jak widać, użyliśmy tutaj trzech metod API dla przejścia w tryb pełnoekranowy
- pre - przechowuje aktualne wymiary elementów VIEWER-a (dzieki czemu będziemy mogli je przywrócić)
- enter - usuwa aktualnie wymuszone wymiary, np. szerokość (powinno być wywołane po pre)
- cancel - przywraca wymiary, które były zachowane przez pre - powinno być wywołane w chwili wyjścia z trybu pełnoekranowego.
Ostatnich kilka rzeczy do zrobienia to:
- ukryć domyślne przyciski VIEWER
- wyłączyć domyślne podwójne stuknięcie/podwójne kliknięcie VIEWER-a, które powoduje wejście w tryb pełnoekranowy (ponieważ nie chcemy wprowadzać samego tylko VIEWER-a w tryb pełnoekranowy).
Obie te rzeczy można łatwo zrobić dodając parametry do naszego kodu osadzenia prezentacji. Parametrem do usunięcia przycisków jest style a parametrem do zmiany zachowania podwójnego kliknięcia jest doubletap_mode.
Wynikiem tego jest następujący kod:
Kompletny przykład można znaleźć tutaj: