Como incorporar um tabuleiro de xadrez interativo no seu site

Quer que os leitores avancem por uma partida na sua página—resumo do clube, post de coaching, newsletter—sem mandá-los para o Lichess ou o Chess.com. É para isso que serve um embed: um tabuleiro interativo que vive dentro do seu layout.

O caminho mais rápido é um único iframe. Sem plugin, sem passo de build, sem biblioteca React de xadrez. Cole o seu PGN no Visualizador PGN do ScanChess gratuito, pressione Embed e solte o trecho no WordPress, Ghost ou qualquer página HTML.

Partida completa ou uma posição?

Escolha o formato antes de escolher a ferramenta:

• Partida completa (PGN): os leitores avançam lance a lance. Use um embed interativo. Este guia.
• Uma posição (FEN): só precisa de um diagrama ou de uma string que alguém cole num tabuleiro de análise. Use o que é FEN, FEN para imagem ou as opções de partilha em como partilhar uma partida de xadrez online.

Em dúvida, incorpore o PGN. Uma partida completa já contém todas as posições pelo caminho.

Passo 1: Obter um PGN limpo

Precisa dos lances em Portable Game Notation. Fontes que funcionam bem:

1. Exportar do Lichess ou Chess.com.
2. Colar lances que já tenha digitado.
3. Fotografar uma planilha em papel e digitalizá-la com o ScanChess—útil quando a partida nunca saiu da planilha.

Lances ilegais ou mal digitados quebram a reprodução depois. Se o PGN estiver instável, passe-o primeiro pelo validador PGN.

Passo 2: Gerar o trecho de embed

1. Abra o Visualizador PGN.
2. Cole o seu PGN (ou carregue uma partida que já partilha a partir do ScanChess).
3. Confirme que o tabuleiro reproduz como espera—gire o tabuleiro se o artigo estiver do ponto de vista das pretas.
4. Clique em Embed na barra de ferramentas. O visualizador copia um iframe para a área de transferência.

Um trecho típico parece-se com isto (o seu src incluirá o PGN codificado):

<iframe
  src="https://scanchess.com/embed/pgn-viewer?pgn=1.+e4+e5+2.+Nf3+Nc6+3.+Bb5+a6"
  width="640"
  height="560"
  style="border:0;border-radius:12px;width:100%;max-width:100%;aspect-ratio:16/10;"
  allowfullscreen
  loading="lazy">
</iframe>

O URL /embed/pgn-viewer é a superfície incorporável. Use esse caminho (ou o trecho que o botão lhe dá), não o URL normal de uma ferramenta ou página de partilha—esses estão bloqueados de propósito para não abrirem em iframe.

Passo 3: Colar no seu CMS

WordPress (editor de blocos)

1. Adicione um bloco de HTML personalizado onde o tabuleiro deve aparecer.
2. Cole o trecho iframe.
3. Pré-visualize no desktop e no telemóvel, depois publique.

Não é necessário nenhum plugin de xadrez. O tabuleiro adapta-se com os estilos width: 100% do trecho.

Ghost

1. No editor, digite /html e escolha um cartão HTML.
2. Cole o trecho.
3. Pré-visualize e publique.

Substack e newsletters semelhantes

Muitos editores de newsletter restringem iframes em bruto. Se o cartão HTML aceitar o trecho, use-o. Caso contrário, ligue para a partida—o deep link do Visualizador PGN (/tools/pgn-viewer?pgn=...) ou um URL permanente do ScanChess de uma partida digitalizada—e diga «abra o tabuleiro interativo». Combinar esse link com uma imagem estática do tabuleiro via FEN para imagem ou um PGN para GIF curto mantém o post legível na caixa de entrada.

Sites estáticos (Hugo, Astro, Jekyll, HTML puro)

Cole o iframe no template da página ou num bloco HTML de Markdown. Como é HTML puro, não depende de React, Vue nem de um pacote npm de xadrez.

Da planilha em papel ao embed

Partidas presenciais costumam começar a tinta, não com um botão de download:

1. Fotografe a planilha.
2. Digitalize-a com o ScanChess para obter um PGN validado (e, em geral, um link de partilha).
3. Abra essa partida no Visualizador PGN ou cole lá o PGN.
4. Pressione Embed e cole o trecho no site do clube ou no blog.

Esse fluxo é a versão ScanChess de «digitar a partida à mão e depois lutar com um plugin de embed».

Dicas que evitam republicar

• Pré-visualize a reprodução antes de incorporar. Lado errado a jogar ou PGN truncado é óbvio no visualizador e invisível na pré-visualização do CMS se saltar este passo.
• Prefira PGN mais curto no URL quando a partida for longa. Embeds por query string têm limites práticos de comprimento. Se o botão Embed encurtar ou reformatar o texto, fique com essa versão. Em páginas de arquivo do clube, um link permanente é mais durável do que enfiar cinquenta lances no src.
• Largura no telemóvel. Mantenha os estilos de largura fluida do trecho. Larguras fixas em píxeis que ficavam bem no rascunho de desktop muitas vezes transbordam no telemóvel.
• Linha de atribuição. O trecho copiado inclui uma pequena linha «powered by ScanChess». Deixe-a se puder: diz aos leitores de onde vem a reprodução e ajuda a manter a ferramenta gratuita.

Quando uma imagem estática ou um GIF chega

Um tabuleiro interativo é excessivo para um puzzle de um lance no chat ou uma miniatura nas redes. Nesses casos:

• FEN para imagem para um diagrama único.
• PGN para GIF para um highlight animado curto.

Se mais tarde quiser que estudem a partida completa no seu site, volte ao embed com iframe.

Opcional: autoalojamento para programadores

Se controla o frontend e prefere não iframes um leitor alojado, o pacote open-source chess-board-embed (licença MIT) no repositório ScanChess oferece um web component sem dependências (<chess-board-embed>) que pode construir e servir você mesmo. A maioria dos webmasters de clube nunca precisa desse caminho—o iframe do Visualizador PGN basta. Use o component quando quiser os assets do tabuleiro na sua própria origem ou dentro de um design system que proíbe frames de terceiros.

Guias relacionados

• Como partilhar uma partida de xadrez online — ficheiros PGN, links, FEN e quando não incorporar.
• O que é PGN? — etiquetas, movetext e como é um ficheiro válido.
• Converter uma planilha manuscrita para PGN — do papel ao digital antes de incorporar.
• Ferramenta gratuita: Visualizador PGN — reproduzir, partilhar e copiar o trecho de embed.