Referência do Editor

product="editor" monta as ferramentas de edição de mapas da Kaleidr em sua página. O editor cria seu próprio mapa dentro do alvo de montagem e sobrepõe seus painéis. Ele é executado no documento, não em um iframe.

O editor incorporado mantém seu trabalho apenas na memória da página. Ele não salva, exporta nem publica o que foi feito, e não oferece callback de alterações. Recarregar a página ou chamar handle.destroy() descarta as edições.

Chave	Chave publicável (kld_pk_live_…). Obrigatória.
Escopo	design. As novas chaves o incluem por padrão.
Plano	Todos os planos, inclusive Free.
Renderização	Na sua página.
Persistência	Nenhuma.
Instâncias	Uma por página.
CSP	Veja a parte do Editor em Content Security Policy.

Para um passo a passo, consulte Integrar o Editor.

Recursos disponíveis

Incluído	Não incluído
Texto posicionado no mapa	Aba Dados e upload de conjuntos de dados
Imagem: imagens posicionadas no mapa	Catálogo de designs do Studio com mapas de exemplo e tipos de estilo
Marcador	Painel de IA
Popup	Biblioteca de modelos 3D
Fundo: plano de fundo atrás do mapa	Compartilhamento e publicação
Camada: rótulos do mapa base, edifícios 3D, luz e terreno	Projetos: salvar, abrir e listar mapas
Design: escolher feição do mapa base, categoria ou região e alterar sua aparência	Login
Legenda: configurações de rótulos e legenda

A coluna esquerda representa a barra de ferramentas do Editor, na ordem apresentada. Design, no editor integrado, é uma ferramenta para redefinir estilos; o catálogo de designs do Studio não está incluído.

Montagem

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-night',
  center: [-0.1276, 51.5072],
  zoom: 12,
});

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night" center="-0.1276,51.5072" zoom="12"
             style="display:block; height:640px"></kaleidr-map>

O alvo de montagem deve ter altura. O Editor ocupa 100% da largura e altura do alvo. Ele adiciona seus elementos sem remover os que já existem; portanto, use um alvo vazio.

Opções

Opção de montagem	Atributo	Tipo	Padrão	Obrigatório	Descrição
product	product	'editor'	nenhum	sim	Seleciona o Editor.
publishableKey	publishable-key	string	nenhum	sim	Chave kld_pk_… com escopo design. Uma chave de servidor kld_sk_… é recusada no navegador antes de qualquer solicitação.
styleId	style-id	string	mapa base padrão da organização ou kaleidr-morning	não	ID de estilo como kaleidr-night ou URL completa de um estilo. Veja IDs de estilo. Definido na montagem.
center	center	[longitude, latitude]; atributo "longitude,latitude"	[0, 0]	não	Centro inicial.
zoom	zoom	número	2	não	Zoom inicial. Funciona sem center.
pitch	pitch	número, graus	0	não	Inclinação inicial.
bearing	bearing	número, graus	0	não	Rotação inicial.
theme	theme	objeto ou string JSON de um objeto	nenhum	não	Até 17 chaves nomeadas. Veja Chaves de tema. Lido apenas na montagem.
apiBase	api-base	URL	https://api.kaleidr.com/inference-api	não	Endereço do envio da troca de sessão. Deve incluir /inference-api. Não é necessário em produção.
tileBase	tile-base	URL	https://tile.kaleidr.com	não	Host usado para resolver IDs de estilo. Não é necessário em produção.
base	base	URL	https://cdn.kaleidr.com	não	Origem de onde o SDK carrega editor.js. Apenas a origem é usada, e somente as indicadas em Substituição da base são aceitas.
enabled	flag	booleano	nenhum	não	Controle por montagem do mecanismo de ativação.

shareId, map, mapTarget, contained e viewerBase não afetam a montagem do Editor. Não existe opção styleUrl: informe a URL em styleId.

Mapa base

O Editor escolhe o mapa base nesta ordem:

1. styleId, quando informado.
2. O mapa base padrão da organização, caso exista.
3. kaleidr-morning.

O mapa base não pode ser alterado depois da montagem, e handle.setStyle não é suportado pelo Editor. Para alterá-lo, destrua e monte novamente, perdendo todas as edições.

Câmera

• center informa a longitude primeiro.
• Cada valor pode ser um número ou uma string numérica.
• Uma opção de montagem que não seja um número finito é ignorada, o padrão é utilizado e o console mostra, por exemplo, [kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.
• Um atributo de câmera que não seja número é descartado silenciosamente e o valor padrão é usado.

Chaves de tema

theme é um objeto cujas chaves devem estar na lista abaixo. Cada valor é uma string com um valor CSS. Chaves que não constam da lista ou valores que não sejam strings não vazias são ignorados sem mensagem: fontSizeBase: 14 não faz nada, mas fontSizeBase: '14px' funciona.

Chave	Estiliza	Exemplo
brandColor	Botões principais, anéis de foco e ferramenta ativa.	'#0b5fff'
brandColorHover	Estado hover de brandColor.	'#0847c2'
brandColorOn	Texto e ícones sobre brandColor.	'#ffffff'
textColor	Texto principal e títulos.	'#111827'
textColorMuted	Texto secundário, como legendas de imagens.	'#6b7280'
surfaceColor	Preenchimento de cartões e diálogos.	'#ffffff'
borderColor	Bordas e divisórias.	'#e5e7eb'
glassBg	Fundo dos painéis translúcidos, da barra lateral e dos painéis expansíveis. Use cor sólida para aparência plana.	'rgba(255,255,255,0.8)'
glassBlur	Propriedade backdrop-filter desses painéis.	'blur(12px)'
cardRadius	Arredondamento dos cartões e diálogos.	'12px'
buttonRadius	Arredondamento dos botões e chips.	'8px'
listRadius	Arredondamento das linhas de lista.	'6px'
fontPrimary	font-family principal.	'"Inter", system-ui, sans-serif'
fontMono	font-family monoespaçada.	'ui-monospace, monospace'
fontSizeBase	Tamanho base da fonte.	'14px'
sidebarRailWidth	Largura da barra lateral de ferramentas.	'64px'
quickActionsWidth	Largura da barra flutuante de ações rápidas.	'320px'

Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  theme: {
    brandColor: '#0b5fff',
    brandColorOn: '#ffffff',
    fontPrimary: '"Inter", system-ui, sans-serif',
    buttonRadius: '8px',
  },
});

Comportamento:

• O tema não é uma coleção arbitrária de propriedades CSS personalizadas. Uma chave como '--my-color' é ignorada.
• Os valores são aplicados ao elemento raiz do documento enquanto o Editor está montado, para que os diálogos os recebam onde forem renderizados. Ao destruir o Editor, os valores anteriores são restaurados.
• O tema é lido apenas uma vez na montagem. handle.setTheme não é suportado pelo Editor, e alterar o atributo theme depois registra um aviso sem efeito.
• Uma string theme deve conter JSON iniciado por {. Qualquer outro valor é ignorado com aviso no console.

Controlador

Kaleidr.mount retorna o controlador sincronamente. Consulte a matriz de controladores para todos os produtos.

Membro	No Editor
handle.product	'editor'
handle.setCamera(camera)	Move o mapa do Editor.
handle.setTheme(theme)	Não suportado. Registra aviso e não faz nada.
handle.setStyle(style)	Não suportado. Registra aviso e não faz nada.
handle.destroy()	Remove Editor e mapa, restaura valores do tema, interrompe renovações de sessão e descarta edições.

O controlador não tem membro map. Sua página não pode acessar o objeto do mapa interno do Editor.

setCamera(camera)

handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });

Campo	Tipo	Descrição
center	[number, number]	Longitude, latitude.
zoom	número	Nível de zoom.
pitch	número	Inclinação em graus.
bearing	número	Rotação em graus.
duration	número	Duração da animação em milissegundos. Omitido ou 0 significa movimento instantâneo.

As chamadas durante o carregamento do Editor ficam em fila e são executadas quando ele inicia.

Atributos do elemento após a montagem

Em um <kaleidr-map product="editor"> montado, alterar center, zoom, pitch ou bearing move o mapa sem animação. Alterar style-id, theme ou outro atributo não tem efeito.

Ciclo de vida

Evento	Resultado
Kaleidr.mount(...) ou conexão do elemento	A troca de sessão e a carga de editor.js acontecem em paralelo. O Editor inicia quando ambas terminam.
handle.destroy() ou remoção do elemento	O Editor e as alterações são removidos.
O elemento é movido para outro elemento pai	É destruído e montado novamente. As alterações se perdem.
Um segundo Editor é montado enquanto há outro	Não suportado. Destrua o primeiro antes.
A página é recarregada	As alterações se perdem.

O que roda na sua página

Diferentemente dos produtos em iframe, o Editor afeta a página que o incorpora:

• Carrega editor.js, um pacote de vários megabytes, de https://cdn.kaleidr.com.
• Adiciona suas folhas de estilo ao documento pelo JavaScript.
• Solicita estilo, tiles, sprites e fontes do mapa base de https://tile.kaleidr.com. Os pedidos de estilo, sprites e fontes levam sua chave publicável como parâmetro de consulta key, para que o host reconheça a página; os pedidos dos dados de tiles não levam chave. O token de sessão nunca é colocado em uma URL.
• Inicia web workers de URLs blob: para o mapa.
• Define valores de tema no elemento raiz do documento durante a montagem.

As diretivas correspondentes estão em Content Security Policy.

Mensagens no console

Mensagem	Significado
[kaleidr:editor] [editor-embed] attach() requires an { apiKey }	Nenhuma chave fornecida. Nada é renderizado.
[kaleidr:editor] kaleidr session exchange failed (<status>)	Troca de sessão recusada. O motivo aparece na resposta da aba Network. Um 403 traz o código em detail, por exemplo insufficient_scope se faltar design; um 429 traz em error.
Erro CORS em …/sdk/sessions, seguido de erro fetch [kaleidr:editor]	A chave é desconhecida ou revogada, ou a origem da página não é permitida.
[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. …	Foi passada uma chave de servidor. Nenhuma solicitação é feita.
[kaleidr:editor] ignored <field>: <value> is not a finite value — using <default> instead.	Uma opção de câmera enviada a Kaleidr.mount não era um número. Atributos do elemento nunca geram este aviso.
[kaleidr:editor] <message>	O mapa do Editor informou um problema, como falha ao carregar estilo ou tile.
[kaleidr] theme string must be JSON …; named string themes are not supported. Ignored.	theme era uma string que não contém objeto JSON.
[kaleidr] theme JSON parse failed (…); ignored.	theme continha JSON inválido.
[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op. …	setTheme foi chamado, ou theme foi alterado depois da montagem.
[kaleidr] setStyle() is not supported on product "editor" — the call is a no-op. …	setStyle foi chamado.

Não disponível

• Salvar, exportar ou publicar o trabalho realizado.
• Evento de alteração, evento de pronto ou callback de erro.
• Objeto de mapa, camadas personalizadas ou leitura do que a pessoa desenhou.
• Alterar mapa base ou tema após a montagem.
• Mais de um Editor na mesma página.

Páginas relacionadas

• Integrar o Editor
• O carregador kaleidr.js
• O elemento <kaleidr-map>
• Incorporar um mapa publicado, para mapas persistentes