Używanie ORBITVU VIEWER jako ES module

ORBITVU VIEWER jest dostarczany z bundle'em ES module (orbitvu.esm.js), który możesz zaimportować z poziomu bundlera lub znacznika script type="module" zamiast ładować klasyczny skrypt.

Od wersji VIEWER 3.10.19 każdy pakiet ORBITVU VIEWER zawiera drugi bundle obok klasycznego:

orbitvu12/
  orbitvu.js        # classic bundle — loaded with a <script> tag
  orbitvu.esm.js    # ES module bundle — imported
  viewer5.css       # stylesheet — must be loaded separately by ES module consumers
  version.xml
  LICENSE.txt

Oba bundle'e są budowane z tego samego kodu źródłowego i renderują identycznie. Różnica polega na sposobie, w jaki Twoja strona po nie sięga: orbitvu.js trzeba załadować znacznikiem <script>, zanim będzie można go wywołać, natomiast orbitvu.esm.js importujesz — czego właśnie potrzebujesz, jeśli Twoja witryna jest budowana za pomocą Vite, webpacka, Rollupa, Next.js lub dowolnego innego bundlera.

Bundle ES module jest częścią pakietu VIEWER do pobrania — tego samego folderu orbitvu12/, który opisuje strona Hostowanie prezentacji 360° na własnym serwerze. Prezentacje hostowane w ORBITVU SUN nadal korzystają z wygenerowanego embed code i nie wymagają żadnych zmian.

Bundle ES module nie dostarcza własnych stylów. W przeciwieństwie do klasycznego bundle'a — który ładuje viewer5.css za Ciebie z folderu VIEWER-a przekazanego do inject_orbitvu — orbitvu.esm.js nie ma argumentu z folderem i sam nie dodaje żadnego arkusza stylów. Musisz załadować viewer5.css samodzielnie, inaczej prezentacja wyświetli się bez stylów.

mount_viewer

Moduł eksportuje jedną funkcję. Zaimportuj arkusz stylów obok niej — viewer5.css nie jest częścią bundle'a, a bez niego prezentacja wyświetli się bez stylów:

import { mount_viewer } from './orbitvu12/orbitvu.esm.js';
import './orbitvu12/viewer5.css';   // required — see below

const viewer = mount_viewer(containerId, params);

mount_viewer montuje VIEWER w elemencie o podanym id i zwraca instancję VIEWER-a. params to ten sam obiekt parametrów VIEWER-a, który przyjmuje klasyczny bundle — łącznie z width i height, przyjmującymi tu te same wartości co wszędzie indziej: 'auto', zwykłą liczbę albo wartość z jednostką.

O dwóch rzeczach trzeba pamiętać:

Element kontenera musi już istnieć. mount_viewer wyszukuje go po id i wypełnia; nie tworzy go.
Sam import modułu niczego nie uruchamia, więc jest bezpieczny w buildzie renderowanym po stronie serwera. Montowanie wymaga prawdziwego DOM — wywołuj mount_viewer wyłącznie w przeglądarce.

Gdy skończysz korzystać z VIEWER-a — na przykład w funkcji czyszczącej useEffect w Reakcie albo przy zmianie trasy w routerze — wywołaj destroy() na zwróconej instancji:

viewer.destroy();

Ładowanie arkusza stylów

viewer5.css jest osobnym plikiem, a nie czymś wbudowanym w bundle — dzięki temu wstrzykiwany element <style> nie może naruszyć restrykcyjnej polityki Content-Security-Policy. Import orbitvu.esm.js nie wciąga więc żadnych stylów i masz trzy sposoby, aby je dostarczyć:

Zaimportuj je obok bundle'a — sposób preferowany i jedyny bez chwilowego wyświetlenia bez stylów:

import { mount_viewer } from '../vendor/orbitvu12/orbitvu.esm.js';
import '../vendor/orbitvu12/viewer5.css';

Podlinkuj je ze strony:

<link rel="stylesheet" href="https://yourdomain.com/orbitvu12/viewer5.css" />

Przekaż viewer_base i pozwól VIEWER-owi samemu dodać <link> podczas montowania:
```
mount_viewer('presentation1-container', {
    viewer_base: 'https://yourdomain.com/orbitvu12/',
    // …
});
```
Ładowanie arkusza stylów to jedyne, co robi viewer_base — jeśli dostarczyłeś już viewer5.css jednym ze sposobów powyżej, ten parametr nie jest potrzebny.

Podstawowy przykład

index.html

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>Orbitvu presentation</title>
        <link rel="stylesheet" href="https://yourdomain.com/orbitvu12/viewer5.css" />
    </head>
    <body>
        <div id="presentation1-container"></div>

        <script type="module">
            import { mount_viewer } from 'https://yourdomain.com/orbitvu12/orbitvu.esm.js';

            mount_viewer('presentation1-container', {
                ovus_folder: 'https://yourdomain.com/presentations/presentation1/',
                content2: 'yes',
                width: '500',
                height: '400'
            });
        </script>
    </body>
</html>

Z bundlerem

Skopiuj folder orbitvu12/ do swojego projektu (albo udostępnij go z własnego hostingu statycznego) i zaimportuj bundle jak każdy inny moduł, dzięki czemu VIEWER trafi do Twojego własnego procesu budowania zasobów.

viewer.js

import { mount_viewer } from '../vendor/orbitvu12/orbitvu.esm.js';
import '../vendor/orbitvu12/viewer5.css';

export function showPresentation(containerId, presentationUrl) {
    return mount_viewer(containerId, {
        ovus_folder: presentationUrl,
        content2: 'yes',
        width: 'auto',
        height: 'auto',
        teaser: 'autorotate'
    });
}

Dostęp do API

mount_viewer zwraca instancję VIEWER-a od razu, ale obiekt API VIEWER-a powstaje później — dopiero po wczytaniu plików konfiguracyjnych prezentacji — więc odczytanie go ze zwróconej instancji nie zadziała. Zamiast tego przekaż viewer_api_init i podaj samą funkcję: callback wskazany nazwą (ciągiem znaków) jest wyszukiwany w zasięgu globalnym strony, a więc nie sięgnie funkcji zdefiniowanej wewnątrz modułu.

viewer_api_init uruchamia się wcześnie, zanim zostanie zażądana pierwsza klatka. Obiekt API jest już wtedy kompletny, ale VIEWER-em nie da się jeszcze sterować — obrót, zoom i przesuwanie nic nie zrobią, dopóki klatki nie zostaną wczytane. Użyj więc viewer_api_init do zarejestrowania swoich callbacków, a VIEWER-em steruj od zdarzenia viewer_initialized, które przekazuje ten sam obiekt API w momencie, gdy prezentacja jest gotowa:

viewer.js

import { mount_viewer } from '../vendor/orbitvu12/orbitvu.esm.js';
import '../vendor/orbitvu12/viewer5.css';

let viewerApi = null;

function onViewerReady(api) {
    viewerApi = api;
    api.setScene({ hangle: 10 });   // safe here — the viewer is loaded
}

const viewer = mount_viewer('presentation1-container', {
    ovus_folder: '/presentations/presentation1/',
    content2: 'yes',
    width: 'auto',
    height: '400px',
    viewer_api_init: (api) => {
        api.addCallback(onViewerReady, 'viewer_initialized');
    }
});

addCallback(callback, event_name) również przyjmuje referencję do funkcji, więc nic w tym przepływie nie wymaga funkcji o nazwie globalnej.

Przy włączonym partial_load zdarzenie viewer_initialized jest odraczane do momentu wczytania pozostałych klatek. Wcześniejsze zdarzenie partially_initialized przydaje się do interfejsu postępu, ale w chwili jego wystąpienia VIEWER-em nadal nie można sterować.

API występuje tylko w tych wersjach VIEWER-a, które je zawierają. W wersji My360 viewer_api_init nigdy nie zostanie wywołane — porównanie funkcji znajdziesz na stronie Licencjonowanie.

Różnice względem klasycznego bundle'a

	`orbitvu.js`	`orbitvu.esm.js`
Ładowanie	`<script src="…/orbitvu.js">`	`import`
Punkt wejścia	`inject_orbitvu(id, viewer_folder, '', params)`	`mount_viewer(id, params)`
Arkusz stylów	ładowany z folderu VIEWER-a podanego w argumencie	importujesz lub linkujesz `viewer5.css` albo ustawiasz `viewer_base`
Wartość zwracana	brak	instancja VIEWER-a

inject_orbitvu nie jest częścią bundle'a ES module — przenosząc osadzenie na import, zastąp je funkcją mount_viewer, która nie przyjmuje argumentu z folderem VIEWER-a, a wszystko pozostałe pobiera z tego samego obiektu parametrów.