# Páginas compostas: figuras com rótulos

> Figuras que põem palavras sobre uma imagem: rótulos nas âncoras de um recurso, o texto alternativo, a legenda e a nota próprios de uma figura, como um rótulo é composto, rótulos afastados do seu ponto com linhas de chamada, legendas de mapa e símbolos em linha, e os avisos dos rótulos

- Versão HTML: https://postext.dev/pt/docs/composed-pages-figures
- Última atualização: 2026-10-20
- Tempo de leitura: 9 min
- Outros idiomas: [en](https://postext.dev/en/docs/composed-pages-figures.md), [es](https://postext.dev/es/docs/composed-pages-figures.md), [ca](https://postext.dev/ca/docs/composed-pages-figures.md), [de](https://postext.dev/de/docs/composed-pages-figures.md), [fr](https://postext.dev/fr/docs/composed-pages-figures.md), [it](https://postext.dev/it/docs/composed-pages-figures.md), [zh](https://postext.dev/zh/docs/composed-pages-figures.md), [ja](https://postext.dev/ja/docs/composed-pages-figures.md), [ar](https://postext.dev/ar/docs/composed-pages-figures.md)

## Em poucas palavras

Um mapa ou um esquema de um livro costuma ter palavras por cima: os nomes de mares e cidades, as peças de uma máquina. O Postext compõe essas palavras como texto sobre a imagem, para que cada idioma tenha as suas. Esta página mostra como escrevê-las no Markdown, como cada uma é posicionada e desenhada e como um nome pode ficar afastado do seu lugar com uma linha que aponta para ele. Também trata das legendas com símbolos e dos avisos de rótulos que não cabem ou que se tocam.

Esta página trata das figuras de uma página composta, ou do texto corrido, que põem palavras sobre a sua imagem. Como se escreve uma página composta está em [Páginas compostas](https://postext.dev/pt/docs/composed-pages.md); os estilos de rótulo e os campos de rótulo de uma âncora, em [Configuração › Páginas compostas](https://postext.dev/pt/docs/configuration-composed-pages.md#estilos-de-rótulo).

## Figuras com rótulos

```md
:::figure{resource="mapa-europa" slot="mapa"}
::label[OCÉANO ATLÁNTICO]{at="atlantico" style="mar"}
::label[**Madrid**]{at="madrid"}
::label[Mar Negro]{at="62% 48%"}
:::
```

`:::figure{resource="…"}` coloca um recurso, com a legenda e o número dele, como faz `::resource`, e lista os rótulos que vão sobre a imagem: uma linha `::label[TEXTO]{…}` por rótulo, com linhas em branco permitidas entre elas.

- `at` indica uma âncora do recurso (um ponto definido uma única vez sobre a imagem e compartilhado por todos os idiomas), ou dá um ponto em porcentagens da imagem, `at="x% y%"`, para um rótulo sem âncora.
- `style` indica um estilo de rótulo e prevalece sobre o estilo da âncora.
- `leader` traça uma linha do rótulo até o ponto da âncora, e `leader="none"` a retira (veja [Linhas de chamada, legendas de mapa e símbolos](https://postext.dev/pt/docs/composed-pages-figures.md#linhas-de-chamada-legendas-de-mapa-e-símbolos)).
- O texto entre colchetes é Markdown em linha: negrito, itálico, chips e símbolos escritos com `:icon`.

Uma figura funciona tanto no texto corrido quanto dentro de um bloco. Os rótulos dela são desenhados sobre a imagem como texto e vão aonde a figura for: uma coluna, um flutuante, um bloco girado ou reduzido pela escada de ajuste (os passos que fazem o conteúdo caber), uma página dupla. Quando falta o `:::` de fechamento de uma figura, a primeira linha que não é um rótulo nem está em branco encerra a figura, e o Postext a aponta como contêiner não fechado.

### As palavras próprias de uma figura

Um recurso guarda uma imagem, as âncoras dela e um único conjunto de palavras, mas cada edição de um livro precisa das próprias palavras. Uma figura pode definir o próprio `alt`, a própria `caption` e a própria `note`, na linha de abertura ou em linhas próprias, e eles substituem os do recurso nas páginas desse arquivo:

```md
:::figure{resource="relieve" alt="Mapa de relieve de Varenia"}
::caption[Relieve de **Varenia**, con sus tres cordilleras]
::note[Fuente: levantamiento de 1932]
::label[Mar de Sal]{at="mar"}
:::
```

- Como atributos da linha de abertura, `alt`, `caption` e `note` recebem um texto curto entre aspas. As linhas `::alt[…]`, `::caption[…]` e `::note[…]` recebem o texto entre colchetes, que pode conter Markdown em linha e `\\` para uma quebra de linha, como a legenda e a nota de um recurso. Uma linha prevalece sobre o atributo de mesmo nome; as linhas ficam entre os rótulos, com linhas em branco se quiser.
- O que a figura não define continua sendo o do recurso. Um valor vazio não diz nada: `caption=""` tira a legenda, `alt=""` marca a imagem como decorativa.
- As palavras substituem as do recurso no capítulo em que estão escritas: a diagramação, o texto alternativo de todas as saídas e o PDF marcado as usam, e o próprio recurso não muda. Num capítulo, um recurso tem um só conjunto de palavras, o da primeira figura: se uma figura posterior do mesmo recurso trouxer outros textos, eles não aparecem, e o Postext gera o aviso `figureWordsShared`. Uma cópia reduzida que precise de legenda própria usa um segundo recurso que aponte para o mesmo arquivo de imagem. Ao contrário de um rótulo, a legenda não é associada caractere a caractere ao Markdown; `sourceAt` responde a um clique nela como faz com a legenda de um recurso.

### Como um rótulo é composto

- **Onde.** Um rótulo fica no ponto da âncora, dado como fração da imagem inteira; se a imagem for recortada na área segura ou composta menor, o rótulo acompanha o desenho. O `align` da âncora indica que lado do rótulo fica no ponto, e `verticalAlign`, que borda fica na altura dele. `start` e `end` seguem a direção do próprio rótulo: em árabe, `start` é a borda direita. `rotate` gira o rótulo em torno do ponto, no sentido horário e em qualquer ângulo: um rio ao longo do curso, uma serra na diagonal.
- **Aparência.** O `style` do rótulo, ou então o da âncora, indica um estilo de rótulo (veja Configuração › Páginas compostas); sem estilo, o rótulo usa a fonte do texto do corpo. O halo traça o contorno das letras por baixo do preenchimento; a placa (`background`) preenche a caixa em volta do texto, alargada por `padding`.
- **Ajuste.** Se a âncora tem `width`, o rótulo quebra entre palavras dentro dessa medida, nunca no meio de uma palavra. Quando uma palavra é mais larga que a medida, o rótulo inteiro é composto menor, até o `minScale` do estilo; um rótulo que ainda assim não cabe é desenhado com a palavra mais larga cortada. Sem `width`, o rótulo fica numa só linha, exceto onde quebra com `\\`, como numa legenda.
- **Texto.** O texto entre colchetes é Markdown em linha, composto como uma legenda: negrito, itálico, chips, marcações de destaque, referências, fórmulas em linha. Um nome de várias palavras é um único rótulo, qualquer que seja a ordem das palavras em cada idioma: `::label[OCEANO ATLÂNTICO]` e `::label[ATLANTIC OCEAN]` ficam na mesma âncora. Rótulos da direita para a esquerda são compostos da direita para a esquerda; os chineses e japoneses quebram entre caracteres.
- **Saídas.** O canvas, o PDF, o visualizador HTML, o EPUB de layout fixo e o Folio desenham os rótulos. Numa página da direita para a esquerda, o rótulo fica onde a imagem o mostra.
- **Vertical.** Com `writingMode: 'vertical-rl'` na âncora (ou no estilo de rótulo dela), o rótulo é composto como uma página vertical: os caracteres em pé, em células uma sob a outra, as colunas da direita para a esquerda, as palavras latinas e os números longos virados de lado e os números curtos numa só célula. Então `width` é uma parte da altura da imagem, o comprimento de uma coluna, e um rótulo chinês ou japonês se reparte em mais colunas. `align` corre ao longo da coluna (`start` é a ponta de cima), `verticalAlign` através das colunas (`top` é a primeira, a da direita), e `rotate` continua girando o rótulo. Na página espelhada de um livro da direita para a esquerda, o rótulo se lê do mesmo jeito, de cima para baixo nas colunas e em pé, no mesmo ponto da imagem (desde o postext 1.40).
- **Verificações.** Um rótulo que continua mais largo do que a medida no `minScale` do estilo gera `labelOverflow`; dois rótulos cujas linhas se tocam geram `labelOverlap` no posterior. As duas coisas são verificadas em cada edição; assim, uma tradução com palavras mais longas mostra onde precisa de espaço. A paleta de uma parte (`:::part{palette="…"}`) recolore os rótulos das páginas dela como faz com as legendas. A verificação de contraste mede um rótulo sobre a placa ou, se não houver, sobre o halo; um rótulo posto diretamente sobre a imagem é ignorado, porque o fundo dele é a imagem. O preflight de impressão também verifica os rótulos: letra pequena em cores de processo, tintas e distância ao refile.
- **Numa página dupla.** Uma figura que atravessa a lombada de uma página dupla (um bloco com `crossGutter: true`) pinta uma metade em cada página; um rótulo que entrasse na faixa da medianiz seria cortado pela dobra e não se leria em nenhuma das duas. Esse rótulo desliza na horizontal até a borda da faixa, do lado em que fica o ponto da âncora, e mantém a altura; um ponto exatamente sobre a lombada fica na primeira página, como um bloco. Uma âncora com `gutter: 'cross'` mantém o lugar, para um título posto nas duas páginas. As bordas externas da folha não são tocadas: um rótulo que passa do refile é cortado como a imagem. Desde o postext 1.43.

### Linhas de chamada, legendas de mapa e símbolos

Desde o postext 1.48, um rótulo pode ficar afastado do que nomeia, um rótulo pode ser a legenda de um mapa, e um rótulo, uma legenda ou uma célula de tabela pode trazer símbolos.

**Linhas de chamada.** O `labelAt` de uma âncora afasta o rótulo do seu ponto (um nome no mar, uma nota na margem de um esquema), e uma linha de chamada liga o rótulo de volta ao ponto. A aparência é o `leader` do estilo de rótulo (veja [Configuração › Estilos de rótulo](https://postext.dev/pt/docs/configuration-composed-pages.md#estilos-de-rótulo)); o Markdown só a liga ou desliga para um rótulo:

```md
:::figure{resource="relieve" slot="mapa"}
::label[Sierra Alta]{at="peaks" leader}
::label[Lago Verde]{at="lake" leader="none"}
:::
```

`leader` com qualquer valor que não seja `none`, `false` ou `off` liga a linha; sem o atributo, decide o `leader` da âncora e, sem nenhum dos dois, um rótulo afastado do seu ponto recebe uma linha quando o estilo dele tem `leader`. A nota de um bloco também pode apontar para um lugar da imagem: um [conector](https://postext.dev/pt/docs/configuration-composed-pages.md#conectores) cuja ponta indica uma âncora da imagem (`anchor: 'lake'`).

**Rótulos de várias linhas.** `:::label{at="…" style="…"}` … `:::`, dentro de um `:::figure`, escreve um rótulo linha por linha: cada linha não vazia da origem é uma linha do rótulo; assim, uma legenda de mapa ou um endereço não precisa de `\\` no fim de cada linha. O primeiro `:::` fecha o rótulo, e o seguinte, a figura. `::label[…]` continua sendo um rótulo de uma linha, quebrado só onde diz `\\`.

**Legendas de mapa.** Um rótulo num estilo com `kind: 'legend'` é a legenda de um mapa: cada linha é uma fila, e o símbolo que abre uma fila fica numa coluna da largura do símbolo mais largo; assim, as palavras das filas começam numa mesma borda. Escreva o símbolo no começo de cada linha:

```md
:::figure{resource="mapa-politico" slot="mapa"}
:::label{at="key" style="key"}
:icon[País]{glyph="■" color="country"} País
:icon[Capital]{glyph="⊙" font="Noto Sans Math"} Capital
:icon[Cidade]{resource="town-mark" size="0.55"} Cidade
:icon[Fronteira]{line="dashed" color="border"} Fronteira
:::
::label[:icon[Capital]{glyph="⊙" font="Noto Sans Math"} Varena]{at="capital"}
:::
```

**Símbolos.** `:icon[alt]{…}` põe um pequeno símbolo na linha, apoiado na linha de base:

| Atributo | Efeito |
| --- | --- |
| `resource="…"` | Um recurso bitmap ou SVG, mantendo a proporção. |
| `glyph="…"` | Um caractere, na fonte do texto ou na fonte que `font="…"` indica. |
| `line="solid\|dashed\|dotted"` | Uma amostra de linha, duas vezes mais longa que alta: uma fronteira ou uma estrada numa legenda de mapa. |
| `color="…"` | Uma cor hexadecimal ou uma entrada da paleta: a cor de um caractere, de uma linha ou de uma imagem. |
| `size="…"` | A altura do símbolo em ems do texto. Padrão `0.75`, a altura de uma maiúscula. |

O primeiro de `resource`, `glyph` e `line` que estiver escrito decide o tipo; sem nenhum deles, a diretiva continua sendo texto. O texto entre colchetes é o texto alternativo do símbolo: os leitores de tela, o PDF marcado e o texto alternativo da imagem o leem no lugar do símbolo, e um símbolo com colchetes vazios é decoração. Os símbolos são lidos nos rótulos de figura e em todos os trechos de um recurso: legendas, notas e células de tabela. Nesta versão, não são lidos no texto corrido, nos títulos nem nos textos de design.

### labelAnchorUnknown

O `at` de um `::label` indica uma âncora que o recurso da figura não tem. O rótulo não é desenhado; o EPUB refluível continua listando-o, e o texto alternativo da imagem o menciona. O aviso traz o recurso, a âncora, as âncoras que o recurso tem (`known`), o idioma, a página e o intervalo de origem do texto do rótulo. Corrija o id da âncora, adicione a âncora ao recurso ou posicione o rótulo com `at="x% y%"`.

No painel Verificações do Sandbox, o aviso leva ao rótulo no painel Texto, e o botão com o alfinete abre as âncoras da imagem com esse nome pronto para colocar: um clique na imagem adiciona a âncora.

### anchorUnlabelled

Uma âncora do recurso da figura tem um estilo de rótulo, mas nenhum `::label` da figura fica nela neste idioma: o mapa tem espaço para uma palavra que esta edição deixa de fora. É uma nota; o `postext check` a lista como `info`. Âncoras sem estilo, como a de um personagem de quadrinhos, não são apontadas. O aviso traz o recurso, a âncora, o estilo dela, o idioma, a página e o intervalo de origem da figura. Escreva o rótulo no Markdown deste idioma ou tire o estilo da âncora.

No painel Verificações, o aviso leva à figura no painel Texto, e o botão com o alfinete abre as âncoras da imagem nessa âncora.

### labelOverflow

Um rótulo continua mais largo do que a `width` da âncora na menor escala que o estilo de rótulo permite (`minScale`): é desenhado nessa escala e ultrapassa a medida. O aviso traz o recurso, o texto do rótulo, a âncora (nenhuma, se o rótulo foi posto com porcentagens), a largura que lhe foi dada, a escala atingida, o idioma, a página e o intervalo de origem do texto do rótulo. É verificado em cada edição; assim, um idioma de palavras mais longas transborda onde outro não. Alargue a `width` da âncora, encurte a palavra no Markdown desta edição ou baixe o `minScale` do estilo de rótulo. Um rótulo chinês ou japonês quebra entre caracteres e não transborda assim. Desde o postext 1.39.

### labelOverlap

Dois rótulos da mesma figura se tocam; num rótulo com placa, conta a placa. O aviso fica no rótulo posterior, na ordem em que foram escritos, com o texto do primeiro rótulo anterior que ele toca e quantos rótulos anteriores toca no total. O teste usa a caixa própria de cada linha, girada com o rótulo, de modo que o espaço ao lado de uma linha curta fica livre, e deixa duas linhas se invadirem em até um oitavo da altura de uma linha. É verificado em cada edição. Mova uma das âncoras, estreite a `width` de um rótulo para que ele quebre ou encurte as palavras no Markdown desta edição. No painel Verificações do Sandbox, o botão do alfinete abre as âncoras da imagem na âncora do rótulo. Desde o postext 1.39. Com `overlap: 'allow'` numa âncora, ou no estilo de rótulo dela, um rótulo que o original imprime tocando os vizinhos (um mapa denso) sai da verificação, e nenhum par de que ele faça parte é reportado. Desde o postext 1.42. As zonas `avoid` de uma imagem contam como os símbolos de um mapa: retângulos desenhados sobre os pontos e os ícones do mapa, no modo **Zonas a evitar** das marcas da imagem, em frações da imagem. Um rótulo que invade uma delas é reportado do mesmo modo, com `symbol 2` no lugar de outro rótulo (`withSymbol` nos dados), e `overlap: 'allow'` deixa um rótulo fora das duas verificações. Desde o postext 1.42.

### figureWordsShared

Uma `:::figure` define palavras (`alt`, `caption` ou `note`) para um recurso cujas palavras uma figura anterior do mesmo capítulo já definiu, e elas são diferentes. As páginas mostram as palavras da primeira figura e omitem estas. O aviso traz o recurso, as palavras omitidas e o intervalo de origem da primeira delas; uma figura posterior que não dá palavras próprias não é problema. Dê à figura um recurso próprio: um segundo recurso que aponte para o mesmo arquivo de imagem, com legenda, número e âncoras próprios. No painel Verificações do Sandbox, ele aparece em Figuras. Desde o postext 1.42.