<kaleidr-map>, l'élément

<kaleidr-map> permet de monter un produit Kaleidr de façon déclarative. Vous écrivez l'élément et ses attributs ; il se monte quand il entre dans le document et se détruit quand il en sort. Il est défini par kaleidr.js, que la page doit donc charger.

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

L'élément est une enveloppe légère : il convertit ses attributs en options et appelle Kaleidr.mount sur lui-même. Tout ce qu'il fait peut être effectué avec Kaleidr.mount, mais l'inverse est faux : il n'accepte pas d'objet carte actif et ne fournit pas le handle.

Utilisez l'élément quand	Utilisez Kaleidr.mount quand
L'intégration est du HTML statique.	Vous avez besoin du handle pour setCamera, setStyle, setTheme ou destroy.
Un CMS ou un modèle écrit le HTML.	Vous connectez Chat à votre propre carte avec l'option map.
Vous souhaitez que la suppression de l'élément déclenche son nettoyage.	Un framework gère le montage et le démontage des composants.

Attributs

Les noms d'attributs sont en kebab-case, tandis que les options de montage correspondantes sont en camelCase.

Attribut	Option de montage	Produits	Obligatoire	Défaut	Observé après montage	Description
product	product	tous	oui	aucun	non	chat, viewer, editor ou tile.
publishable-key	publishableKey	chat, editor, tile	oui, sauf Chat sur carte publiée	aucun	non	Votre clé kld_pk_…. Viewer ne l'utilise pas.
share-id	shareId	viewer, chat	Viewer : oui	aucun	non	Viewer : identifiant de carte publiée. Chat sans clé : carte publiée qui fournit le chat.
map-id	mapId	viewer	non	aucun	non	Alias de share-id.
style-id	styleId	tile, editor	recommandé sur Tile	fond de carte par défaut de l'organisation ; sur Editor, puis kaleidr-morning	non	Identifiant ou URL de style de fond de carte.
map-target	mapTarget	chat	non	aucun	non	Sélecteur CSS d'un élément Viewer ou Tile <kaleidr-map> que l'assistant pilote.
contained	contained	chat	non	désactivé	non	Ancre le panneau dans cet élément, qui doit être positionné et dimensionné.
lang	lang	chat	non	attribut <html lang> bien formé, sinon anglais	non	Langue des réponses, sous forme d'étiquette BCP 47 telle que en, ko ou pt-BR. Voir Langue du Chat.
chat-title	title	chat	non	titre propre du panneau	non	Titre de l'en-tête. L'attribut est chat-title, pas title : en HTML, title crée une infobulle au survol.
placeholder	placeholder	chat	non	texte indicatif propre du panneau	non	Texte indicatif du champ de saisie.
layout	layout	viewer	non	map	non	bar monte la barre de chat, qui lit aussi chat-title, placeholder, theme et lang, avec ses propres valeurs par défaut : voir les options du viewer. locator et listings affichent la carte à côté d'une liste d'une collection de la Bibliothèque de lieux : voir Mises en page de lieux. guide ouvre le chat à côté d'une carte d'établissements : voir Mise en page guide. live affiche les véhicules et les arrêts du jour : voir Mise en page en direct.
collection	collection	viewer localisateur, annonces, guide et en direct	non	la première collection du type de la mise en page que la carte dessine	non	L'identifiant de la collection à lister ; sur live, celui de la collection Véhicules.
stops	stops	viewer en direct	non	la première collection Arrêts que la carte dessine	non	L'identifiant de la collection Arrêts.
filters	filters	viewer localisateur et annonces	non	tous les filtres de la collection	non	Les filtres des visiteurs à afficher, séparés par | : search, category, price, beds, baths, open_now.
card	card	viewer	non	auto	non	Les fiches de lieu compact n'affichent que le titre, le sous-titre et les actions.
prompt	prompt	viewer	non	aucun	non	Question à poser à la Kaleidr AI de la carte à son ouverture ; sur une barre de chat, texte prérempli du champ.
prompt-param	promptParam	viewer	non	aucun	non	Lit prompt depuis ce paramètre de requête de l'URL de la page, lorsque le visiteur vient d'une page de même origine.
prompts	prompts	barre de chat viewer	non	aucun	non	Exemples de questions, séparés par |.
accent	accent	barre de chat viewer	non	#2da84a	non	Couleur CSS.
results-url	resultsUrl	barre de chat viewer	non	aucun	non	Envoie les visiteurs vers cette page avec ?q=<question>.
center	center	viewer, tile, editor	non	défaut du produit	oui	"longitude,latitude", par exemple "-0.1276,51.5072".
zoom	zoom	viewer, tile, editor	non	défaut du produit	oui	Nombre. Au montage, Viewer et Tile ne l'appliquent qu'avec center.
pitch	pitch	viewer, tile, editor	non	défaut du produit	oui	Inclinaison en degrés.
bearing	bearing	viewer, tile, editor	non	défaut du produit	oui	Rotation en degrés.
theme	theme	chat, editor	non	aucun	oui (agit sur Chat uniquement)	Chaîne JSON. Chat : propriétés CSS personnalisées. Editor : 17 clés de thème.
flag	enabled	tous	non	aucun	non	Commande par élément du mécanisme d'activation.
base	base	tous	non	https://cdn.kaleidr.com	non	Origine de chargement des bundles. Sont autorisées uniquement la CDN Kaleidr (https://cdn.kaleidr.com), l'origine de kaleidr.js ou celle de la page. Les autres valeurs sont ignorées avec un avertissement. Voir Remplacement de la base.
viewer-base	viewerBase	viewer, tile	non	https://map-embed.kaleidr.com	non	Origine de l'iframe.
api-base	apiBase	chat, editor, tile	non	https://api.kaleidr.com/inference-api	non	Destination des sessions et des requêtes du produit. Doit inclure /inference-api.
tile-base	tileBase	editor	non	https://tile.kaleidr.com	non	Hôte sur lequel les identifiants de style sont résolus.

api-key est un alias obsolète de publishable-key. Les quatre attributs …-base servent aux tests sur un autre déploiement et sont inutiles en production.

Attributs booléens

flag et contained sont interprétés comme des booléens :

Écriture	Valeur interprétée
contained (sans valeur), contained=""	vrai
"true", "1", "yes", "on"	vrai
"false", "0", "no", "off"	faux
attribut absent	non défini
toute autre valeur	ignorée, avec avertissement en console

La casse et les espaces entourant les mots sont ignorés : flag="False" désactive donc aussi l'élément. Puisqu'un attribut sans valeur signifie vrai, un modèle qui produit flag="" active l'élément. Écrivez explicitement false.

Attributs numériques et de caméra

zoom, pitch et bearing sont convertis en nombres. center comporte deux nombres séparés par une virgule, la longitude en premier. Une valeur non valide est ignorée sans message et remplacée par la valeur par défaut du produit.

Attributs après montage

L'élément lit ses attributs une fois, lorsqu'il entre dans le document. Par la suite, seuls cinq sont observés :

Attribut modifié	viewer	tile	editor	chat
center, zoom, pitch, bearing	La carte saute à la nouvelle caméra.	La carte saute à la nouvelle caméra.	La carte saute à la nouvelle caméra.	Avertissement ; aucun effet.
theme	Avertissement.	Avertissement.	Avertissement. Editor lit son thème uniquement au montage.	Le panneau change de style.
Tout autre attribut	Aucun effet.	Aucun effet.	Aucun effet.	Aucun effet.

Un changement de caméra via les attributs n'est jamais animé. Pour animer, montez avec Kaleidr.mount puis appelez handle.setCamera({ …, duration: 800 }).

Lorsqu'un attribut de caméra change, l'élément envoie tous les attributs de caméra qu'il possède alors. Modifier seulement zoom sur un élément ayant aussi center réapplique ce centre.

Pour modifier share-id, style-id, publishable-key, product, flag, contained, lang, chat-title ou placeholder, remplacez l'élément : retirez-le puis insérez-en un nouveau avec les nouveaux attributs. Dans Tile, handle.setStyle change le style sans remonter, mais seulement si la carte a été montée avec 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);

Cycle de vie

Événement	Comportement de l'élément
Entre dans le document	Lit ses attributs et se monte. Chat, Editor et Tile lancent un échange de session.
Est déjà dans le document avant le chargement de kaleidr.js	Attend le script, puis se monte.
Quitte le document	Détruit le montage, supprime ses ajouts et arrête le renouvellement des sessions.
Revient dans le document	Relit ses attributs et se remonte, avec un nouvel échange de session.
Change de parent	Quitte puis rejoint le document : destruction puis nouveau montage.
product est absent ou non reconnu	Affiche [kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile" sans monter. Modifier product après coup n'a aucun effet.

Conséquences :

• Définissez les attributs avant d'insérer l'élément. Si vous le créez en JavaScript, donnez-lui tous ses attributs avant de l'ajouter. Un élément ajouté trop tôt se monte avec ses valeurs du moment.

  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

• Un nouveau montage a un coût. Un élément Tile remonté compte un nouveau chargement de carte. Editor perd ses modifications et Chat commence une nouvelle conversation. Un code qui recrée ou réordonne des nœuds DOM, par exemple une liste réaffichée par un framework, peut provoquer cela sans que vous le remarquiez. Voir Intégration des frameworks.

• Un élément caché se monte quand même. display:none ne retarde rien : Tile dans un onglet fermé démarre une session.

• L'élément affiche ses enfants jusqu'à ce qu'une carte les remplace. Tout contenu intérieur s'affiche. Viewer et Tile le remplacent par l'iframe après chargement : il peut donc servir d'indicateur de chargement, ou de secours si le montage échoue ou est retenu par le mécanisme d'activation. Chat et Editor ne suppriment jamais les enfants. Laissez l'élément vide si cela n'est pas voulu.

Dimensions

<kaleidr-map> utilise display:block par défaut ; on peut donc lui appliquer height :

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

Trois points à connaître sur ce comportement :

• Votre propre display prime toujours. Un style en ligne, une règle de feuille de style et l'attribut hidden remplacent la valeur par défaut. Si votre CSS définit display:inline, height ne s'applique plus.
• Aucune règle spéciale de Content Security Policy n'est requise. La valeur par défaut n'est fournie ni par un élément <style> ni par un attribut style ; elle fonctionne donc sans 'unsafe-inline'.
• Safari avant 16.4 ne reçoit pas cette valeur par défaut. L'élément reste en ligne et ignore width et height. Les exemples conservent donc display:block dans l'attribut style : c'est sans effet négatif ailleurs et indispensable pour dimensionner l'élément dans les anciennes versions.

C'est pourquoi cette documentation utilise :

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

ou, une fois pour tout le site :

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

Produit	Comportement de dimensionnement
viewer, tile	L'iframe occupe 100 % de la largeur. Sa hauteur occupe 100 % de l'élément s'il a une hauteur au montage, sinon elle est fixée à 500 pixels. Le montage applique position:relative (sans position en ligne) et overflow:hidden à l'élément.
editor	L'éditeur occupe 100 % de la largeur et de la hauteur. Sans hauteur, rien n'est visible.
chat	Sans contained, le panneau est une fenêtre fixe en haut à gauche et la taille de l'élément n'importe pas. Avec contained, il se place dans l'élément, qui doit avoir position:relative (ou un positionnement équivalent) et des dimensions.

Le repli à 500 pixels est déterminé une fois au montage. Si l'élément n'avait pas de hauteur alors, l'iframe conserve 500 pixels, même si vous dimensionnez l'élément ensuite.

Si votre Content Security Policy interdit les attributs style en ligne, dimensionnez l'élément dans une feuille de style. Sa valeur par défaut de type bloc n'est pas affectée.

Matrice des handles

L'élément n'expose pas de handle. Pour appeler ces méthodes, montez avec Kaleidr.mount, qui en renvoie un.

Méthode	chat	viewer	editor	tile
destroy()	oui	oui	oui	oui
setCamera(camera)	non pris en charge	oui	oui	oui
setTheme(theme)	oui	non pris en charge	non pris en charge	non pris en charge
setStyle(style)	non pris en charge	non pris en charge	non pris en charge	oui
send(text)	non pris en charge	oui	non pris en charge	non pris en charge
setFilters(filters)	non pris en charge	oui	non pris en charge	non pris en charge
showVehiclesLayer(layer)	non pris en charge	oui	non pris en charge	non pris en charge
clearVehiclesLayer()	non pris en charge	oui	non pris en charge	non pris en charge

Chaque handle possède toutes ces méthodes. Une méthode « non prise en charge » ne fait rien et affiche un avertissement dans la console, sans déclencher d'exception. Ce comportement fait partie du contrat /embed/v1.

Selon le produit :

• chat : setTheme modifie le style du panneau. setCamera n'est pas pris en charge car Chat ne possède pas de carte : l'assistant déplace la carte connectée en répondant, et votre code peut la déplacer avec l'API de votre bibliothèque cartographique.
• viewer : setCamera déplace la carte publiée. setFilters définit les filtres des visiteurs d'une mise en page de lieux. showVehiclesLayer dessine vos propres véhicules sur la carte, et clearVehiclesLayer les retire : voir la couche de véhicules.
• editor : setCamera déplace la carte de l'éditeur. Le thème et le fond de carte sont fixés au montage.
• tile : setCamera déplace la carte et setStyle remplace le fond de carte sur place.

setCamera accepte { center, zoom, pitch, bearing, duration }. Tous les champs sont facultatifs, center vaut [longitude, latitude] et duration est en millisecondes. Voir kaleidr.js.

Chat et map-target

Chat peut piloter deux types de carte :

• Votre propre carte (Mapbox GL JS, MapLibre GL JS, Google Maps ou Leaflet). Un objet carte ne peut pas être écrit dans un attribut ; utilisez Kaleidr.mount avec l'option map. Voir la référence Chat.

• Un élément Viewer ou Tile Kaleidr sur la même page. Faites pointer map-target vers lui avec un sélecteur CSS :

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

  L'ordre des deux éléments n'a aucune importance. Chat recherche sa cible au moment où il en a besoin.

Sans map ni map-target, Chat n'est qu'un panneau sans carte.

L'enveloppe et les styles de l'élément Chat positionnent le panneau au-dessus de la carte. Chaque déclaration est expliquée dans Thèmes et disposition. Chat sur une carte publiée est décrit dans Chat sur une carte publiée.

Messages de console

Message	Signification
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	product est absent ou mal orthographié : l'élément ne se monte pas.
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. Use <attribute>="true" / "false" (or omit it).	flag ou contained contient une valeur non reconnue. Le message nomme l'attribut : flag="…" ou 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.	L'attribut base indique une origine interdite. Le produit se charge depuis la CDN par défaut.
[kaleidr] embed is disabled — this mount passed `enabled: false` (or `flag="false"`). …	L'élément est retenu par flag. Remplacez-le sans cette valeur pour monter.
[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. …	Un attribut de caméra d'un élément Chat a changé.
[kaleidr] setTheme() is not supported on product "<product>" — the call is a no-op. …	L'attribut theme a changé sur Viewer, Tile ou Editor.

Les erreurs de montage sont consignées comme [kaleidr:<product>] …. Elles figurent dans kaleidr.js.

Non disponible

• Événements. L'élément n'émet aucun événement DOM.
• Propriétés ou méthodes. Il n'a ni setCamera, ni propriété handle, ni promesse ready.
• Nouvelle lecture des attributs. Hormis les cinq observés, une modification après montage est ignorée.

Voir aussi

• Le chargeur kaleidr.js
• Intégration des frameworks
• Viewer, Tile, Editor et Chat