2024年12月12日木曜日

Oracle APEXのアプリケーションにDeck.glを組み込む

Oracle APEXのアプリケーションにデータ・ビジュアリゼーションのためのライブラリDeck.glを組み込む手順を確認してみました。

Deck.glはReactでの使用が想定されていますが（確認した実装例はすべてReact）、ドキュメントに以下のセクションがあり、スタンドアロンでも使用する方法は提供されています。

Using deck.gl Standalone

Getting Startedの章に含まれる上記Using deck.gl Standaloneの例を、Oracle APEXに組み込んでみます。

Oracle APEXのリージョンとしての組み込みと全画面での組み込みを実装しています。


以下より実装について紹介します。

全画面での実装はUsing deck.gl StandaloneのページのUsing the Scripting APIで紹介されている手順そのままです。

ページ・プロパティのJavaScriptのファイルURLに以下を記述します。Deck.glとMapLibre GL JSのライブラリをロードします。

https://unpkg.com/deck.gl@latest/dist.min.js
https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.js

MapLibreはAPEXのマップ・リージョンで使用していますが、APEX 24.1に含まれているMapLibreのバージョンは2.4.0です。少し古いので、新しいバージョンを読み込みます。

ページにマップ・リージョンを配置していなければ、APEXにバンドルされているMapLibreのライブラリはロードされないので、ライブラリは競合しません。

CSSのファイルURLに以下を記述します。

https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.css

JavaScriptのページ・ロード時に実行に以下を記述します。

const {DeckGL, ScatterplotLayer} = deck;
new DeckGL({
mapStyle: 'https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json',
initialViewState: {
longitude: -122.45,
latitude: 37.8,
zoom: 15
},
controller: true,
layers: [
new ScatterplotLayer({
data: [
{position: [-122.45, 37.8], color: [255, 0, 0], radius: 100}
],
getPosition: d => d.position,
getFillColor: d => d.color,
getRadius: d => d.radius
})
]
});
view raw deck-gl-full-screen.js hosted with ❤ by GitHub
以上で全画面での実装は完了です。ページを実行してみます。


ヘッダーが邪魔ですが、ヘッダーを削除したり非表示にすると、ページの移動やサインアウトができなくなります。ヘッダーが邪魔にならないよう、ヘッダーのバックグラウンド色を透明にします。

開発者ツール・バーのカスタマイズより、テーマ・ローラーを開きます。

カスタムCSSとして以下を記述します。対象のページがページ番号2なので、スコープとして.page-2を指定しています。ヘッダーのバックグラウンド色はCSS変数--ut-header-background-colorで定義されています。
.page-2 {
   --ut-header-background-color: rgba(0,0,0,0);
}
変更を保存すると、ヘッダーが透明になります。


Oracle APEXが使用しているCSS変数の一覧は、製品に含まれています。例えば、Oracle APEX 24.1では、以下のHTMLが提供されています。CDN上のファイルを参照していますが、同じものはAPEXのZIPファイルにもあります。


ただし、これも完全とは言えないようです。やはり、JavaScriptコンソールのスタイルから、対象となるCSS変数を見つけるのが確実です。


Deck.glのリージョンへの実装です。

ページ・プロパティのJavaScriptやCSSのファイルURLには、Deck.glやMapLibre GL JSのライブラリの読み込みに必要な設定を行います。これらは全画面と同じです。

Deck.glによる描画を行うリージョンを作成します。静的コンテンツのリージョンを作成し、ソースのHTMLコードとして以下を記述します。縦のサイズを640pxとしています。横幅は自動調整します。

<div id="mydeckgl" class="h640"></div>


JavaScriptのページ・ロード時に実行に以下を記述します。

const {DeckGL, ScatterplotLayer} = deck;
/*
* mydeckglが地図とDeck.glが描いたリージョンの両方を
* 小に持つリージョン。
*/
const mydeck = document.getElementById("mydeckgl");
/*
* Deck.glが描画するキャンバス要素を作成する。
*/
const canvasEl = document.createElement('canvas');
/*
* canvas要素の指定を追加している。
* controllerはtrueにしているが、リージョンとして組み込むと
* 機能しない。
*/
new DeckGL({
canvas: canvasEl,
mapStyle: 'https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json',
initialViewState: {
longitude: -122.45,
latitude: 37.8,
zoom: 15
},
controller: true,
layers: [
new ScatterplotLayer({
data: [
{position: [-122.45, 37.8], color: [255, 0, 0], radius: 100}
],
getPosition: d => d.position,
getFillColor: d => d.color,
getRadius: d => d.radius
})
]
});
/*
* MapLibreが描画した地図の要素をmydeckglの子要素に移動する。
*/
const mapEl = document.querySelector('.maplibregl-map');
mydeck.appendChild(mapEl);
/*
* Deck.glが描画したキャンバスを、リージョンの
* 左上にパディング０で配置する。
*/
canvasEl.style.top = 0;
canvasEl.style.left = 0;
mydeck.appendChild(canvasEl);
view raw deck-gl-region.js hosted with ❤ by GitHub

MapLibreが地図を描画する要素の指定方法を見つけられなかったので、地図が生成された後に要素を移動しています。また、Deck.glが描画したキャンバス要素をそのままmydeckglの子要素すると位置が若干ズレるので、topとleftに0を設定しています。

Deck.glの描画をリージョンに行うと、controllerをtrueにしていても有効になりません。そのため、リージョンは描画のみ、対話的な操作は全画面で実装するという選択になるでしょう。

今回の記事は以上になります。

今回作成したAPEXアプリケーションのエクスポートを以下に置きました。
https://github.com/ujnak/apexapps/blob/master/exports/sample-deck-gl.zip

Oracle APEXのアプリケーション作成の参考になれば幸いです。

完
投稿者 時刻:
ラベル: