Data Attributes

`data-*` 属性完全リファレンス

HTML の <div class="geolonia"> に置ける全 data-* 属性。parse-atts.ts のデフォルト値 → container.dataset で上書き、を経て EmbedAttributes (src/types.ts:3-34) として GeoloniaMap に渡る。

各行に「読み取り箇所」と「反映箇所」を併記。新規 attribute を追加する場合は EmbedAttributes 型 / parse-atts.ts デフォルト / 使用箇所の 3 箇所を更新する (現状の慣習)。

マージ順序

parse-atts.ts:33-66:

parse-atts 内のデフォルト値オブジェクト
...container.dataset でスプレッド → HTML の data-* で上書き
戻り値が EmbedAttributes に

注: params.interactive (new GeoloniaMap(params).interactive) のみは parse-atts のデフォルト計算時に参照される (parse-atts.ts:45-46 で gestureHandling と navigationControl のデフォルトを反転する)。それ以外の params 値は getOptions (util.ts:309) で最後に Object.assign される。

1. 地図状態

HTML 属性	atts キー	型	デフォルト	解釈 / 反映箇所
`data-lat`	`lat`	`string \| number`	`0`	`getOptions` で `parseFloat` → `center[1]` (`util.ts:289`)
`data-lng`	`lng`	`string \| number`	`0`	`getOptions` で `parseFloat` → `center[0]` (`util.ts:289`)
`data-zoom`	`zoom`	`string \| number`	`0`	`parseFloat` → `MapOptions.zoom` (`util.ts:292`)
`data-bearing`	`bearing`	`string \| number`	`0`	`parseFloat` → `MapOptions.bearing` (`util.ts:290`)
`data-pitch`	`pitch`	`string \| number`	`0`	`parseFloat` → `MapOptions.pitch` (`util.ts:291`)
`data-hash`	`hash`	`string`	`'off'`	`hash === 'on'` → `MapOptions.hash = true` (`util.ts:293`)
`data-min-zoom`	`minZoom`	`string \| number`	`''`	`getOptions` で `Number(atts.minZoom) === 0 \|\| Number(atts.minZoom)` (= 数値かつ NaN でない) ならセット (`util.ts:298-303`)
`data-max-zoom`	`maxZoom`	`string \| number`	`20`	`Number(atts.maxZoom)` が truthy ならセット (`util.ts:305-307`)

注: '0' 文字列は parseFloat('0') === 0 で許容。minZoom の判定が冗長な OR になっているのは、Number('') === 0 を弾きつつ Number('0') === 0 は通す意図 (Suspicious-Logic 参照)。

2. スタイル

HTML 属性	atts キー	型	デフォルト	解釈
`data-style`	`style`	`string`	`'geolonia/basic-v2'` (parse-atts), さらに `getStyle` で URL 解決	`keyring.isGeoloniaStyleCheck(style)` で内部 / 外部判定。詳細は `Module-Util` 参照
`data-lang`	`lang`	`string`	`getLang()` (navigator 由来。`'ja'` または `'en'`)	`getStyle` で URL の言語サフィックスに使う

data-lang の値解釈 (parse-atts.ts:16-25):

'auto' → getLang() 実行
'ja' → 'ja' (そのまま)
それ以外 ('auto' でも 'ja' でもない場合の else if 分岐) → 'en'
属性なし → getLang() 実行 (= 自動判定)

data-style の URL 解決:

空 / 未指定 → CDN デフォルト URL (https://cdn.geolonia.com/style/geolonia/basic-v2/{lang}.json)
絶対 URL (http/https) → そのまま (Mixed Content 警告あり)
相対パス (/, ./, ../) → location.href 基準で resolve
.json で終わる文字列 → 同上の resolve
それ以外 ('geolonia/basic' 等) → https://cdn.geolonia.com/style/{style}/{lang}.json

詳細は Module-Util の getStyle 節と Module-Keyring の isGeoloniaStyleCheck 節。

3. マーカー / ポップアップ

HTML 属性	atts キー	型	デフォルト	解釈
`data-marker`	`marker`	`string`	`'on'`	`'on'` のときのみ `GeoloniaMarker` を追加 (`geolonia-map.ts:254-288`)
`data-marker-color`	`markerColor`	`string`	`'#E4402F'`	`GeoloniaMarker({ color })` に渡る。`.left` を `color`、`.right` を `tinycolor(color).darken()` でカラーリング (`geolonia-marker.ts:35-38`)
`data-open-popup`	`openPopup`	`string`	`'off'`	`'on'` のときマーカーの popup を初期表示 (`geolonia-map.ts:279-281`)
`data-custom-marker`	`customMarker`	`string`	`''`	CSS selector。指定があれば `document.querySelector(...)` で要素を取得しマーカー要素として使用 (`geolonia-map.ts:258-269`)
`data-custom-marker-offset`	`customMarkerOffset`	`string`	`'0, 0'`	`'x, y'` 形式の文字列。`.split(/,/).map(n => Number(n.trim()))` でパース (`geolonia-map.ts:259-261`)

popup の HTML 内容は container.innerHTML を constructor 開始時にスナップショット (geolonia-map.ts:103)。new Popup({ offset: [0, -25] }).setHTML(content) → marker にバインド (geolonia-map.ts:256)。

data-marker="on" でも data-lat / data-lng の両方が未指定だと marker 追加しない (geolonia-map.ts:254)。

4. コントロール

data-*-control 属性は 共通フォーマット: 'on' / 'off' / 'top-right' / 'bottom-right' / 'bottom-left' / 'top-left'。parseControlOption(value) (util.ts:319-332) でパース → { enabled: boolean, position: string | undefined } を返す。enabled === true のときのみ map.addControl(control, position) を呼ぶ。

HTML 属性	atts キー	デフォルト	反映
`data-geolonia-control`	`geoloniaControl`	`'on'`	`GeoloniaControl` (`geolonia-map.ts:202-205`)。enabled に関わらず必ず追加される (`parseControlOption` の戻り値の `position` のみ参照)。`'off'` の場合は default position (`bottom-left`) になる挙動
`data-navigation-control`	`navigationControl`	`params.interactive === false ? 'off' : 'on'`	`NavigationControl` (`geolonia-map.ts:217-223`)
`data-geolocate-control`	`geolocateControl`	`'off'`	`GeolocateControl` (`geolonia-map.ts:225-231`)
`data-fullscreen-control`	`fullscreenControl`	`'off'`	`FullscreenControl` (`geolonia-map.ts:209-215`)
`data-scale-control`	`scaleControl`	`'off'`	`ScaleControl` (`geolonia-map.ts:233-237`)
`data-gesture-handling`	`gestureHandling`	`params.interactive === false ? 'off' : 'on'`	`@geolonia/mbgl-gesture-handling` 適用 (`'off'` 以外かつ `isScrollable()` 真のとき、`geolonia-map.ts:250-252`)

CustomAttributionControl (geolonia-map.ts:207) は data-* 属性で制御不可。常に bottom-right に追加される。

5. データ表示

HTML 属性	atts キー	デフォルト	解釈
`data-geojson`	`geojson`	`''`	URL または CSS selector (= インライン GeoJSON 要素の textContent をパース)。`SimpleStyle` を addTo (`geolonia-map.ts:304-325`)
`data-simple-vector`	`simpleVector`	`''`	ベクトルタイル URL / カスタムタイル ID。`parseSimpleVector` で `geolonia://tiles/custom/{id}` に展開 → `SimpleStyleVector` を addTo (`geolonia-map.ts:299-302`)
`data-cluster`	`cluster`	`'on'`	`'on'` のとき `SimpleStyle` の cluster 有効化 (`geolonia-map.ts:314`)
`data-cluster-color`	`clusterColor`	`'#ff0000'`	`SimpleStyle` のクラスタ円色 (`geolonia-map.ts:315`)

data-geojson が CSS selector か URL かは isCssSelector (geolonia-map.ts:44-60) で判定:

http://, https://, /, ./, ../ で始まる → URL
それ以外 → document.querySelector(string) で要素取得を試行 (失敗時 false)

ヒットすれば el.textContent → JSON.parse (geolonia-map.ts:307-308)。

6. API / 認証

HTML 属性	atts キー	デフォルト	解釈
`data-key`	`key`	`keyring.apiKey` (= script tag URL から抽出)	data-* で上書き可能
`data-api-url`	`apiUrl`	`https://api.geolonia.com/${keyring.stage}`	`transformRequest` で `sourcesUrl` を組み立てる際の base (`geolonia-map.ts:122`)

注: keyring.parse(container) は parse-atts 内で呼ばれる (parse-atts.ts:27) が、これは script tag を走査するメソッドであり container は参照しない (keyring.ts:54-86)。data-key 属性自体は container.dataset.key 経由で読まれる (spread 時)。

7. ライフサイクル

HTML 属性	atts キー	デフォルト	解釈
`data-lazy-loading`	`lazyLoading` (atts に含まれず、`render.ts` が直接 querySelectorAll で見る)	(該当属性無し = lazy)	`'off'` 指定で即時 render。それ以外は IntersectionObserver で可視化時 render (`render.ts:82-87`)
(constructor 引数) `interactive`	(atts に含まれず)	`true`	`parse-atts.ts:45-46` でデフォルト値計算に使用。`false` だと gestureHandling と navigationControl が `'off'` に
`data-loader`	`loader`	`'on'`	`'off'` 以外のとき loading spinner (`<div class="loading-geolonia-map">`) を表示 (`geolonia-map.ts:107-119`)。`load` イベント時に削除 (`geolonia-map.ts:242-247`)

data-lazy-loading は atts に入らない点に注意 (parse-atts.ts のデフォルト値オブジェクトには無い)。render.ts の CSS セレクタで直接判定される。

8. 3D

HTML 属性	atts キー	デフォルト	解釈
`data-3d`	`'3d'` (キー名は文字列リテラル)	`''`	`'on'` でレイヤの `metadata['visible-on-3d'] === true` を可視化 + `metadata['hide-on-3d'] === true` を非表示。`'off'` で逆 (`geolonia-map.ts:327-356`)

詳細は Hidden-Spec の 3D layer metadata 節。

9. プラグイン

HTML 属性	atts キー	デフォルト	解釈
`data-plugin`	`plugin`	`'off'`	現状は EmbedAttributes に存在するが embed コード内で参照されない (古い設計の遺物?)。プラグインは `registerPlugin()` 経由で imperative に登録

10. 隠れ属性 (parse-atts のデフォルトには無いが atts 経由で参照される)

EmbedAttributes 型の [otherKey: string]: string | number インデックスシグネチャを使い、container.dataset の任意のキーが atts に流れる。実装で読まれているのは:

atts キー	場所	用途
`simpleVector`	`geolonia-map.ts:299`	`data-simple-vector` から (キャメルケース変換)
`stage`	`geolonia-map.ts:156,171`	parse-atts:60 で `keyring.stage` から設定 (data-stage で上書きはおそらく非推奨)
`interactive`	`getOptions` 経由	`params` から渡る (構文上 data-interactive も可だが推奨されない)

11. EmbedAttributes 型 (`src/types.ts:3-34`)

export type EmbedAttributes = {
  lat: string | number;
  lng: string | number;
  zoom: string | number;
  bearing: string | number;
  pitch: string | number;
  hash: string;
  marker: string;
  markerColor: string;
  openPopup: string;
  customMarker: string;
  customMarkerOffset: string;
  gestureHandling: string;
  navigationControl: string;
  geolocateControl: string;
  fullscreenControl: string;
  scaleControl: string;
  geoloniaControl: string;
  geojson: string;
  cluster: string;
  clusterColor: string;
  style: string;
  lang: string;
  plugin: string;
  key: string;
  apiUrl: string;
  loader: string;
  minZoom: string | number;
  maxZoom: string | number;
  '3d': string;
  [otherKey: string]: string | number;
};

simpleVector が型定義に無い (現状の型 hole)。atts.simpleVector 参照は [otherKey: string] で型チェックを通している。

12. data-* 命名規約

HTML の data-foo-bar は JS で element.dataset.fooBar (キャメル化)。parse-atts のデフォルト値オブジェクトもキャメル化キーで書く (markerColor, customMarkerOffset 等)。書き直し時はこの規約を維持。

例外: data-3d は数字始まりのため dataset['3d'] (ブラケット) で参照。

Uh oh!

Data Attributes

data-* 属性 完全リファレンス

マージ順序

1. 地図状態

2. スタイル

3. マーカー / ポップアップ

4. コントロール

5. データ表示

6. API / 認証

7. ライフサイクル

8. 3D

9. プラグイン

10. 隠れ属性 (parse-atts のデフォルトには無いが atts 経由で参照される)

11. EmbedAttributes 型 (src/types.ts:3-34)

12. data-* 命名規約

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`data-*` 属性完全リファレンス

11. EmbedAttributes 型 (`src/types.ts:3-34`)