ORBITVU VIEWERをESモジュールとして使用する

ORBITVU VIEWERには、クラシック版のスクリプトを読み込む代わりに、バンドラーやscriptタグ（type="module"）からインポートできるESモジュールバンドル（orbitvu.esm.js）が含まれています。

VIEWER 3.10.19以降、すべてのORBITVU VIEWERパッケージには、クラシックなバンドルとは別にもう1つのバンドルが含まれています。

orbitvu12/
  orbitvu.js        # クラシックバンドル — <script>タグで読み込みます
  orbitvu.esm.js    # ESモジュールバンドル — importで読み込みます
  viewer5.css       # スタイルシート — ESモジュールを利用する場合は別途読み込む必要があります
  version.xml
  LICENSE.txt

両方のバンドルは同じソースからビルドされており、見た目はまったく同じです。違いはページからの読み込み方法です。orbitvu.jsは呼び出す前に<script>タグで読み込む必要がありますが、orbitvu.esm.jsはimportで読み込みます — サイトがVite、webpack、Rollup、Next.js、その他のバンドラーで構築されている場合はこちらが適しています。

ESモジュールバンドルは、ダウンロード可能なVIEWERパッケージの一部であり、自社サーバー上で360°プレゼンテーションをホスティングで扱われているのと同じorbitvu12/フォルダーに含まれています。ORBITVU SUNでホストされているプレゼンテーションは、引き続き生成された埋め込みコードを使用でき、変更の必要はありません。

ESモジュールバンドルには、それ自体のスタイルは含まれていません。 inject_orbitvuに渡したVIEWERフォルダーから自動的にviewer5.cssを読み込むクラシックバンドルとは異なり、orbitvu.esm.jsにはフォルダー引数がなく、スタイルシートも自動では追加されません。viewer5.cssを自分で読み込む必要があります。読み込まないと、プレゼンテーションはスタイルが適用されない状態で表示されます。

mount_viewer

このモジュールがエクスポートする関数は1つです。スタイルシートも一緒にインポートしてください — viewer5.cssはバンドルに含まれていないため、インポートしないとプレゼンテーションはスタイルが適用されない状態で表示されます。

import { mount_viewer } from './orbitvu12/orbitvu.esm.js';
import './orbitvu12/viewer5.css';   // 必須 — 以下を参照

const viewer = mount_viewer(containerId, params);

mount_viewerは、指定したidを持つ要素にビューアをマウントし、そのビューアのインスタンスを返します。paramsは、クラシックバンドルが受け付けるものと同じVIEWERパラメータのオブジェクトで、widthとheightも含め、他の場所と同じ値（'auto'、数値、または単位付きの値）を指定できます。

以下の2点に注意してください。

コンテナ要素はあらかじめ存在している必要があります。 mount_viewerはidによってその要素を検索して中身を埋め込みますが、要素自体を作成することはありません。
モジュールをインポートするだけでは何も開始されません。 そのため、サーバーサイドレンダリングのビルドでも安全にインポートできます。マウントには実際のDOMが必要なので、mount_viewerはブラウザ上でのみ呼び出してください。

ビューアが不要になったとき — ReactのuseEffectのクリーンアップ内や、ルーターの遷移時など — は、返されたインスタンスに対してdestroy()を呼び出してください。

viewer.destroy();

スタイルシートの読み込み

viewer5.cssはバンドルに組み込まれておらず別ファイルになっています。これは、挿入された<style>要素によって厳格なContent-Security-Policyの設定が壊れることのないようにするためです。そのため、orbitvu.esm.jsをインポートしてもスタイルは一切読み込まれず、スタイルを提供するには次の3つの方法があります。

バンドルと一緒にインポートする — 推奨される方法で、最初にスタイルが適用されない状態が発生しない唯一の方法です。
```
import { mount_viewer } from '../vendor/orbitvu12/orbitvu.esm.js';
import '../vendor/orbitvu12/viewer5.css';
```

ホストページからリンクする：

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

viewer_baseを渡し、マウント時にVIEWER自身に<link>を追加させる：
```
mount_viewer('presentation1-container', {
    viewer_base: 'https://yourdomain.com/orbitvu12/',
    // …
});
```
viewer_baseが行うのはスタイルシートの読み込みだけです。上記のいずれかの方法ですでにスタイルシートを提供している場合、このパラメータはまったく必要ありません。

基本的な例

index.html

<!DOCTYPE html>
<html lang="ja">
    <head>
        <meta charset="UTF-8" />
        <title>Orbitvu プレゼンテーション</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>

バンドラーを使う場合

orbitvu12/フォルダーをプロジェクトにコピーする（または自社の静的ホストから配信する）ことで、他のモジュールと同じようにバンドルをインポートでき、VIEWERを自社のアセットパイプラインに組み込むことができます。

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'
    });
}

APIの取得

mount_viewerはビューアのインスタンスをすぐに返しますが、VIEWER APIオブジェクトはプレゼンテーションの設定ファイルが読み込まれた後に作成されるため、返されたインスタンスから直接読み取ることはできません。代わりにviewer_api_initを渡し、関数そのものを指定してください。文字列で名前を指定するコールバックは、ページのグローバルスコープ上で検索されるため、モジュール内で定義された関数には到達できません。

viewer_api_initは最初のフレームがリクエストされる前の早い段階で発火します。この時点でAPIオブジェクトは完成していますが、ビューアはまだ操作可能な状態ではありません — フレームが読み込まれるまで、回転・ズーム・パンは何も行いません。そのため、viewer_api_initはコールバックの登録に使用し、実際にビューアを操作する際は、プレゼンテーションの準備が整った時点で同じAPIオブジェクトを渡してくれる**viewer_initialized**イベントを使用してください。

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 });   // ビューアはすでに読み込まれているので、ここで呼び出しても安全
}

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)は関数への参照も受け付けるため、このフローにはグローバルに名前を付けた関数はまったく必要ありません。

partial_loadが有効な場合、viewer_initializedは残りのフレームが届くまで発火が遅延されます。それより前に発火するpartially_initializedイベントは進捗UIに便利ですが、その時点ではまだビューアを操作することはできません。

このAPIは、APIを含むVIEWERのエディションでのみ利用可能です。My360エディションではviewer_api_initは一切呼び出されません — 機能比較についてはライセンスを参照してください。

クラシックバンドルとの違い

	`orbitvu.js`	`orbitvu.esm.js`
読み込み方法	`<script src="…/orbitvu.js">`	`import`
エントリーポイント	`inject_orbitvu(id, viewer_folder, '', params)`	`mount_viewer(id, params)`
スタイルシート	VIEWERフォルダーの引数から読み込まれる	`viewer5.css`をインポートまたはリンクするか、`viewer_base`を設定する
戻り値	なし	ビューアのインスタンス

inject_orbitvuはモジュールバンドルには含まれていません。埋め込みをimportに移行する際は、mount_viewerに置き換えてください。mount_viewerはVIEWERフォルダーの引数を取らず、それ以外はすべて同じparamsオブジェクトから取得します。