`<kaleidr-map>`, das Element

<kaleidr-map> bindet ein Kaleidr-Produkt deklarativ ein. Du schreibst das Element mit Attributen; es wird beim Einfügen ins Dokument eingebunden und beim Entfernen aufgeräumt. Definiert wird es von kaleidr.js, daher muss die Seite dieses Skript laden.

<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>

Das Element ist ein schlanker Wrapper: Es wandelt Attribute in Optionen um und ruft Kaleidr.mount auf sich selbst auf. Alles, was das Element kann, geht auch mit Kaleidr.mount. Umgekehrt nicht: Das Element kann kein aktives Kartenobjekt entgegennehmen und stellt kein Handle bereit.

Verwende das Element, wenn	Verwende `Kaleidr.mount`, wenn
Die Einbindung statisches HTML ist.	Du das Handle für `setCamera`, `setStyle`, `setTheme` oder `destroy` brauchst.
Ein CMS oder eine Vorlage HTML ausgibt.	Du Chat mit deiner eigenen Karte verbindest und die Option `map` benötigst.
Das Entfernen aus dem Dokument automatisch aufräumen soll.	Ein Framework das Ein- und Aushängen steuert.

Attribute

Attributnamen verwenden kebab-case, die entsprechenden Einbindungsoptionen camelCase.

Attribut	Einbindungsoption	Produkte	Erforderlich	Standard	Nach Einbindung beobachtet	Beschreibung
`product`	`product`	alle	ja	keiner	nein	`chat`, `viewer`, `editor` oder `tile`.
`publishable-key`	`publishableKey`	chat, editor, tile	ja, außer Chat auf veröffentlichter Karte	keiner	nein	Dein `kld_pk_…`-Schlüssel. Viewer nutzt ihn nicht.
`share-id`	`shareId`	viewer, chat	Viewer: ja	keiner	nein	Viewer: ID der veröffentlichten Karte. Chat ohne Schlüssel: die veröffentlichte Karte, die Chat bereitstellt.
`map-id`	`mapId`	viewer	nein	keiner	nein	Alias für `share-id`.
`style-id`	`styleId`	tile, editor	empfohlen für Tile	Standardgrundkarte der Organisation; bei Editor danach `kaleidr-morning`	nein	Grundkartenstil-ID oder Stil-URL.
`map-target`	`mapTarget`	chat	nein	keiner	nein	CSS-Selektor für ein Viewer- oder Tile-`<kaleidr-map>`-Element, das der Assistent steuert.
`contained`	`contained`	chat	nein	aus	nein	Platziert das Panel im Element, das positioniert und dimensioniert sein muss.
`lang`	`lang`	chat	nein	Wert von `<html lang>`, sofern gültiges Sprachkennzeichen, sonst Englisch	nein	Sprache der Antworten als BCP-47-Kennzeichen wie `en`, `ko` oder `pt-BR`. Siehe Chat-Sprache.
`chat-title`	`title`	chat	nein	eigener Paneltitel	nein	Titel der Kopfzeile. Verwende `chat-title`, nicht `title`: HTML-`title` zeigt einen Tooltip beim Überfahren.
`placeholder`	`placeholder`	chat	nein	eigener Platzhaltertext des Panels	nein	Platzhalter im Eingabefeld.
`layout`	`layout`	viewer	nein	`map`	nein	`bar` bindet die Chatleiste ein, die auch `chat-title`, `placeholder`, `theme` und `lang` liest, mit eigenen Standardwerten: siehe die Viewer-Optionen. `locator` und `listings` zeigen die Karte neben einer Liste einer Sammlung aus der Ortsbibliothek: siehe Orts-Layouts. `guide` öffnet den Chat neben einer Karte mit Locations: siehe Guide-Layout. `live` zeigt Fahrzeuge und die heutigen Haltestellen: siehe Live-Layout.
`collection`	`collection`	viewer Filialfinder, Angebotsliste, Guide und Live	nein	die erste Sammlung vom Typ des Layouts, die die Karte zeichnet	nein	Die ID der Sammlung, die aufgelistet wird; bei `live` die der Sammlung vom Typ Fahrzeuge.
`stops`	`stops`	viewer Live	nein	die erste Sammlung vom Typ Haltestellen, die die Karte zeichnet	nein	Die ID der Sammlung vom Typ Haltestellen.
`filters`	`filters`	viewer Filialfinder und Angebotsliste	nein	alle Filter der Sammlung	nein	Die angezeigten Besucherfilter, getrennt durch `\|`: `search`, `category`, `price`, `beds`, `baths`, `open_now`.
`card`	`card`	viewer	nein	`auto`	nein	`compact`-Ortskarten zeigen nur Titel, Untertitel und Aktionen.
`prompt`	`prompt`	viewer	nein	keiner	nein	Eine Frage, die der Kaleidr AI der Karte beim Öffnen der Karte gestellt wird; bei einer Chatleiste der vorausgefüllte Text des Felds.
`prompt-param`	`promptParam`	viewer	nein	keiner	nein	Liest `prompt` aus diesem Abfrageparameter der Seiten-URL, wenn der Besucher von einer Seite desselben Ursprungs kam.
`prompts`	`prompts`	Viewer-Chatleiste	nein	keiner	nein	Beispielfragen, getrennt durch `\|`.
`accent`	`accent`	Viewer-Chatleiste	nein	`#2da84a`	nein	Eine CSS-Farbe.
`results-url`	`resultsUrl`	Viewer-Chatleiste	nein	keiner	nein	Leitet Besucher mit `?q=<question>` auf diese Seite.
`center`	`center`	viewer, tile, editor	nein	Produktstandard	ja	`"longitude,latitude"`, etwa `"-0.1276,51.5072"`.
`zoom`	`zoom`	viewer, tile, editor	nein	Produktstandard	ja	Zahl. Viewer und Tile nutzen sie beim Einbinden nur zusammen mit `center`.
`pitch`	`pitch`	viewer, tile, editor	nein	Produktstandard	ja	Neigung in Grad.
`bearing`	`bearing`	viewer, tile, editor	nein	Produktstandard	ja	Drehung in Grad.
`theme`	`theme`	chat, editor	nein	keiner	ja (wirkt nur bei Chat)	JSON-Zeichenfolge. Chat: CSS-Custom-Properties. Editor: 17 Theme-Schlüssel.
`flag`	`enabled`	alle	nein	keiner	nein	Elementspezifische Aktivierungssperre.
`base`	`base`	alle	nein	`https://cdn.kaleidr.com`	nein	Ursprung zum Laden der Bundles. Zugelassen sind nur die Kaleidr-CDN (`https://cdn.kaleidr.com`), der Ursprung von `kaleidr.js` oder der Seitenursprung. Andere Werte werden mit Warnung ignoriert. Siehe Base-Überschreibung.
`viewer-base`	`viewerBase`	viewer, tile	nein	`https://map-embed.kaleidr.com`	nein	Ursprung des iframes.
`api-base`	`apiBase`	chat, editor, tile	nein	`https://api.kaleidr.com/inference-api`	nein	Ziel für Sitzungsaustausch und Produktanfragen. Muss `/inference-api` enthalten.
`tile-base`	`tileBase`	editor	nein	`https://tile.kaleidr.com`	nein	Host zur Auflösung der Stil-IDs.

api-key ist ein veralteter Alias von publishable-key. Die vier …-base-Attribute dienen Tests gegen andere Deployments und werden in Produktion nicht benötigt.

Boolesche Attribute

flag und contained werden als Wahrheitswerte gelesen:

Schreibweise	Gelesen als
`contained` (ohne Wert), `contained=""`	wahr
`"true"`, `"1"`, `"yes"`, `"on"`	wahr
`"false"`, `"0"`, `"no"`, `"off"`	falsch
Attribut fehlt	nicht gesetzt
jeder andere Wert	ignoriert, mit Konsolenwarnung

Bei den Wörtern spielen Großschreibung und umgebende Leerzeichen keine Rolle. Deshalb deaktiviert auch flag="False" das Element. Ein Attribut ohne Wert ist wahr; eine Vorlage mit flag="" aktiviert das Element also. Verwende ausdrücklich false.

Numerische und Kameraattribute

zoom, pitch und bearing werden als Zahlen interpretiert. center besteht aus zwei kommaseparierten Zahlen, zuerst Längengrad. Unlesbare Werte werden ohne Meldung ignoriert und durch den Produktstandard ersetzt.

Attribute nach dem Einbinden

Das Element liest seine Attribute einmal beim Einfügen ins Dokument. Danach werden nur fünf beobachtet:

Geändertes Attribut	viewer	tile	editor	chat
`center`, `zoom`, `pitch`, `bearing`	Die Karte springt zur neuen Kamera.	Die Karte springt zur neuen Kamera.	Die Karte springt zur neuen Kamera.	Konsolenwarnung, sonst nichts.
`theme`	Warnung.	Warnung.	Warnung. Editor liest das Theme nur beim Einbinden.	Das Panel wird neu gestaltet.
Jedes andere Attribut	Nichts.	Nichts.	Nichts.	Nichts.

Kameraänderungen durch Attribute sind nie animiert. Für Animationen verwende Kaleidr.mount und rufe handle.setCamera({ …, duration: 800 }) auf.

Ändert sich ein Kameraattribut, übermittelt das Element sämtliche aktuellen Kameraattribute. Wenn du nur zoom an einem Element mit center änderst, wird auch der Mittelpunkt erneut gesetzt.

Um share-id, style-id, publishable-key, product, flag, contained, lang, chat-title oder placeholder zu ändern, ersetze das Element: Entferne es und füge ein neues mit den geänderten Attributen ein. Bei Tile kann handle.setStyle den Stil ohne erneute Einbindung wechseln, aber nur bei Einbindung mit 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);

Lebenszyklus

Ereignis	Verhalten des Elements
Wird ins Dokument eingefügt	Liest Attribute und bindet sich ein. Bei Chat, Editor und Tile beginnt ein Sitzungsaustausch.
Ist vor dem Laden von `kaleidr.js` bereits im Dokument	Wartet auf das Skript und bindet sich anschließend ein.
Wird aus dem Dokument entfernt	Zerstört die Einbindung, entfernt ihre Elemente und stoppt Sitzungserneuerungen.
Wird erneut eingefügt	Liest Attribute neu und bindet sich mit neuem Sitzungsaustausch ein.
Wird zu anderem Elternelement verschoben	Wird entfernt und neu eingefügt, also zerstört und erneut eingebunden.
`product` fehlt oder ist kein zulässiger Wert	Protokolliert `[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"` und bindet nicht ein. Späteres Setzen von `product` bewirkt nichts.

Die Konsequenzen:

Setze Attribute vor dem Einfügen. Wenn du das Element in JavaScript erzeugst, setze alle Attribute und füge es danach ein. Andernfalls bindet es sich sofort mit den bis dahin vorhandenen Werten ein.

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

Erneutes Einbinden kostet. Ein Tile-Element zählt dabei einen neuen Kartenaufruf. Editor verliert Bearbeitungen und Chat beginnt eine neue Unterhaltung. Code, der DOM-Knoten neu erstellt oder umsortiert, etwa Listen in Frameworks, kann das unbemerkt auslösen. Siehe Framework-Integration.
Ausgeblendete Elemente binden sich trotzdem ein. display:none verzögert nichts; Tile startet auch in geschlossenem Tab eine Sitzung.
Kinder bleiben sichtbar, bis eine Karte sie ersetzt. Inhalt des Elements wird zunächst dargestellt. Viewer und Tile ersetzen ihn nach dem Laden durch den iframe, sodass er als Ladeplatzhalter dient und bei fehlgeschlagener oder durch die Aktivierungssperre zurückgehaltener Einbindung als Fallback bleibt. Chat und Editor entfernen Kinder nicht. Lass das Element leer, wenn du diesen Effekt nicht willst.

Größe

<kaleidr-map> ist standardmäßig display:block, sodass height wirkt:

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

Drei wichtige Details:

Deine eigene display-Einstellung hat Vorrang. Inline-Styles, Stylesheet-Regeln und das hidden-Attribut überschreiben den Standard. Bei display:inline wirkt height nicht.
Keine Freigabe in der Content Security Policy nötig. Der Standard wird weder per <style>-Tag noch per style-Attribut gesetzt, also funktioniert er auch ohne 'unsafe-inline'.
Safari vor 16.4 übernimmt den Standard nicht. Das Element bleibt inline und ignoriert width und height. Deshalb enthalten die Beispiele display:block im style-Attribut. Das schadet anderen Browsern nicht und ermöglicht in alten Safari-Versionen die Größe.

Deshalb verwenden die Beispiele:

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

oder einmal für die ganze Website:

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

Produkt	Größenverhalten
viewer, tile	Der iframe ist 100 % so breit wie das Element. Seine Höhe beträgt 100 %, falls das Element beim Einbinden eine Höhe hat, andernfalls feste 500 Pixel. Die Einbindung setzt `position:relative` (falls keine Inline-Position vorhanden) und `overflow:hidden`.
editor	Der Editor füllt 100 % von Breite und Höhe des Elements. Ohne Höhe ist nichts sichtbar.
chat	Ohne `contained` ist das Panel als Fenster oben links im Viewport fixiert; die Elementgröße spielt keine Rolle. Mit `contained` befindet es sich im Element, das `position:relative` oder eine andere Positionierung sowie eine Größe benötigt.

Die 500-Pixel-Alternative wird einmal beim Einbinden entschieden. Fehlt dem Element dann eine Höhe, bleibt der iframe 500 Pixel hoch, auch wenn später eine Höhe festgelegt wird.

Wenn deine Content Security Policy Inline-style-Attribute verbietet, lege die Größe über ein Stylesheet fest. Der Blockstandard des Elements ist davon nicht betroffen.

Handle-Matrix

Das Element bietet kein Handle. Um diese Methoden aufzurufen, binde mit Kaleidr.mount ein. Der Aufruf gibt ein Handle zurück.

Methode	chat	viewer	editor	tile
`destroy()`	ja	ja	ja	ja
`setCamera(camera)`	nicht unterstützt	ja	ja	ja
`setTheme(theme)`	ja	nicht unterstützt	nicht unterstützt	nicht unterstützt
`setStyle(style)`	nicht unterstützt	nicht unterstützt	nicht unterstützt	ja
`send(text)`	nicht unterstützt	ja	nicht unterstützt	nicht unterstützt
`setFilters(filters)`	nicht unterstützt	ja	nicht unterstützt	nicht unterstützt
`showVehiclesLayer(layer)`	nicht unterstützt	ja	nicht unterstützt	nicht unterstützt
`clearVehiclesLayer()`	nicht unterstützt	ja	nicht unterstützt	nicht unterstützt

Jedes Handle verfügt über alle diese Methoden. „Nicht unterstützt“ bedeutet, dass der Aufruf nichts tut und eine Konsolenwarnung protokolliert, aber keine Ausnahme wirft. Das gehört zum Vertrag /embed/v1.

Je Produkt:

chat: setTheme gestaltet das Panel um. setCamera ist nicht unterstützt, weil Chat keine eigene Karte besitzt. Der Assistent bewegt beim Antworten die verbundene Karte; dein Code bewegt sie über die API der Kartenbibliothek.
viewer: setCamera bewegt die veröffentlichte Karte. setFilters setzt die Besucherfilter eines Orts-Layouts. showVehiclesLayer zeichnet eigene Fahrzeuge auf die Karte, und clearVehiclesLayer entfernt sie: siehe die Fahrzeugebene.
editor: setCamera bewegt die Editorkarte. Theme und Grundkarte sind beim Einbinden festgelegt.
tile: setCamera bewegt die Karte und setStyle wechselt die Grundkarte direkt.

setCamera akzeptiert { center, zoom, pitch, bearing, duration }. Alle Felder sind optional, center ist [longitude, latitude], und duration wird in Millisekunden angegeben. Siehe kaleidr.js.

Chat und `map-target`

Chat kann zwei Kartentypen steuern:

Deine eigene Karte (Mapbox GL JS, MapLibre GL JS, Google Maps oder Leaflet). Ein Kartenobjekt passt nicht in ein Attribut. Verwende Kaleidr.mount mit der Option map. Siehe Chat-Referenz.

Ein Kaleidr-Viewer- oder Tile-Element auf derselben Seite. Verweise mit einem CSS-Selektor in map-target darauf:

<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>

Die Reihenfolge der beiden Elemente ist unerheblich. Chat sucht sein Ziel erst bei Bedarf.

Ohne map und map-target ist Chat ein Panel ohne Karte.

Wrapper und CSS des Chat-Elements legen das Panel über die Karte. Jede Deklaration wird unter Design und Anordnung erläutert. Chat auf veröffentlichten Karten findest du unter Chat auf veröffentlichter Karte.

Konsolenmeldungen

Nachricht	Bedeutung
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	`product` fehlt oder ist falsch geschrieben. Keine Einbindung.
`[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. Use <attribute>="true" / "false" (or omit it).`	`flag` oder `contained` besitzt einen nicht akzeptierten Wert. Die Meldung nennt das Attribut: `flag="…"` oder `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` nennt einen nicht erlaubten Ursprung. Das Produkt lädt trotzdem vom Standard-CDN.
[kaleidr] embed is disabled — this mount passed `enabled: false` (or `flag="false"`). …	`flag` hält das Element zurück. Ersetze es ohne die Sperre, um einzubinden.
`[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. …`	Ein Kameraattribut eines Chat-Elements wurde geändert.
`[kaleidr] setTheme() is not supported on product "<product>" — the call is a no-op. …`	`theme` wurde auf Viewer, Tile oder Editor geändert.

Einbindungsfehler werden als [kaleidr:<product>] … protokolliert und in kaleidr.js aufgelistet.

Nicht verfügbar

Ereignisse. Das Element sendet keine DOM-Events.
Eigenschaften oder Methoden. Es hat kein setCamera, keine handle-Eigenschaft und kein ready-Promise.
Erneutes Lesen von Attributen. Abgesehen von den fünf überwachten werden Änderungen nach dem Einbinden ignoriert.

Attribute​

Boolesche Attribute​

Numerische und Kameraattribute​

Attribute nach dem Einbinden​

Lebenszyklus​

Größe​

Handle-Matrix​

Chat und map-target​

Konsolenmeldungen​

Nicht verfügbar​

Verwandte Themen​