API Reference
Concepts and usage patterns for the MaplatUi API. This page focuses on
release-independent explanatory material (ADR-0012). For the complete
and up-to-date API signature list, see docs/api/
in the repository.
MaplatUi is the main class for embedding Maplat into a web application. Its lifecycle has three phases:
-
Initialization —
MaplatUi.createObject(option)returns a Promise that resolves when the map data is loaded and the transform is ready. This is the recommended way to create an instance. -
Running — the instance is interactive: the user can switch maps, toggle
overlay, view POIs, etc. State changes can be reflected to the URL via
updateUrl(). -
Destruction —
remove()destroys the application and releases resources (event listeners, DOM elements, tile caches).
Why a Promise? Maplat must load map definition JSON, compute (or load pre-computed) TIN transforms, and initialize the OpenLayers map before it is ready. The Promise resolves only after all of this is complete.
The option object passed to createObject or the constructor has several
categories of properties:
| Category | Key properties | Purpose |
|---|---|---|
| App identity | appid |
Identifies which app JSON to load |
| Map source | (defined in the app JSON, not the option) | Which maps, base layers, overlays to show |
| UI behavior |
overlay, enableHideMarker, enableMarkerList, enableBorder, enableShare
|
Toggle UI features |
| URL state | stateUrl |
Reflect map state (center, zoom, selected map) to the URL |
| PWA |
pwaManifest, pwaWorker
|
Progressive Web App configuration |
| External tokens | mapboxToken |
Access tokens for third-party tile services |
The option object controls runtime behavior. The map and app data (which maps, POIs, styles) are defined in the app JSON file, not in the option. See Concepts for data format details.
For a quick embed without a bundler, load OpenLayers and Maplat UI from a CDN. You must load OpenLayers before Maplat UI.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10/ol.min.css">
<script src="https://cdn.jsdelivr.net/npm/ol@10/dist/ol.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@maplat/ui@0.12.2/dist/maplat_ui.css">
<script src="https://cdn.jsdelivr.net/npm/@maplat/ui@0.12.2/dist/maplat_ui.umd.js"></script>
<div id="map_div"></div>
<script>
MaplatUi.createObject({ appid: "myApp" }).then(function(app) {
console.log("Maplat initialized");
});
</script>For a modern bundler-based project, import MaplatUi as an ES module.
import { MaplatUi } from '@maplat/ui';
import '@maplat/ui/dist/maplat_ui.css';
MaplatUi.createObject({ appid: 'myApp' }).then(app => {
// Application initialized
});Peer dependency: ol (OpenLayers) v9 or v10 must be installed separately.
When integrating Maplat into a framework (React, Vue, etc.), manage the lifecycle in the component's mount/unmount hooks:
// Pseudocode
onMount: MaplatUi.createObject(option).then(app => { this.app = app; })
onUnmount: this.app.remove();Do not create multiple MaplatUi instances on the same DOM element. Destroy the old instance before creating a new one.
The complete API signature list (static methods, constructor, instance methods,
and the full MaplatAppOption property table) is maintained in
docs/api/ in the repository. This Wiki page
intentionally does not duplicate the signatures to avoid divergence from
the source of truth.
See:
-
docs/api/— authoritative API signatures - README §API Documentation — overview and quick reference
- 🇬🇧 English (Home)
- 🇯🇵 日本語 (Home.ja)
English
日本語
- 📄 README / README.ja
- 🗺️ Ecosystem Map（現在外部非公開）
- 🌐 Product site / 製品サイト
- 🏢 Nayuta, Inc. / コーポレートサイト