Blocos de Mapa: Mostrar uma Localização sem Ocultar o Endereço

Um bloco de mapa ajuda um visitante a entender onde um lugar real está e a passar da leitura para a navegação. Seu conteúdo durável é o endereço verificado em HTML; o mapa visual é um auxílio opcional de orientação. A implementação padrão reserva a área do mapa, mostra um fallback estático leve e carrega um provedor interativo aprovado somente após o visitante solicitar.

National Gallery
Trafalgar Square, London WC2N 5DN, United Kingdom
Mapa não carregado. Abra a localização no seu aplicativo de mapas, ou ative Carregar mapa interativo quando precisar inspecionar as ruas ao redor.

Esta fachada renderizada é útil antes de qualquer requisição de terceiros. Ela nomeia o lugar, expõe o endereço como texto selecionável, explica o estado não carregado e fornece dois caminhos claros: abrir um mapa externo ou carregar deliberadamente o mapa incorporado.

Por que este elemento é importante

Perguntas sobre localização são práticas. Um visitante pode estar decidindo se uma filial é próxima o suficiente, verificando de que lado de uma linha férrea ela está, encontrando a entrada correta ou comparando transporte público com estacionamento. Um mapa reduz o trabalho mental de traduzir um endereço desconhecido em contexto espacial. Ele pode tornar marcos próximos e relações entre ruas visíveis mais rápido que um parágrafo.

Essa conveniência não faz do mapa a fonte da verdade. Visitantes podem copiar um endereço, enviá-lo para outra pessoa ou lê-lo com tecnologia assistiva. Os tiles do mapa não podem suportar essas ações de forma confiável, e dados fracos, configurações de privacidade ou falha do provedor podem bloqueá-las. O endereço deve permanecer útil sem o mapa.

Um mapa incorporado pode adicionar iframe, JavaScript, fontes, imagens e requisições de terceiros. Esses recursos competem com a resposta da página e podem divulgar um endereço IP ou iniciar armazenamento sujeito a consentimento. Um visitante que nunca usa o mapa não deve pagar esse custo.

Extraibilidade por máquina significa que o software pode identificar o lugar sem interpretar pixels do mapa ou executar o provedor. Rastreadores de busca, sistemas de IA, leitores de tela, ferramentas de tradução e pipelines de dados locais precisam de um nome de lugar, endereço postal completo, coordenadas quando aplicável e um link de destino estável em HTML ou campos estruturados. Uma URL de iframe não é um endereço confiável. Rótulos do provedor podem mudar, e pins podem estar ligeiramente deslocados. O mesmo registro de localização verificado deve alimentar o endereço visível, o marcador do mapa, o link de navegação e quaisquer dados estruturados elegíveis.

As regras de escrita de elementos têm precedência: escolha um elemento tipado pelo propósito, não pela aparência. Se o propósito é orientação espacial em torno de um lugar verificado, use um bloco de mapa. Se o propósito é publicar detalhes de contato, use um bloco de horários e contato ou bloco NAP e deixe o mapa consumir o mesmo registro de endereço. Se o propósito é reservar um horário, use um bloco de reservas .

Quando usar

Use um bloco de mapa quando ver o lugar em seu entorno ajuda o leitor a completar uma tarefa dependente de localização. Usos típicos incluem uma loja, escritório, clínica, local de evento, ponto de retirada, showroom, hotel, atração, filial, entrada de evento ou limite de área de serviço. É especialmente útil quando a entrada difere do endereço postal, as ruas próximas são confusas, rotas de acessibilidade precisam de explicação, ou transporte público e estacionamento afetam a visita.

Confirme o marcador em relação à entrada real ou ponto de serviço, em vez de aceitar o primeiro resultado de geocodificação do provedor. Para um lugar dentro de um edifício maior, informe o andar, unidade ou entrada em texto.

Casos de quase-acerto frequentemente criam mapas atraentes mas inúteis:

• Uma lista de cidades atendidas: isso é uma declaração de área de serviço, não prova de uma localização física. Não coloque pins em centros de cidades e sugira escritórios.
• Um endereço postal sem acesso de visitantes: publique os detalhes postais e informe que visitas não estão disponíveis. Um mapa sugeriria uma ação de chegada não suportada.
• Uma empresa remota ou somente online: um escritório registrado pode ser legalmente relevante, mas não se torna um destino para clientes só porque uma incorporação pode localizá-lo.
• Instruções passo a passo: link para um provedor de navegação e forneça notas específicas da rota. Um mapa estático incorporado não pode considerar trânsito, fechamentos ou o ponto de partida do visitante.
• Muitas localizações: use um localizador com uma lista textual de resultados. Uma nuvem de pins não pode substituir páginas individuais de filial.
• Prova de presença local: um mapa não é evidência de que uma equipe opera lá. Apoie a afirmação com identidade, endereço, contato, horários e conteúdo específico da filial consistentes.
• Contexto geográfico decorativo: se a localização não afeta a tarefa, omita o mapa. Um horizonte de cidade ou contorno regional pertence a um propósito visual diferente.

Onde posicionar

Posicione o mapa imediatamente após o nome do lugar, endereço completo e qualquer qualificador crítico para a visita. Em uma página de localização, a sequência usual é introdução, endereço e fatos de contato, mapa, notas de chegada, horários e, em seguida, a ação de visita ou reserva. Se as direções são a resposta principal, resuma-as antes do mapa.

Mantenha o endereço, fachada do mapa, controle de carregamento, link de fallback, legenda e nota de direção em uma região rotulada. O visitante não deve precisar cruzar uma seção de depoimentos ou marketing para encontrar o endereço que pertence ao pin. Um link “Obter direções” deve usar as mesmas coordenadas ou identificador de lugar que o marcador exibido.

O bloco pode ficar próximo aos horários de funcionamento da mesma filial, mas não ao lado de um endereço conflitante, outro mapa, vídeo de reprodução automática ou anúncio estilizado como um controle. Não o posicione dentro de um carrossel, acordeão, modal obrigatório, aba oculta ou célula de tabela estreita.

Não coloque o mapa entre um aviso e a instrução que ele qualifica, ou entre uma ação de reserva e seus pré-requisitos. Nunca sobreponha texto essencial de endereço, texto de consentimento ou o único link de direções sobre tiles do mapa. Em dispositivos móveis, preserve esta ordem de leitura: nome do lugar, endereço, qualificador de visita, fallback, controle de carregamento, região do mapa e, em seguida, direções.

Anatomia

1. Nome do lugar: identifica a filial, local ou destino representado pelo marcador.
2. Endereço textual completo: inclui todas as linhas de endereço, localidade, código postal e país necessários para distinguir o lugar.
3. Qualificador de visita: informa entrada, unidade, andar, exigência de agendamento, restrição de visitante ou fato de acessibilidade quando altera a chegada.
4. Viewport reservado: fixa largura e proporção antes do carregamento de recursos interativos, evitando movimento do layout.
5. Fallback estático: fornece contexto espacial útil sem scripts; deve ser um ativo real gerado antes de ser referenciado.
6. Marcador: representa o ponto de chegada verificado, não meramente um código postal ou centroide administrativo.
7. Controle de carregamento: é um botão real com um nome acessível específico, como “Carregar mapa interativo para National Gallery.”
8. Aviso do provedor: nomeia o terceiro e explica que a ativação pode conectar-se a ele.
9. Link de direções: abre um destino HTTPS estável para navegação sem exigir o player incorporado.
10. Legenda ou nota de marco: explica a conclusão útil do mapa, como a entrada de frente para uma rua nomeada.
11. Registro de localização: fornece coordenadas governadas, identificador de lugar e data de verificação ao renderizador.
12. Estado de falha: preserva o endereço, link de direções e opção de repetição se o provedor não puder carregar.

Exemplos de design

Toda variante mantém o endereço em HTML, reserva as dimensões do mapa e fornece um link direto de direções. Apenas o comportamento de carregamento muda.

Mapa estático com direções externas — menor custo

Use uma imagem de mapa otimizada quando a orientação ajuda, mas panorâmica e zoom não. O texto alternativo informa sua conclusão espacial; a legenda carrega os marcos. Publique o caminho somente após o ativo existir.

Mapa interativo com clique-para-carregar — padrão

Exiba primeiro um fallback estático ou painel reservado neutro. Um botão carrega o iframe aprovado após ativação explícita. Isso protege a velocidade da página e torna a conexão de terceiros intencional, mantendo panorâmica, zoom e inspeção de ruas disponíveis sob demanda.

Mapa com consentimento

Use quando a política de privacidade do site exigir consentimento antes de contatar o provedor. Explique a consequência em linguagem simples e ofereça o link de direções sem exigir consentimento. Recusar não deve ocultar o endereço ou impedir o funcionamento do resto da página.

Mapa interativo sempre carregado — exceção medida

Use somente quando a interação é central, o contato com o provedor é permitido e a medição em campo aceita o custo. O carregamento preguiçoso (lazy loading) ainda pode inicializar conforme o visitante se aproxima. Mantenha um fallback renderizado no servidor porque loading="lazy" não pode prevenir falha do provedor.

Bloco de localização única dentro de um localizador

Para uma página com múltiplas localizações, emparelhe o mapa selecionado com uma lista textual de resultados. Carregar uma filial selecionada mantém a interação compreensível; alterar a seleção atualiza o nome do lugar, endereço, marcador e link de direções em conjunto. A lista permanece utilizável sem o mapa.

Parâmetros

“Fonte” significa de onde o renderizador obtém o valor editado. O sistema de localização autoritativo permanece responsável por verificar o endereço real e as coordenadas.

O renderizador deve construir URLs de provedor a partir de identificadores na lista de permitidos e coordenadas numéricas. Autores não devem colar HTML de iframe arbitrário, chaves de API, tokens de acesso ou JavaScript no corpo. Seis casas decimais localizam um ponto com precisão muito maior que um visitante normalmente precisa; retenha menos dígitos quando publicar uma entrada privada exata criaria um risco de segurança ou privacidade.

Sintaxe e exemplos de código

Estes exemplos portáveis descrevem um modelo de conteúdo canônico. Um projeto deve implementar e testar o renderizador correspondente antes que autores usem a sintaxe em produção.

Diretiva Markdown portável

:::map{variant=facade place-id="north-street-clinic" latitude=51.454514 longitude=-2.587910 zoom=16 aspect-ratio="4/3" provider=osm directions-url="https://www.openstreetmap.org/directions?to=51.454514,-2.587910" verified=2026-08-27}
## North Street Clinic

18 North Street, Bristol BS1 3PR, United Kingdom

Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.
:::

O primeiro título fornece title; a linha seguinte fornece o endereço estruturado; e o corpo restante fornece a legenda ou nota de chegada.

Mapeamento de shortcode Hugo

Use apenas parâmetros nomeados. Esta notação documenta o adaptador pretendido; não afirma que um shortcode de mapa já existe neste repositório.

{{< map variant="facade" placeId="north-street-clinic" latitude="51.454514" longitude="-2.587910" zoom="16" aspectRatio="4/3" provider="osm" directionsUrl="https://www.openstreetmap.org/directions?to=51.454514,-2.587910" verified="2026-08-27" >}}
## North Street Clinic

18 North Street, Bristol BS1 3PR, United Kingdom

Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.
{{< /map >}}

O adaptador deve reservar a proporção, renderizar o endereço e fallback no servidor, e criar o iframe somente após o gatilho declarado. Nunca deve expor uma chave de API do provedor no conteúdo editado.

Bloco WordPress

<!-- wp:amicited/map {"variant":"facade","placeId":"north-street-clinic","latitude":51.454514,"longitude":-2.587910,"zoom":16,"aspectRatio":"4/3","provider":"osm","directionsUrl":"https://www.openstreetmap.org/directions?to=51.454514,-2.587910","verified":"2026-08-27"} -->
<h2>North Street Clinic</h2>
<address>18 North Street, Bristol BS1 3PR, United Kingdom</address>
<p>Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.</p>
<!-- /wp:amicited/map -->

Um bloco nativo deve armazenar coordenadas como números, manter campos de endereço estruturados, validar o provedor e renderizar uma fachada segura no lado do servidor. A pré-visualização do editor pode mostrar uma representação estática em vez de inicializar o provedor completo.

Exemplos bons e ruins

Bom

North Street Clinic
18 North Street, Bristol BS1 3PR, United Kingdom
Use the courtyard entrance beside the pharmacy. Step-free access is available from North Street.
Carregar mapa interativo · Abrir direções em um aplicativo de mapas

Isso funciona porque o visitante pode identificar, copiar e navegar para o lugar sem a incorporação. A nota de entrada resolve uma ambiguidade real de chegada. Carregar o terceiro é uma escolha, e ambas as ações declaram claramente o que acontece.

Ruim

Encontre-nos aqui!
[mapa interativo de largura total com um pin sem rótulo]

Isso falha porque “aqui” não identifica um lugar, o endereço existe apenas dentro dos pixels do provedor, e o pin pode representar um código postal em vez de uma entrada. O mapa carregado antecipadamente adiciona custo mesmo para visitantes que não o usam. Não há fallback, data de verificação, nota de chegada ou link de navegação acessível. Adicionar um endereço ao title do iframe melhoraria o rótulo do quadro, mas não criaria texto de página selecionável.

Marcação Schema e acessibilidade

Um bloco de mapa não tem um tipo Schema.org dedicado. Campos verificados podem alimentar o Organization, subtipo LocalBusiness, Place, PostalAddress ou GeoCoordinates apropriados quando a página representa essa entidade. Use um registro de localização compartilhado; o endereço visível, marcador, URL canônico da filial e JSON-LD devem concordar.

Não adicione hasMap apenas para fazer a página parecer mais completa. Quando usado, deve apontar para uma URL de mapa estável para o mesmo lugar, não uma URL de sessão expirante ou um endpoint de iframe com chave exposta. Uma empresa de área de serviço sem uma localização pública de clientes deve descrever sua área de serviço honestamente e não deve publicar instalações inventadas ou coordenadas privadas excessivamente precisas.

A acessibilidade começa com a independência do mapa. Coloque o nome do lugar e o endereço completo em HTML, usando <address> apenas para informações de contato relevantes. Forneça um link de direções normal. Descreva entradas, marcos, transporte, estacionamento e acesso sem degraus em texto. O texto alternativo do mapa estático deve comunicar a conclusão útil, não listar cada rua.

O controle de carregamento deve ser um <button> operável por teclado com foco visível e um nome acessível vinculado ao lugar. O carregamento não deve mover o foco inesperadamente. Após a ativação, anuncie um status curto como “Mapa interativo carregado” e mantenha o foco no controle de origem ou mova-o apenas quando a interface tiver um ponto de entrada por teclado documentado. Dê a cada iframe um título único, por exemplo “Mapa de ruas interativo para North Street Clinic.”

Os controles do provedor devem permanecer operáveis em larguras estreitas e zoom de 200%. Não prenda o foco do teclado dentro do iframe. Não dependa de cor do pin, gestos de arrastar, hover ou rótulos visuais de ruas para informações essenciais. Se o mapa falhar ou o consentimento for negado, mantenha a região reservada estável e exponha o endereço, nota de chegada, link de direções externo e ação de repetição.

Regras de escrita

Comece com o nome público oficial do lugar em duas a dez palavras. Siga com o endereço postal completo conforme armazenado no registro de localização governado. Não abrevie unidade, edifício, localidade ou código postal necessários para alcançar a entrada correta. Inclua o país quando a página puder receber tráfego internacional ou quando o nome da cidade for ambíguo.

Adicione uma nota de chegada de 8 a 35 palavras apenas quando ela alterar o que o visitante deve fazer. Nomeie um marco durável ou relação de entrada: “Use a entrada do pátio ao lado da farmácia” é útil; “Você não vai nos perder de vista” não é. Fechamentos de estradas sensíveis ao tempo, rotas de construção e entradas temporárias precisam de um responsável e data de revisão em outro lugar no sistema de conteúdo.

Use um bloco de mapa para um destino selecionado. Um localizador pode alternar esse destino, mas cada estado selecionado deve atualizar o título, endereço, marcador, legenda e link atomicamente. Mostre um marcador principal por padrão. Marcos secundários podem aparecer apenas quando explicam a chegada e são visualmente distinguíveis em texto e controles.

Mantenha os rótulos de controle literais: “Carregar mapa interativo,” “Abrir direções” e “Ver entrada acessível.” Evite rótulos vagos como “Explorar,” “Ver mais” ou “Clique aqui.” Informe o provedor antes da ativação quando uma conexão tiver implicações de privacidade.

Nunca coloque números de telefone, horários de funcionamento, alegações promocionais, avaliações, preços, formulários de reserva ou longas políticas de estacionamento dentro da tela interativa. Esses fatos pertencem ao HTML e a seus próprios elementos tipados. Nunca publique uma chave de API, a localização ao vivo de um usuário, uma entrada residencial privada, pins de escritório inventados, áreas de serviço não verificadas ou coordenadas copiadas de um geocodificador não verificado. O mapa não deve sugerir acesso de visitantes onde não existe.

Verifique o endereço e o marcador na publicação, após uma alteração de localização e durante a revisão programada. As ruas e os rótulos do provedor podem mudar independentemente; a organização ainda é responsável pela precisão de seu registro de localização e instruções de chegada.

Tipos de post que o utilizam

O campo postTypes no frontmatter é a fonte para esta matriz de implementação.

Lista de verificação de garantia de qualidade

• O nome do lugar e o endereço completo aparecem como texto selecionável renderizado no servidor fora do mapa.
• O marcador aponta para o ponto de chegada público verificado, em vez de um código postal ou centroide de edifício.
• O endereço, coordenadas, identificador de lugar, link de direções e dados estruturados vêm do mesmo registro governado.
• O bloco explica qualquer unidade, andar, entrada, regra de agendamento ou rota de acessibilidade necessária para chegar.
• A implementação padrão evita requisições de terceiros até ativação explícita ou consentimento válido.
• Uma exceção de sempre-carregado tem um propósito documentado, base de privacidade e orçamento de desempenho medido.
• Largura e proporção são reservadas antes de carregar imagem, iframe ou código do provedor.
• Qualquer caminho de imagem estática aponta para um ativo real aprovado e tem texto alternativo útil.
• O controle de carregamento é um botão com nome acessível específico do lugar e foco visível.
• O iframe, quando criado, tem um título descritivo único e não prende o foco do teclado.
• O endereço, link de direções, nota de chegada e caminho de repetição permanecem utilizáveis quando scripts, consentimento ou o provedor falham.
• Informações essenciais não dependem de cor do pin, hover, arrastar, zoom ou rótulos do mapa.
• O layout funciona em larguras estreitas e zoom de 200% sem cobrir os controles do provedor.
• A página não afirma ter um escritório público, entrada ou área de serviço que a organização não pode verificar.
• Nenhuma chave de API, token de acesso, localização de usuário, coordenada privada ou URL de iframe arbitrária aparece no conteúdo editado.
• Implementações com múltiplas localizações mantêm uma lista textual acessível por teclado e sincronizam a filial selecionada atomicamente.
• Schema, se presente, descreve a mesma entidade real e endereço mostrados aos visitantes.
• A data de verificação e o responsável pela revisão atendem à política de manutenção de dados locais do site.

Um bloco de mapa é bem-sucedido quando perder o mapa altera a conveniência, não o significado. O leitor ainda sabe o lugar, como alcançá-lo e o que esperar; o provedor permanece opcional.