<kaleidr-map>, o elemento

<kaleidr-map> é a forma declarativa de montar um produto Kaleidr. Escreves o elemento com atributos, e ele monta-se quando entra no documento e destrói-se quando sai. É definido por kaleidr.js, pelo que a página tem de carregar esse script.

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

O elemento é um invólucro simples: converte atributos em opções e chama Kaleidr.mount sobre si próprio. Tudo o que o elemento faz também pode ser feito com Kaleidr.mount, mas o inverso não é verdade: o elemento não recebe um objeto de mapa ativo e não expõe o controlador.

Utiliza o elemento quando	Utiliza Kaleidr.mount quando
A incorporação é HTML estático.	Precisas do controlador para setCamera, setStyle, setTheme ou destroy.
Um CMS ou modelo gera o HTML.	Queres ligar Chat ao teu próprio mapa, o que exige a opção map.
Queres que a remoção do documento faça a limpeza automaticamente.	Um framework controla quando os componentes são montados e desmontados.

Atributos

Os atributos usam nomes em kebab-case. As opções de montagem correspondentes usam camelCase.

Atributo	Opção de montagem	Produtos	Obrigatório	Predefinição	Observado após montagem	Descrição
product	product	todos	sim	nenhum	não	chat, viewer, editor ou tile.
publishable-key	publishableKey	chat, editor, tile	sim, exceto Chat em mapa publicado	nenhum	não	Chave kld_pk_…. Viewer não a usa.
share-id	shareId	viewer, chat	Viewer: sim	nenhum	não	Viewer: ID do mapa publicado. Chat sem chave: mapa publicado que fornece o Chat.
map-id	mapId	viewer	não	nenhum	não	Alias de share-id.
style-id	styleId	tile, editor	recomendado em Tile	mapa de base predefinido da organização; no Editor, depois kaleidr-morning	não	ID de estilo ou URL de estilo.
map-target	mapTarget	chat	não	nenhum	não	Seletor CSS para um elemento Viewer ou Tile <kaleidr-map> que o assistente deve controlar.
contained	contained	chat	não	desativado	não	Coloca o painel dentro do elemento, que tem de ter posicionamento e dimensão.
lang	lang	chat	não	valor de <html lang> se for uma etiqueta bem formada; caso contrário inglês	não	Idioma do painel em BCP 47, como en, ko ou pt-BR. Consulta Idioma do Chat.
chat-title	title	chat	não	título próprio do painel	não	Título do cabeçalho. Usa chat-title, não title: em HTML title apresenta uma dica ao passar o rato.
placeholder	placeholder	chat	não	texto predefinido do campo de entrada	não	Texto de ajuda do campo de entrada.
layout	layout	viewer	não	map	não	bar monta a barra de chat, que também lê chat-title, placeholder, theme e lang, com valores predefinidos próprios: consulta as opções do Viewer. locator e listings mostram o mapa ao lado de uma lista de uma coleção da Biblioteca de locais: consulta Layouts de locais. guide abre o chat ao lado de um mapa de estabelecimentos: consulta Layout de guia. live mostra os veículos e as paradas de hoje: consulta Layout ao vivo.
collection	collection	localizador, anúncios, guia e ao vivo do Viewer	não	a primeira coleção do tipo do layout que o mapa desenha	não	O identificador da coleção a listar; em live, o da coleção de Veículos.
stops	stops	Viewer ao vivo	não	a primeira coleção de Paradas que o mapa desenha	não	O identificador da coleção de Paradas.
filters	filters	localizador e anúncios do Viewer	não	todos os filtros da coleção	não	Os filtros para visitantes a mostrar, separados por |: search, category, price, beds, baths, open_now.
card	card	viewer	não	auto	não	Os cartões de local compact mostram apenas o título, o subtítulo e as ações.
prompt	prompt	viewer	não	nenhum	não	Pergunta a fazer ao Kaleidr AI do mapa quando o mapa abre; numa barra de chat, o texto pré-preenchido do campo.
prompt-param	promptParam	viewer	não	nenhum	não	Lê prompt desse parâmetro de consulta do URL da página, quando o visitante veio de uma página da mesma origem.
prompts	prompts	barra de chat do Viewer	não	nenhum	não	Perguntas de exemplo, separadas por |.
accent	accent	barra de chat do Viewer	não	#2da84a	não	Uma cor CSS.
results-url	resultsUrl	barra de chat do Viewer	não	nenhum	não	Envia os visitantes para essa página com ?q=<question>.
center	center	viewer, tile, editor	não	predefinição do produto	sim	"longitude,latitude", por exemplo "-0.1276,51.5072".
zoom	zoom	viewer, tile, editor	não	predefinição do produto	sim	Número. Na montagem, Viewer e Tile só o usam com center.
pitch	pitch	viewer, tile, editor	não	predefinição do produto	sim	Inclinação em graus.
bearing	bearing	viewer, tile, editor	não	predefinição do produto	sim	Rotação em graus.
theme	theme	chat, editor	não	nenhum	sim (apenas Chat)	Cadeia JSON. Chat: propriedades CSS personalizadas. Editor: 17 chaves de tema.
flag	enabled	todos	não	nenhum	não	Controlo por elemento do mecanismo de ativação.
base	base	todos	não	https://cdn.kaleidr.com	não	Origem dos bundles. Apenas a CDN Kaleidr (https://cdn.kaleidr.com), a origem de onde foi carregado kaleidr.js ou a origem da página são aceites; os outros valores são ignorados com aviso. Consulta Substituição da base.
viewer-base	viewerBase	viewer, tile	não	https://map-embed.kaleidr.com	não	Origem do iframe.
api-base	apiBase	chat, editor, tile	não	https://api.kaleidr.com/inference-api	não	Destino da sessão e pedidos do produto. Deve incluir /inference-api.
tile-base	tileBase	editor	não	https://tile.kaleidr.com	não	Servidor onde se resolvem os IDs de estilo.

api-key é um alias obsoleto de publishable-key. Os quatro atributos …-base destinam-se a testes contra outra instalação e não são necessários em produção.

Atributos booleanos

flag e contained são interpretados como booleanos:

Escrito como	Interpretado como
contained (sem valor), contained=""	verdadeiro
"true", "1", "yes", "on"	verdadeiro
"false", "0", "no", "off"	falso
atributo ausente	não definido
qualquer outro valor	ignorado, com aviso na consola

As palavras não distinguem maiúsculas e minúsculas nem espaços adjacentes, pelo que flag="False" também desativa o elemento. Um atributo sem valor significa verdadeiro; assim, um modelo que gere flag="" ativa o elemento. Escreve false explicitamente.

Atributos numéricos e de câmara

zoom, pitch e bearing são convertidos em números. center contém dois números separados por vírgula, começando pela longitude. Um valor que não possa ser convertido é ignorado silenciosamente e aplica-se o valor predefinido do produto.

Atributos depois da montagem

O elemento lê os seus atributos uma única vez, ao entrar no documento. Depois observa apenas cinco:

Atributo alterado	viewer	tile	editor	chat
center, zoom, pitch, bearing	A câmara salta para a nova vista.	A câmara salta para a nova vista.	A câmara salta para a nova vista.	Aviso na consola; sem efeito.
theme	Aviso.	Aviso.	Aviso. O Editor só lê o tema ao montar.	O painel muda de estilo.
Qualquer outro atributo	Nada.	Nada.	Nada.	Nada.

As alterações de câmara por atributos nunca são animadas. Para animar, monta com Kaleidr.mount e chama handle.setCamera({ …, duration: 800 }).

Quando um atributo de câmara muda, o elemento envia todos os atributos de câmara que possui nesse momento. Alterar só zoom num elemento que também tem center volta a aplicar esse centro.

Para alterar share-id, style-id, publishable-key, product, flag, contained, lang, chat-title ou placeholder, substitui o elemento: remove-o e insere outro com os novos atributos. Em Tile, handle.setStyle muda o estilo sem nova montagem, mas apenas se o mapa tiver sido montado com 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);

Ciclo de vida

Evento	Ação do elemento
Entra no documento	Lê atributos e monta-se. Chat, Editor e Tile iniciam a troca de sessão.
Já está no documento antes de carregar kaleidr.js	Aguarda pelo script e monta-se depois.
Sai do documento	Destrói a montagem, remove o que acrescentou e interrompe renovações da sessão.
Entra novamente	Volta a ler atributos e monta-se, com uma nova troca de sessão.
É movido para outro pai	Sai e entra: é destruído e montado novamente.
Falta product ou não é um dos quatro valores	Regista [kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile" e não monta. Definir product mais tarde não tem efeito.

Consequências:

• Define os atributos antes de inserir o elemento. Se o criares em JavaScript, define todos os atributos e depois adiciona-o. Inserir primeiro inicia a montagem com os valores disponíveis nesse momento.

  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

• Uma nova montagem tem custo. Um elemento Tile montado novamente conta outro carregamento de mapa. O Editor perde as edições e Chat inicia outra conversa. Código que recria ou reordena nós DOM, como uma lista num framework, pode provocar isto sem aviso. Consulta Integração com frameworks.

• Um elemento escondido também se monta. display:none não adia a montagem; Tile num separador fechado inicia uma sessão.

• O elemento mostra os filhos até serem substituídos pelo mapa. Qualquer conteúdo interior fica visível. Viewer e Tile substituem-no por um iframe quando carregam, pelo que serve de indicador de carregamento e fica como alternativa se a montagem falhar ou for retida pelo mecanismo de ativação. Chat e Editor nunca removem esses filhos. Deixa vazio salvo se pretenderes esse comportamento.

Dimensões

<kaleidr-map> tem display:block por predefinição, portanto height aplica-se:

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

Três detalhes sobre esse valor:

• O teu próprio display tem prioridade. Um estilo inline, uma regra da folha de estilos ou o atributo hidden sobrepõe-se à predefinição. Se definires display:inline, height deixa de se aplicar.
• Não exige nada da Política de Segurança de Conteúdo. A predefinição não é fornecida por uma etiqueta <style> nem por atributo style, pelo que funciona sem 'unsafe-inline'.
• Safari anterior a 16.4 não recebe essa predefinição. O elemento continua inline e ignora width e height. Os exemplos incluem display:block no atributo style por esse motivo: não prejudica outros navegadores e dimensiona o elemento nos antigos.

Por isso a forma usada nesta documentação é:

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

ou, uma vez para todo o site:

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

Produto	Comportamento das dimensões
viewer, tile	O iframe ocupa 100% da largura do elemento. A altura é 100% quando há altura na montagem, ou 500 píxeis fixos. A montagem define position:relative (se não existir posição inline) e overflow:hidden no elemento.
editor	O editor ocupa 100% da largura e altura. Sem altura nada aparece.
chat	Sem contained, o painel é uma janela fixa no canto superior esquerdo, independentemente do elemento. Com contained, fica dentro do elemento, que requer position:relative (ou equivalente) e dimensões.

O valor alternativo de 500 píxeis é decidido uma única vez, na montagem. Um elemento que não tinha altura nesse momento mantém o iframe de 500 píxeis, mesmo que seja dimensionado mais tarde.

Se a Política de Segurança de Conteúdo proibir atributos style inline, define as dimensões numa folha de estilos. O valor de bloco predefinido do elemento não é afetado.

Matriz do controlador

O elemento não expõe controlador. Para chamar estes métodos, monta com Kaleidr.mount, que o devolve.

Método	chat	viewer	editor	tile
destroy()	sim	sim	sim	sim
setCamera(camera)	não suportado	sim	sim	sim
setTheme(theme)	sim	não suportado	não suportado	não suportado
setStyle(style)	não suportado	não suportado	não suportado	sim
send(text)	não suportado	sim	não suportado	não suportado
setFilters(filters)	não suportado	sim	não suportado	não suportado
showVehiclesLayer(layer)	não suportado	sim	não suportado	não suportado
clearVehiclesLayer()	não suportado	sim	não suportado	não suportado

Todos os controladores têm todos estes métodos. Um método marcado como «não suportado» não faz nada e regista um aviso na consola, sem lançar exceção. Isto integra o contrato /embed/v1.

Por produto:

• chat: setTheme altera o estilo do painel. setCamera não é suportado porque Chat não possui um mapa: o assistente move o mapa associado ao responder; o teu código move-o através da API da biblioteca de mapas.
• viewer: setCamera move o mapa publicado. setFilters define os filtros para visitantes de um layout de locais. showVehiclesLayer desenha os teus próprios veículos no mapa e clearVehiclesLayer remove-os: consulta a camada de veículos.
• editor: setCamera move o mapa do editor. O tema e o mapa de base são fixos na montagem.
• tile: setCamera move o mapa e setStyle muda o mapa de base sem montar novamente.

setCamera aceita { center, zoom, pitch, bearing, duration }. Todos os campos são opcionais, center é [longitude, latitude] e duration mede-se em milissegundos. Consulta kaleidr.js.

Chat e map-target

Chat pode controlar dois tipos de mapa:

• O teu próprio mapa (Mapbox GL JS, MapLibre GL JS, Google Maps ou Leaflet). Um objeto de mapa não pode ser passado como atributo: usa Kaleidr.mount com a opção map. Consulta a referência de Chat.

• Um elemento Viewer ou Tile de Kaleidr na mesma página. Aponta map-target para ele com um seletor 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>

  A ordem dos dois elementos não importa. Chat procura o destino quando necessita dele.

Sem map nem map-target, Chat funciona como painel sem mapa.

O invólucro e os estilos do elemento Chat colocam o painel sobre o mapa. Cada declaração é explicada em Temas e disposição. O Chat num mapa publicado é explicado em Chat num mapa publicado.

Mensagens da consola

Mensagem	Significado
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	product falta ou está mal escrito; o elemento não monta.
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. Use <attribute>="true" / "false" (or omit it).	flag ou contained tem um valor não reconhecido. A mensagem indica o atributo: 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.	O atributo base usa uma origem não admitida. O produto continua a carregar da CDN predefinida.
[kaleidr] embed is disabled — this mount passed `enabled: false` (or `flag="false"`). …	O elemento foi retido por flag. Substitui-o sem esse valor para montar.
[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. …	Um atributo de câmara foi alterado num elemento Chat.
[kaleidr] setTheme() is not supported on product "<product>" — the call is a no-op. …	theme foi alterado num elemento Viewer, Tile ou Editor.

As falhas de montagem surgem como [kaleidr:<product>] … e estão listadas em kaleidr.js.

Não disponível

• Eventos. O elemento não emite eventos DOM.
• Propriedades ou métodos. Não tem setCamera, propriedade handle ou promessa ready.
• Nova leitura de atributos. Exceto os cinco observados, as alterações após montar são ignoradas.

Relacionado

• O carregador kaleidr.js
• Integração com frameworks
• Viewer, Tile, Editor e Chat