<kaleidr-map> 要素

<kaleidr-map> は Kaleidr 製品を宣言的にマウントする方法です。属性を付けて要素を記述すると、ドキュメントに追加されたときに自動的にマウントされ、取り除かれると破棄されます。kaleidr.js が定義する要素なので、ページでこのスクリプトを読み込む必要があります。

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

この要素は薄いラッパーで、属性をオプションに変換して自分自身に Kaleidr.mount を呼び出します。要素でできることは Kaleidr.mount でもできますが、逆は成り立ちません。要素は実際の地図オブジェクトを受け取れず、ハンドルも返しません。

要素を使う場合	Kaleidr.mount を使う場合
埋め込みを静的な HTML で記述する。	setCamera、setStyle、setTheme、destroy を呼ぶためにハンドルが必要。
CMS やテンプレートが HTML を出力する。	自分の地図に Chat を接続するため map オプションが必要。
ドキュメントから削除すると自動で後片付けしたい。	フレームワークがマウントやアンマウントを管理する。

属性

属性名は kebab-case、対応するマウントオプションは camelCase です。

属性	マウントオプション	製品	必須	既定値	マウント後に監視	説明
product	product	すべて	はい	なし	いいえ	chat、viewer、editor、tile。
publishable-key	publishableKey	chat、editor、tile	はい。ただし公開済み地図の Chat を除く	なし	いいえ	kld_pk_… キー。Viewer は使用しません。
share-id	shareId	viewer、chat	Viewer：はい	なし	いいえ	Viewer では公開済み地図 ID。キーなしの Chat ではチャットを提供する公開済み地図。
map-id	mapId	viewer	いいえ	なし	いいえ	share-id の別名。
style-id	styleId	tile、editor	Tile では推奨	組織の既定ベースマップ。Editor ではさらに kaleidr-morning	いいえ	ベースマップのスタイル ID または URL。
map-target	mapTarget	chat	いいえ	なし	いいえ	アシスタントが操作する Viewer または Tile の <kaleidr-map> 要素を指す CSS セレクター。
contained	contained	chat	いいえ	オフ	いいえ	パネルをこの要素内に配置します。要素には位置とサイズの指定が必要です。
lang	lang	chat	いいえ	有効な <html lang> の値、なければ英語	いいえ	応答言語を指定する BCP 47 タグ（en、ko、pt-BR など）。Chat の言語を参照してください。
chat-title	title	chat	いいえ	パネル固有のタイトル	いいえ	ヘッダーのタイトル。属性は chat-title です。HTML の title 属性の title はホバー時のツールチップなので異なります。
placeholder	placeholder	chat	いいえ	パネル固有のプレースホルダー	いいえ	入力欄のプレースホルダー。
layout	layout	viewer	いいえ	map	いいえ	bar でチャットバーをマウントします。チャットバーも chat-title、placeholder、theme、lang を読み取りますが、既定値は独自です。Viewer のオプションを参照してください。locator と listings はスポットライブラリのコレクションの一覧の横に地図を表示します。スポットのレイアウトを参照してください。guide は施設の地図の横にチャットを開きます。ガイドのレイアウトを参照してください。live は車両と今日の停留所を表示します。ライブのレイアウトを参照してください。
collection	collection	viewer の店舗検索、物件一覧、ガイド、ライブ	いいえ	地図が描画する、レイアウトの種類の最初のコレクション	いいえ	一覧に表示するコレクションの ID。live では車両コレクションの ID。
stops	stops	viewer のライブ	いいえ	地図が描画する最初の停留所コレクション	いいえ	停留所コレクションの ID。
filters	filters	viewer 店舗検索と物件一覧	いいえ	コレクションのすべてのフィルター	いいえ	表示する訪問者向けフィルター。| で区切ります：search、category、price、beds、baths、open_now。
card	card	viewer	いいえ	auto	いいえ	compact のスポットカードはタイトル、サブタイトル、アクションだけを表示します。
prompt	prompt	viewer	いいえ	なし	いいえ	地図を開いたときに地図の Kaleidr AI に投げかける質問。チャットバーでは入力欄にあらかじめ入るテキスト。
prompt-param	promptParam	viewer	いいえ	なし	いいえ	訪問者が同じオリジンのページから来た場合に、ページ URL のこのクエリパラメーターから prompt を読み取ります。
prompts	prompts	viewer チャットバー	いいえ	なし	いいえ	質問例。| で区切ります。
accent	accent	viewer チャットバー	いいえ	#2da84a	いいえ	CSS カラー。
results-url	resultsUrl	viewer チャットバー	いいえ	なし	いいえ	訪問者を ?q=<question> 付きでそのページへ送ります。
center	center	viewer、tile、editor	いいえ	製品の既定値	はい	"longitude,latitude"。例："-0.1276,51.5072"。
zoom	zoom	viewer、tile、editor	いいえ	製品の既定値	はい	数値。Viewer と Tile ではマウント時に center を伴う場合のみ有効です。
pitch	pitch	viewer、tile、editor	いいえ	製品の既定値	はい	傾斜角（度）。
bearing	bearing	viewer、tile、editor	いいえ	製品の既定値	はい	回転角（度）。
theme	theme	chat、editor	いいえ	なし	はい（Chat のみ反映）	JSON 文字列。Chat では CSS カスタムプロパティ、Editor では17 個のテーマキーを使用。
flag	enabled	すべて	いいえ	なし	いいえ	要素単位の有効化ゲート。
base	base	すべて	いいえ	https://cdn.kaleidr.com	いいえ	製品バンドルの読み込み元。Kaleidr CDN（https://cdn.kaleidr.com）、kaleidr.js が読み込まれたオリジン、ページ自身のオリジンのみ許可されます。他の値は警告とともに無視されます。ベース URL の上書きを参照。
viewer-base	viewerBase	viewer、tile	いいえ	https://map-embed.kaleidr.com	いいえ	iframe の読み込み元オリジン。
api-base	apiBase	chat、editor、tile	いいえ	https://api.kaleidr.com/inference-api	いいえ	セッション交換と製品リクエストの送信先。/inference-api が必要です。
tile-base	tileBase	editor	いいえ	https://tile.kaleidr.com	いいえ	スタイル ID の解決先ホスト。

api-key は publishable-key の非推奨の別名です。4 つの …-base 属性は別のデプロイ先でのテスト用であり、本番では不要です。

真偽値属性

flag と contained は真偽値として解釈されます。

記述方法	解釈される値
contained（値なし）、contained=""	true
"true"、"1"、"yes"、"on"	true
"false"、"0"、"no"、"off"	false
属性なし	未設定
その他の値	無視し、コンソールに警告

大文字と小文字や前後の空白は区別しないため、flag="False" でも要素は無効になります。値なしの属性は true なので、テンプレートが flag="" を出すと要素が有効化されます。明示的に false と記述してください。

数値属性とカメラ属性

zoom、pitch、bearing は数値として解析されます。center はコンマ区切りの 2 数値で、経度が先です。解析できない値はメッセージなしで無視され、製品の既定値になります。

マウント後の属性

要素は属性をドキュメントに入るときに一度だけ読みます。その後に監視されるのは次の 5 つだけです。

変更した属性	viewer	tile	editor	chat
center、zoom、pitch、bearing	地図は新しいカメラに即座に移動します。	地図は新しいカメラに即座に移動します。	地図は新しいカメラに即座に移動します。	コンソール警告のみ。
theme	警告。	警告。	警告。Editor はマウント時にしかテーマを読みません。	パネルのスタイルを更新します。
その他の属性	何もしません。	何もしません。	何もしません。	何もしません。

属性変更によるカメラ移動にアニメーションは付きません。アニメーションが必要なら Kaleidr.mount でマウントして handle.setCamera({ …, duration: 800 }) を呼んでください。

カメラ属性が 1 つ変わると、要素は現在保持するすべてのカメラ属性を送信します。zoom だけを変更しても、要素に center が設定されていればその中心点が再適用されます。

share-id、style-id、publishable-key、product、flag、contained、lang、chat-title、placeholder を変更するには、要素を削除して新しい属性の要素を挿入してください。Tile の場合、handle.setStyle で再マウントなしにスタイルを切り替えられますが、Kaleidr.mount でマウントした地図に限られます。

// Show a different published map in the same place.
const old = document.querySelector('kaleidr-map');
const next = old.cloneNode(false);
next.setAttribute('share-id', 'ANOTHER_MAP_ID');
old.replaceWith(next);

ライフサイクル

イベント	要素の動作
ドキュメントに入る	属性を読み、マウントします。Chat、Editor、Tile ではセッション交換を開始します。
kaleidr.js 読み込み前からドキュメント内にある	スクリプトが読み込まれるまで何もせず、その後マウントします。
ドキュメントから外れる	マウントを破棄し、追加した内容を削除してセッション更新を停止します。
再びドキュメントに入る	属性を再読込し、新しいセッション交換で再マウントします。
別の親要素に移動する	一度外れて戻るため、破棄して再マウントします。
product がない、または 4 製品以外の値	[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile" を記録してマウントしません。後から product を指定しても効果はありません。

これにより次の点に注意が必要です。

• 挿入前に属性を設定してください。 JavaScript で要素を作る場合、すべての属性を設定してから追加します。先に追加すると、その時点の属性でマウントされます。

  const el = document.createElement('kaleidr-map');
  el.setAttribute('product', 'tile');
  el.setAttribute('publishable-key', 'kld_pk_live_…');
  el.setAttribute('style-id', 'kaleidr-night');
  el.style.cssText = 'display:block; height:480px';
  document.getElementById('slot').appendChild(el); // mounts here

• 再マウントにはコストがかかります。 Tile を再マウントすると別の地図読み込みが計上されます。Editor の編集内容は失われ、Chat は新しい会話を始めます。フレームワークのリスト再描画などで DOM ノードを作り直したり並べ替えたりすると、意図せず発生することがあります。フレームワーク統合を参照してください。

• 非表示要素もマウントされます。 display:none はマウントを遅らせません。閉じたタブ内の Tile もセッションを開始します。

• 地図に置き換わるまで子要素を表示します。 要素内の内容は表示されます。Viewer と Tile は読み込み後に iframe に置き換えるため、読み込み中のプレースホルダーや、失敗・有効化ゲートによる停止時の代替表示として使えます。Chat と Editor は子要素を削除しません。必要がなければ空にしてください。

サイズ

<kaleidr-map> は既定で display:block なので、height を設定できます。

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="height:480px"></kaleidr-map>

この既定動作についての 3 つの注意点：

• 自分で指定した display が常に優先されます。 インラインスタイル、スタイルシートの規則、hidden 属性は既定動作を上書きします。display:inline を指定すると height は適用されません。
• Content Security Policy の許可は不要です。 この既定値は <style> タグや style 属性で設定されていないので、'unsafe-inline' がなくても動作します。
• Safari 16.4 より前では既定値が適用されません。 要素はインラインのままで width と height が効きません。そのため例では display:block を style 属性に含めています。他の環境には無害で、古い Safari でのサイズ指定に必要です。

そのため、このドキュメントでは次の形式を使用します。

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

またはサイト全体で一度指定します。

kaleidr-map { display: block; height: 480px; }

製品	サイズの動作
viewer、tile	iframe は要素の幅の 100%。マウント時に高さがあれば高さも 100%、なければ固定 500 ピクセル。要素に position:relative（インライン位置指定がない場合）と overflow:hidden を設定します。
editor	エディターは要素の幅と高さの 100% を使用します。高さがない場合は何も見えません。
chat	contained がなければパネルは画面左上の固定ウィンドウで、要素のサイズには影響されません。contained があれば要素内に配置されるため position:relative（または同等の位置指定）とサイズが必要です。

500 ピクセルの代替高さはマウント時に一度だけ決まります。その時点で高さがなかった要素は、後から高さを指定しても iframe は 500 ピクセルのままです。

Content Security Policy がインラインの style 属性を禁止する場合は、スタイルシートでサイズを指定してください。要素のブロック表示の既定動作はこのポリシーの影響を受けません。

ハンドル対応表

要素からハンドルは取得できません。これらのメソッドを使うには Kaleidr.mount でマウントし、返されたハンドルを使います。

メソッド	chat	viewer	editor	tile
destroy()	はい	はい	はい	はい
setCamera(camera)	非対応	はい	はい	はい
setTheme(theme)	はい	非対応	非対応	非対応
setStyle(style)	非対応	非対応	非対応	はい
send(text)	非対応	はい	非対応	非対応
setFilters(filters)	非対応	はい	非対応	非対応
showVehiclesLayer(layer)	非対応	はい	非対応	非対応
clearVehiclesLayer()	非対応	はい	非対応	非対応

すべてのハンドルはこれらのメソッドをすべて持ちます。「非対応」のメソッドは何もせず、コンソールに警告を記録します。例外は投げません。この動作は /embed/v1 契約の一部です。

製品ごとの動作：

• chat：setTheme でパネルのスタイルを変えます。Chat 自身は地図を所有しないため setCamera は非対応です。ただし回答時にはアシスタントが接続された地図を動かします。自分のコードからは地図ライブラリの API を使用してください。
• viewer：setCamera で公開済み地図を動かします。setFilters でスポットのレイアウトの訪問者向けフィルターを設定します。showVehiclesLayer で自分の車両を地図に描画し、clearVehiclesLayer で消します。車両レイヤーを参照してください。
• editor：setCamera でエディターの地図を動かします。テーマとベースマップはマウント時に固定されます。
• tile：setCamera で地図を動かし、setStyle でベースマップをその場で切り替えます。

setCamera は { center, zoom, pitch, bearing, duration } を受け取ります。全フィールドは任意、center は [longitude, latitude]、duration はミリ秒単位です。詳しくは kaleidr.js を参照してください。

Chat と map-target

Chat は 2 種類の地図を操作できます。

• 自分の地図（Mapbox GL JS、MapLibre GL JS、Google Maps、Leaflet）。地図オブジェクトは属性で渡せないため、Kaleidr.mount に map オプションを指定します。Chat リファレンスを参照してください。

• 同じページの Kaleidr Viewer または Tile 要素。CSS セレクターを使って map-target で指します。

  <div style="position:relative">
    <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
                 style-id="kaleidr-morning"
                 style="display:block; height:480px"></kaleidr-map>
  
    <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
                 map-target="#basemap"
                 style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
  </div>

  2 要素の順序は関係ありません。Chat は必要なときに対象を検索します。

map も map-target もない場合、Chat は地図なしのパネルになります。

ラッパーと Chat 要素のスタイルが地図の上にパネルを配置します。各宣言についてはテーマとレイアウトを参照してください。公開済み地図での Chat は公開済み地図の Chatに説明があります。

コンソールメッセージ

メッセージ	意味
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	product が欠けているか誤記されています。マウントされません。
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. Use <attribute>="true" / "false" (or omit it).	flag または contained に許可外の値があります。警告には flag="…" または contained="…" が示されます。
[kaleidr] base "<value>" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.	base に許可されないオリジンが指定されました。製品は既定の CDN から読み込まれます。
[kaleidr] embed is disabled — this mount passed `enabled: false` (or `flag="false"`). …	flag によりマウントが停止しています。この値を取り除いた要素に置き換えてください。
[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. …	Chat 要素のカメラ属性が変わりました。
[kaleidr] setTheme() is not supported on product "<product>" — the call is a no-op. …	Viewer、Tile、Editor の theme 属性が変わりました。

マウント失敗は [kaleidr:<product>] … と記録されます。kaleidr.jsに一覧があります。

利用できない機能

• イベント。要素は DOM イベントを発行しません。
• プロパティやメソッド。setCamera、handle プロパティ、ready Promise はありません。
• 属性の再読込。監視対象の 5 個以外の属性はマウント後に変更しても無視されます。

関連ページ

• ローダー kaleidr.js
• フレームワーク統合
• Viewer、Tile、 Editor、Chat のリファレンス