# Formato do documento: imagens, tabelas e vídeos > Recursos no texto: referências e inserções, numeração, posicionamento e onde um flutuante vai parar, contorno de texto, tamanho do bitmap, áreas seguras, âncoras de quadrinhos e vídeos - Versão HTML: https://postext.dev/pt/docs/document-format-resources - Última atualização: 2026-10-16 - Tempo de leitura: 42 min - Outros idiomas: [en](https://postext.dev/en/docs/document-format-resources.md), [es](https://postext.dev/es/docs/document-format-resources.md), [ca](https://postext.dev/ca/docs/document-format-resources.md), [de](https://postext.dev/de/docs/document-format-resources.md), [fr](https://postext.dev/fr/docs/document-format-resources.md), [it](https://postext.dev/it/docs/document-format-resources.md), [zh](https://postext.dev/zh/docs/document-format-resources.md), [ja](https://postext.dev/ja/docs/document-format-resources.md), [ar](https://postext.dev/ar/docs/document-format-resources.md) ## Em poucas palavras Esta página trata das imagens, tabelas e vídeos de um livro. Você os inclui uma vez e os menciona no texto, e o Postext coloca cada um perto do lugar onde é mencionado pela primeira vez. Você pode escolher onde ele fica: no alto de uma página, na largura de todas as colunas ou exatamente onde foi escrito. O texto pode contornar uma imagem. Uma imagem pode marcar a parte que sempre deve aparecer quando ela é cortada para caber. Os vídeos tocam na visualização web e nos livros digitais, e no impresso mostram uma imagem. ## Recursos Imagens, SVGs, tabelas e vídeos não são escritos no meio do texto. Eles são declarados uma vez como **recursos** (gerenciados no [painel Recursos](https://postext.dev/pt/docs/sandbox.md#painel-recursos) do Sandbox, que cuida do envio de imagens e SVGs, de um editor de tabelas interativo, de vídeos do YouTube, do Vimeo e enviados, e da edição de legendas e posicionamento) e depois ligados à sua prosa por id. **Referenciar um recurso basta para incorporá-lo**: você o menciona uma vez com um `:ref{id="…"}` em linha, e o motor faz a figura ou a tabela flutuar até o primeiro espaço livre depois dessa referência (o pé da coluna em que você o menciona, o topo da coluna seguinte, uma faixa da página seguinte), como faria um compositor de livros impressos. Você não o posiciona uma segunda vez. As duas formas abaixo são sintaxe nova que não colide com o CommonMark, de modo que um documento que as usa continua legível como texto simples em qualquer outro visualizador de Markdown. ### Referência em linha (a forma principal) Refira-se a um recurso de dentro da prosa com `:ref{id="…"}`. A primeira referência ao mesmo tempo **incorpora** o recurso (para que ele seja posicionado na página) e renderiza o número calculado, precedido por padrão do rótulo curto do tipo: ```md As shown in :ref{id="lighthouse-diagram"}, the lantern room sits above the gallery. ``` é renderizado como: *As shown in Fig. 1.7, the lantern room sits above the gallery.* E o próprio diagrama flutua até o espaço livre mais próximo depois da frase (o pé desta coluna, o topo da seguinte ou uma faixa da página seguinte), enquanto esta frase e o texto depois dela seguem sem interrupção. O texto corrido nunca é interrompido no ponto da referência. Onde o recurso fica (no primeiro espaço livre, ou só num espaço no topo ou no pé; numa única coluna ou na largura toda) depende do seu **posicionamento** (veja [Posicionamento](https://postext.dev/pt/docs/document-format-resources.md#posicionamento) abaixo) e de onde você o menciona: a busca começa logo depois da referência. ### Inserção em bloco (opcional, posicionamento explícito em linha) Às vezes você quer que um recurso fique num ponto exato do fluxo em vez de flutuar. Desative a flutuação dando ao recurso `placement.position: "here"` e inserindo-o com `::resource{id="…"}` numa linha própria: ```md Here is the floor plan we discussed. ::resource{id="lighthouse-diagram"} The keeper's quarters occupy the eastern wing. ``` Para um recurso flutuante, a diretiva `::resource` é desnecessária: o `:ref` já o posicionou, e um `::resource` redundante para o mesmo id é tratado apenas como mais uma referência, não como uma segunda cópia. Um `::resource` só renderiza o recurso em linha quando o posicionamento resolvido é `"here"`. Um recurso em linha mantém uma linha de espaço acima dele (o espaço de flutuante), como faria um flutuante, a menos que o bloco anterior peça mais. No texto corrido ele mantém o mesmo espaço abaixo; depois, o texto que vem em seguida volta para a grade de linhas de base, o que pode acrescentar até mais uma linha. Um título, uma lista, um boxe ou outro recurso em linha logo depois dele divide esse espaço com o seu próprio espaço acima: vale o maior dos dois, não a soma. (Até o postext 1.4, o espaço abaixo era só o que o encaixe na grade deixava, de nada até uma linha; `layout.inlineResourceGap: 'above'` mantém essa regra, e os livros salvos antes do 1.5 são lidos com ela.) Dentro de um boxe (`:::callout`), o recurso mantém o mesmo espaço, uma linha do próprio texto do boxe acima dele e, com `'around'`, abaixo; no topo ou no pé do boxe, quem o separa é o preenchimento. (Até o postext 1.4, ele ficava encostado no texto do boxe; `layout.inlineResourceGapInBoxes: false` mantém isso, e os livros salvos antes do 1.5 cujos boxes inserem um recurso são lidos com essa opção.) Um recurso em linha cujo posicionamento também diz `span: 'page'` (`placement: { position: 'here', span: 'page' }`) ocupa a página no ponto da sua diretiva num layout de várias colunas, como faz um boxe que ocupa a página: as colunas acima dele se fecham niveladas (balanceadas, ou o recurso vai para o topo da página seguinte quando isso não é possível), ele é composto na largura do conteúdo com o mesmo espaço acima e abaixo, e o texto continua em todas as colunas embaixo dele. Numa página de uma coluna, ele é composto como antes, na medida inteira. Um recurso `span: 'column'` com `columns` definido fica na sua coluna quando é inserido em linha: as colunas só contam para os flutuantes. Desde o postext 1.19. O `id` precisa corresponder a um recurso definido no painel Recursos. O motor renderiza o recurso (bitmap, SVG ou tabela) com a legenda desenhada embaixo, como pé de figura ou de tabela. O texto da legenda é formado pelo `captionPrefix` do tipo de recurso, pelo número calculado e pela legenda do próprio recurso, por exemplo **Figura 1.7. A planta original do farol.** Sua tipografia é regida por [Configuração › Estilo de legenda](https://postext.dev/pt/docs/configuration-resources.md#estilo-de-legenda): o rótulo e a descrição compartilham uma família tipográfica e um tamanho, enquanto o rótulo mantém configurações independentes de negrito, itálico e cor; o espaço acima da legenda é `0.75em` por padrão e o alinhamento é à esquerda. A legenda pode, em vez disso, ficar acima do recurso (`captionStyle.position: 'above'`, de forma global ou por tipo de recurso), opcionalmente sobre uma barra colorida. Um recurso também pode ter uma `note` (uma linha curta de fonte ou de crédito, com a mesma formatação em linha e as mesmas marcas `:ref` da legenda), composta num corpo menor sob o recurso (sob a legenda quando a legenda fica embaixo, sob o corpo quando fica em cima) e estilizada por `captionStyle.note`. **Quebras de linha em legendas e notas.** Uma legenda ou uma nota é um parágrafo composto na medida do seu espaço, e uma quebra de linha digitada nela vale como espaço. Para começar uma linha nova, escreva `\\` (a quebra forçada dos títulos) ou termine a linha com uma barra invertida, a quebra forçada do Markdown: `¹ Measured at 20 °C. \\ ² Mean of three runs.` compõe cada nota de uma tabela larga numa linha própria. A linha antes de uma quebra mantém sua largura natural, sem ser esticada até a medida, e duas quebras seguidas não criam uma linha vazia (um espaço inseparável entre elas cria). Numa célula de tabela, `\\` faz o mesmo que uma quebra de linha: abre um parágrafo novo; o recuo da linha seguinte é mantido, de modo que dois espaços iniciais ainda aninham um item de lista. No próprio texto as duas barras invertidas são sempre uma quebra, sem escape: para imprimi-las, ponha-as em código em linha, onde as barras invertidas saem como foram escritas. No destino de um link elas continuam fazendo parte da URL, e nos atributos de uma diretiva (o `text` de um `:ref`) fazem parte do valor; dentro de um chip, que é composto numa só linha, uma quebra vale como espaço. (Até o postext 1.4, as barras invertidas eram impressas, e uma legenda ou uma nota só quebrava onde a medida acabava.) Os recursos de tabela desenham a própria grade, estilizada por [Configuração › Estilo de tabela](https://postext.dev/pt/docs/configuration-resources.md#estilo-de-tabela): as células do corpo e do cabeçalho têm tipografia totalmente independente, o fundo do cabeçalho é `#f0f0f0` por padrão, as bordas `0.75pt`, e `cellPadding` `0.375em`; qualquer campo não definido herda do texto do corpo. As larguras das colunas fazem parte da própria tabela: `TableModel.columnWidths` guarda um peso relativo por coluna (`[2, 1, 1]` dá à primeira coluna metade da largura); quando não definido, as colunas dividem a largura por igual. Uma tabela também pode ser composta numa variante nomeada: `table.styleId` escolhe um dos `tableStyles` do documento (veja [Configuração › Estilos de tabela nomeados](https://postext.dev/pt/docs/configuration-resources.md#estilos-de-tabela-nomeados)), cujos campos não definidos herdam de `tableStyle`; um id desconhecido ou ausente mantém `tableStyle`. Uma célula posiciona seu conteúdo com `TableCell.align` (`left`, `center`, `right`; os itens de lista ficam alinhados à esquerda) e `TableCell.verticalAlign` (`top`, o padrão, `middle` ou `bottom`). O alinhamento vertical move todo o conteúdo da célula (a imagem e o texto embaixo dela, como uma unidade) dentro de uma célula mais alta que ele: uma linha esticada por uma vizinha mais longa, ou as linhas que um `rowSpan` cobre. Vale em todas as saídas (canvas, HTML, PDF), em tabelas giradas e em cada fatia de uma tabela dividida entre páginas. Os dois se definem por célula nos botões de alinhamento da barra de ferramentas do editor de tabelas do Sandbox. Uma célula de tabela também pode conter uma imagem. `TableCell.image` indica um recurso bitmap ou SVG pelo id (`{ "resourceId": "fig-arm", "width": 0.7 }`): a imagem é desenhada dentro da célula (nunca numerada, flutuante nem com legenda), ajustada à largura interna da célula (ou à fração dela indicada por `width`, padrão `1`) mantendo a proporção, alinhada como o texto da célula, e qualquer texto da célula corre embaixo dela. A linha cresce para contê-la. No editor de tabelas do Sandbox, o botão de imagem da barra de ferramentas escolhe o recurso da célula ativa e um campo de largura define a fração. Um id que não corresponde a nenhum recurso de imagem deixa a célula só com texto. Uma célula pode ter seu próprio preenchimento. `TableCell.background` é um valor de cor (`{ "hex": "#c1dfd6", "model": "hex" }`, opcionalmente ligado a uma entrada da paleta do documento com `paletteId`) pintado no lugar do fundo de cabeçalho ou de corpo do estilo; é assim que uma matriz de compatibilidade colore suas células de verde, vermelho e amarelo. O editor de tabelas do Sandbox o define pelo controle de preenchimento da barra de ferramentas. Para criar a legenda dessas cores, a legenda, a nota e qualquer bloco de texto aceitam uma **amostra de cor** em linha: `:swatch{color="#c1dfd6"}` (um hex, ou o id de uma entrada da paleta, `:swatch{color="table-compatible"}`) compõe um pequeno quadrado sobre a linha de base, com três quartos do tamanho da fonte, preenchido com a cor e contornado na cor do texto, de modo que uma nota pode dizer `:swatch{color="ok"}: compatible; :swatch{color="no"}: incompatible`. Uma cor que não se resolve em nada desenha um contorno vazio. O hex pode ter canal alfa (`#rrggbbaa`, `#rgba`), e cores `rgb()` / `rgba()` também funcionam, de modo que um preenchimento de célula translúcido tem uma amostra translúcida correspondente (veja [Configuração › Transparência](https://postext.dev/pt/docs/configuration-fonts-colors-viewers.md#transparência)). Os recursos SVG também podem ser recoloridos para impressão com uma única cor especial por meio de `diagramStyle.singleInk` (padrão `false`). Quando ativado, todas as cores de um diagrama SVG são convertidas numa retícula de `diagramStyle.inkColor` (que por padrão é a cor principal da paleta, `#295AA3`) proporcional à luminância (o branco vira papel, o preto a tinta cheia), de modo que as figuras se reproduzem fielmente quando o documento é impresso com uma única cor especial. Veja [Configuração › Estilo de diagramas](https://postext.dev/pt/docs/configuration-resources.md#estilo-de-diagramas). Uma inserção malformada (`id` ausente ou vazio, `id` sem aspas ou com aspas simples, atributos extras) não vira um bloco de recurso; ela passa para a análise comum de parágrafo e continua visível na saída. O mesmo acontece com uma linha de inserção bem formada colada embaixo de uma linha de parágrafo sem linha em branco entre elas: ela é lida como parte desse parágrafo. Os dois casos geram um aviso `malformedEmbed`, uma entrada **Inserção composta como texto** no painel Verificações do Sandbox. As referências em linha são reconhecidas dentro de qualquer bloco de texto (parágrafos, títulos, citações em bloco e itens de lista) e podem conviver com negrito, itálico, código em linha e fórmulas em linha. #### Opções de referência A diretiva `:ref` aceita três atributos opcionais, em qualquer ordem. `style` escolhe como o rótulo calculado é renderizado: `style="number"` imprime só o número (`1.7`), `style="full"` imprime o nome completo do tipo mais o número (`Figure 1.7`), e quando `style` não é definido usa-se o `shortLabel` do tipo mais o número (`Fig. 1.7`). `case` muda a caixa (maiúsculas ou minúsculas) apenas da parte do rótulo, com `lower`, `upper` ou `capitalize`, sem tocar no número. `text` é uma substituição literal que troca qualquer rótulo calculado e tem precedência sobre `style` e `case`. As opções de renderização lado a lado: | Sintaxe | Renderiza | Observações | | --- | --- | --- | | `:ref{id="…"}` | `Fig. 1.7` | Estilo padrão: o `shortLabel` do tipo seguido do número, unidos por um espaço inseparável para que nunca se separem numa quebra de linha. | | `:ref{id="…" style="number"}` | `1.7` | Só o número calculado, sem rótulo. | | `:ref{id="…" style="full"}` | `Figure 1.7` | O `name` completo do tipo seguido do número. Use no início de uma frase ou onde a abreviatura soa mal. | | `:ref{id="…" case="lower"}` | `fig. 1.7` | Muda a caixa só do rótulo: `lower` (`fig. 1.7`), `upper` (`FIG. 1.7`) ou `capitalize` (primeira letra maiúscula). Combina com `style="full"` (`figure 1.7`); o número nunca é alterado, e um valor não reconhecido é ignorado. | | `:ref{id="…" text="see the plan"}` | `see the plan` | Uma substituição explícita. O texto dado é usado literalmente no lugar de qualquer rótulo calculado; útil para links na prosa como “como vimos antes”. Quando presente, `text` tem precedência sobre `style` e `case`. | Se um `:ref` (ou um `::resource`) indica um id sem recurso correspondente, o rótulo vira `?` (um rótulo `text=` é impresso em vez disso, ainda sem número nem link) e o Sandbox emite um aviso de **Recurso desconhecido**. O motor o registra como uma entrada `unknownResourceId` nos `contentWarnings` do documento, com o intervalo de origem e a página da referência; isso vale também para um `:ref` dentro de uma legenda, de uma nota ou de uma célula de tabela de um recurso que o texto usa. ### Numeração pela primeira referência O número de um recurso é atribuído **na primeira vez que ele é mencionado na ordem de leitura**, seja essa primeira menção uma inserção em bloco `::resource` ou um `:ref` em linha. A partir daí, toda referência ao mesmo id imprime esse mesmo número. Isso significa que os números seguem a ordem em que o leitor encontra os recursos, e não a ordem em que eles foram criados no painel: - Se você faz um `:ref` a uma figura na introdução e só a insere (`::resource`) duas páginas depois, ela continua com o número da introdução: a referência veio primeiro. - Inserir uma referência nova *mais cedo* no documento renumera automaticamente tudo o que vem depois. Não há numeração manual para manter em dia. A numeração é por tipo de recurso e respeita o escopo de reinício e o formato de contador de cada tipo; veja [Configuração › Tipos de recurso](https://postext.dev/pt/docs/configuration-resources.md#tipos-de-recurso) para os tokens de modelo (`{h1}`, `{n}`), `resetOn` e `counterFormat`. Só conta o que o texto referencia: um recurso que só um design desenha (um elemento de imagem de uma abertura de capítulo, por exemplo) não recebe número e deixa o contador como estava. E `{h1}` conta todo título de nível 1 cujo estilo não seja `numbered: false`, mesmo um cujo `numberingTemplate` esteja vazio, de modo que um artigo cujo único H1 é o título numera suas figuras como 1.1, 1.2… por padrão. [Configuração › O que é numerado](https://postext.dev/pt/docs/configuration-resources.md#o-que-é-numerado) traz as duas regras e as configurações para Figura 1, 2…. ### Posicionamento Cada recurso tem um **posicionamento** que decide onde o flutuante fica, resolvido por recurso (seu próprio `placement`), depois pelo `defaultPlacement` do tipo e depois pelo padrão embutido `auto` / `column`: | Campo | Valores | Significado | | --- | --- | --- | | `position` | `"auto"` · `"top"` · `"bottom"` · `"here"` | `"auto"` (o padrão) ocupa o primeiro espaço livre depois da referência, no topo ou no pé; `"top"` / `"bottom"` só aceitam espaços desse tipo; `"here"` desativa a flutuação e insere o recurso em linha na diretiva `::resource` (uma tabela posicionada aí é cortada entre linhas quando não cabe no resto da sua coluna; veja [Tabelas mais altas que a página](https://postext.dev/pt/docs/configuration-resources.md#tabelas-mais-altas-que-a-página)). | | `width`, `align` | `0 < width < 1`; `"left"` · `"center"` · `"right"` | Um recurso mais estreito que o seu espaço: `width` é a fração da largura da coluna (ou da página) que ele ocupa, `align` onde ele fica dentro do espaço (uma tabela pequena centralizada na coluna; uma faixa da largura da página cuja imagem ocupa uma coluna). Uma imagem mais estreita que o seu espaço (um bitmap menor que a coluna, ou um que `layout.fitFiguresToPage` reduziu) também fica ali conforme `align`, sob uma legenda que mantém a medida do espaço. Vale tanto para flutuantes quanto para inserções `::resource` em linha. | | `captionSide` | `true` · `false` | Num layout de coluna e meia cuja coluna lateral é reservada para flutuantes (`layout.sideColumnRole: 'floats'`), um flutuante `"column"` com `captionSide` mantém o corpo na coluna principal e compõe a legenda (e a nota) na coluna lateral, alinhada com o topo da figura, ou com o pé no caso de um flutuante no pé; a coluna lateral cede essa faixa. Uma página sem essa coluna mantém a legenda sob a figura. Desde o postext 1.28 um recurso posto no texto (`"here"`), de uma coluna, também o aceita: a legenda e a nota vão para a coluna lateral, na altura do topo do corpo, o bloco no texto tem a altura do corpo sozinho, e as figuras e boxes laterais compostos depois respeitam a legenda. Onde a coluna lateral está ocupada ao lado do recurso, a legenda fica sob o corpo; um recurso que passa para a coluna ou página seguinte decide de novo ali. Não dentro de um box, nem numa página vertical, nem numa imagem contornada pelo texto. `layout.inlineCaptionSide: false` deixa as legendas laterais só para os flutuantes de coluna. | | `span` | `"column"` · `"page"` | Ocupar uma única coluna, ou interromper o fluxo das colunas e ocupar a largura total do conteúdo, atravessando todas as colunas. Num layout de uma coluna, os dois são idênticos. | | `columns` | um número inteiro, padrão `1` | Numa página de várias colunas, um flutuante `"column"` que atravessa esse número de colunas adjacentes, medianizes incluídas: uma foto ocupando duas das cinco colunas de um jornal. Ele ocupa o topo de uma sequência de colunas vazias que começam niveladas, ou o pé da coluna que o cita e das colunas vazias depois dela. Tantas colunas quantas a página tem, ou mais, o transformam num flutuante que ocupa a página. É ignorado pelos spans `"page"` e `"side"`, por um recurso girado e por uma inserção em linha (`"here"`); `captionSide` só se aplica a um flutuante de uma coluna de largura. Desde o postext 1.18. | | `rotate` | `"ccw"` · `"cw"` | Compõe o recurso girado um quarto de volta: uma tabela em paisagem num livro em retrato. `"ccw"` o gira no sentido anti-horário, com o topo voltado para a borda esquerda da página (o leitor gira o livro no sentido horário), a convenção habitual; `"cw"`, no sentido contrário. Um recurso girado é sempre um flutuante que ocupa a página, numa página própria: ele é diagramado ao longo da altura da área de conteúdo, arredondada para baixo em linhas inteiras da grade de linhas de base e menos uma linha de corpo, o espaço de flutuante que toda faixa de flutuante mantém (uma mancha de 237 mm numa grade de 14 pt comporta 47 linhas, 232,1 mm, então o recurso recebe 46 delas, 227,2 mm); fica encostado na lombada quando as margens são espelhadas (à esquerda, caso contrário), e uma tabela larga demais para uma página é cortada entre linhas e continua, girada, nas páginas seguintes com o cabeçalho repetido, exatamente como uma tabela em pé mais alta que uma página. Uma figura girada é redimensionada para caber na página. Ignorado numa inserção em linha (`"here"`). | | `shrink`, `minScale` | `"never"` · `"page"` · `"slot"`; `0 < minScale ≤ 1`, padrão `0.7` | Reduz uma imagem flutuante (bitmap, SVG, o pôster de um vídeo), mantendo as proporções, ao espaço que uma posição tem, em vez de levá-la adiante. `"never"` (o padrão) a compõe no seu tamanho. `"page"` a reduz só quando ela é alta demais para a faixa de uma página nova: a área de conteúdo menos o que já ocupa essa página (uma abertura, outros flutuantes, notas de rodapé) e o espaço do flutuante, como uma prancha de catálogo ajustada à sua página. `"slot"` também a reduz para entrar numa posição da página que a cita, ou no espaço que sobra ao lado de outra faixa, se couber ali em `minScale` ou mais; caso contrário, segue adiante como antes. As posições são testadas na ordem de sempre, e a faixa continua terminando na grade de linhas de base. Uma imagem com área segura é recortada dentro dela antes de ser reduzida (veja [Área segura](https://postext.dev/pt/docs/document-format-resources.md#área-segura)). Numa página nova, onde não tem outro lugar para onde ir, uma imagem que não cabe nem em `minScale` é composta nessa escala e ultrapassa a faixa. A diagramação avisa cada flutuante reduzido com um aviso `floatShrunk`. Tabelas (que se dividem), caixas flutuantes, tiras de quadrinhos, recursos girados e inserções em linha nunca são reduzidos. O padrão do documento é `layout.floatShrink`. Desde o postext 1.24. | | `captionMeasure` | `"slot"` · `"body"` | A medida da legenda e da nota de uma imagem mais estreita que o seu espaço (reduzida, ou um bitmap menor que a coluna): `"slot"` (o padrão) mantém a medida do espaço; `"body"` as compõe tão largas quanto a imagem, embaixo dela conforme `align`, de modo que uma prancha centralizada leva a legenda centralizada embaixo. Vale para flutuantes e inserções em linha. Desde o postext 1.24. | | `wrap`, `wrapGap` | `"none"` · `"left"` · `"right"` · `"start"` · `"end"`; um comprimento | Compõe o texto ao lado do recurso: ele fica naquele lado da coluna, e as linhas ao lado são ajustadas à medida que sobra, a `wrapGap` da caixa dele (legenda incluída), e voltam à medida inteira embaixo. Vale para uma inserção em linha (`"here"`) e para um flutuante de uma coluna no alto ou no pé de uma coluna; flutuantes de página, de várias colunas, da coluna lateral e girados mantêm a faixa. O recurso ocupa `width` da coluna, ou `layout.wrap.defaultWidth` (0,45). `wrapGap` tem como padrão `layout.wrap.gap`, ou uma linha do corpo. Veja [Contorno de texto](https://postext.dev/pt/docs/document-format-resources.md#contorno-de-texto). Desde o postext 1.24. | | `citingPage` | `true` · `false`, padrão `false` | Deixa um flutuante `"top"` ou `"auto"` ocupar o topo da página (um flutuante na largura da página) ou da coluna (um flutuante de coluna, também na largura de `columns`) onde cai a linha que o cita pela primeira vez, como faz o posicionamento `t` do LaTeX, em vez do primeiro espaço livre depois dessa linha. O texto acima da referência desce para baixo do flutuante. Só faz isso quando o flutuante cabe ali dentro de `layout.maxTopFraction` da coluna (0,7 por padrão), quando os flutuantes anteriores da sua sequência de numeração já estão posicionados, quando nenhuma quebra explícita abre a página (a primeira página de um capítulo, uma parte, um `:::pagebreak`) e nada na largura da página fica acima da linha que o cita, e quando, assim posicionado, a linha que o cita continua caindo nessa página (numa coluna que o flutuante encabeça); senão, o flutuante ocupa o seu espaço habitual. Flutuantes girados, os da coluna lateral e o resto de uma tabela dividida entre páginas nunca se movem assim. Padrão: o `defaultPlacement` do tipo e depois `layout.floatsAtCitingPage`. Desde o postext 1.25. | Um flutuante vai para o **primeiro espaço livre depois da sua primeira referência**, na ordem de leitura: o pé da coluna em que está a referência, depois o topo e o pé da próxima coluna vazia da mesma página, depois as faixas da próxima página que o fluxo abre (um flutuante que ocupa a página fica no pé da página quando todas as colunas ainda têm espaço para ele; caso contrário, numa faixa da página seguinte). Uma página aberta por uma figura ou tabela em linha também conta: um flutuante à espera dessa página ocupa o topo dela, acima da figura ou tabela, quando os dois cabem nela; quando não cabem, a figura ou tabela fica com a página e o flutuante espera a seguinte. Até o postext 1.4, essa página era pulada, e o flutuante esperava a página depois dela mesmo quando os dois cabiam. Ele é composto no seu tamanho, a menos que o seu `shrink` o deixe reduzir-se ao espaço de uma posição (veja a tabela acima), e nunca fica antes da sua referência. Os flutuantes de uma mesma sequência de numeração aparecem na ordem das referências: uma figura que não cabe em lugar nenhum de uma página segura as figuras que vêm atrás dela (uma tabela à espera não segura uma figura, nem o contrário), de modo que a figura 12 nunca aparece antes da figura 11. Uma tabela que, sem isso, teria de esperar é cortada: quando lhe é oferecido o topo de uma coluna vazia, ela ocupa as linhas que cabem e continua no espaço seguinte (a coluna ao lado ou a próxima página), com as linhas de cabeçalho repetidas (veja `tableStyle.overflow`). Um flutuante `top` ou `auto` com `citingPage` ligado pode, em vez disso, encabeçar a página (ou a coluna) onde cai a linha que o cita, e o texto acima da referência desce para baixo dele: fica pintado acima da sua referência na mesma página, nunca numa anterior, e num PDF etiquetado e no HTML continua sendo lido depois dela. O motor resolve isso em algumas passadas a mais e só o mantém enquanto a linha que o cita continuar nessa página. Os flutuantes nunca escapam do seu capítulo: numa abertura de capítulo (um nível de título com `breakBefore` ou `span: 'page'`), num `:::part`, num estilo de boxe com `floatBarrier: true` (o boxe de “pontos-chave” que fecha um capítulo) e no fim do documento, todo flutuante ainda pendente é posicionado antes, nos espaços livres da página ou em páginas abertas antes da fronteira. Um flutuante citado pela primeira vez pela própria abertura (um título de capítulo que nomeia sua figura), ou pelo primeiro bloco depois de um `:::part`, pertence ao capítulo novo: ele fica depois dessa linha, como qualquer outro. Uma figura ou tabela que pediu o topo de uma página pode então ocupar o pé da página de fechamento do capítulo, sob as colunas balanceadas, em vez de uma página só para ela. Um `:::pagebreak` simplesmente manda os flutuantes pendentes para a página que vem depois dele. Sob uma abertura de largura de página composta sobre duas ou mais colunas de texto, a coluna da própria abertura conta como vazia no topo enquanto nada vem depois da abertura nela: um boxe flutuante colocado logo depois da abertura, ou um recurso incorporado ali com `::resource`, ocupa o topo da primeira coluna, sob a abertura e na altura dos topos das outras colunas (em várias colunas a partir dela com `columns`), e o texto da coluna começa abaixo dele. Um flutuante citado no texto continua indo depois da linha que o cita. Até o postext 1.24 a primeira coluna não oferecia esse espaço e o flutuante caía a partir da segunda; `layout.floatsUnderOpener: false` mantém isso (veja [Configuração › Layout](https://postext.dev/pt/docs/configuration-page-layout.md#diagramação)). Os boxes laterais (`span="side"`) também não saem do seu capítulo. Um boxe que não cabe na coluna lateral da sua página ocupa a da página seguinte; se o capítulo, ou o documento, termina antes, cada boxe ainda à espera é composto na coluna lateral de uma página aberta depois do texto, na ordem dos seus delimitadores, e uma figura lateral citada depois deles fica atrás. Essa página não tem texto, então a diagramação avisa de cada boxe e figura que está nela (`afterText`). Um boxe mais alto que uma coluna lateral vazia é composto mesmo assim e avisado (`calloutOverflow`), e o que ainda assim não encontra página também é avisado (`unplaced`) em vez de sumir. Até o postext 1.24 só a primeira dessas páginas era aberta e os boxes restantes se perdiam sem aviso. As faixas de flutuantes são corrigidas em relação à grade de linhas de base para que o texto em volta mantenha o ritmo vertical da página inteira. Uma faixa **no topo** aumenta sua margem inferior até a próxima linha da grade, de modo que o texto abaixo do flutuante continua alinhado com as colunas vizinhas e com a página oposta. Um flutuante **no pé** é ancorado de modo que a última linha da legenda compartilhe uma linha de base com a última linha de texto das outras colunas (um conteúdo sem legenda alinha sua borda inferior à última posição da grade); as páginas cheias, portanto, terminam na mesma altura entre colunas e entre páginas opostas. Na página de fechamento de um capítulo, e do documento, nada vem depois das figuras e tabelas de página inteira compostas abaixo da última faixa de texto, então elas sobem para ficar a um espaço de flutuante abaixo dela, empilhadas na sua ordem, em vez de deixar um vazio entre o texto e uma figura no pé da página. Isso vale também para um flutuante `position: 'bottom'`. Para mantê-las no pé, como em todas as outras páginas, defina `layout.hugClosingFloats: false` (veja [Configuração › Layout](https://postext.dev/pt/docs/configuration-page-layout.md#diagramação)). Páginas com coluna lateral nunca as movem. Os três renderizadores (a visualização no canvas, o visualizador HTML e a saída PDF) renderizam recursos. No renderizador HTML, os dados das imagens ficam fora do documento, então o host os fornece pela opção de resolvedor `resourceImageUrl(fileId)`; quando o resolvedor está ausente (ou não retorna nada para um arquivo), o recurso é renderizado como uma caixa neutra de marcação para que o layout fique estável. O arquivo de um vídeo chega do mesmo modo por `resourceVideoUrl(fileId)` (veja [Vídeos](https://postext.dev/pt/docs/document-format-resources.md#vídeos)). #### Onde um flutuante pode ficar “Nunca antes da sua referência” se conta a partir da linha que cita o flutuante: o flutuante espera até essa linha ser composta e ocupa o primeiro espaço livre depois dela na ordem de leitura; o topo da página em que a linha é composta vem antes dela. Um flutuante lateral (`span: 'side'`, na coluna lateral reservada a flutuantes de um layout de coluna e meia) é a exceção: ele se empilha na coluna lateral ao lado do texto que o cita, e pode ficar mais acima na página que a linha que o cita. Para uma figura citada na página 5: | Posicionamento | Na página 5 | Caso contrário | | --- | --- | --- | | `top`, `span: 'page'` | Nunca: a faixa no topo da página fica acima da linha que cita. | A faixa superior da página 6. | | `top`, `span: 'column'` | O topo de uma coluna posterior que ainda está vazia: citada na primeira de duas colunas, pode abrir a segunda. | O topo de uma coluna da página 6. | | `auto` ou `bottom`, `span: 'page'` | A faixa do pé da página 5, quando todas as colunas ainda têm espaço para ela. | Uma faixa da página 6. | | `auto` ou `bottom`, `span: 'column'` | O pé da coluna que cita; depois o pé (qualquer um dos dois) ou o topo (só `auto`) de uma coluna vazia posterior. | Página 6. | - Uma página de abertura de capítulo segue as mesmas regras: um flutuante `auto` ou `bottom` que ocupa a página, citado no primeiro parágrafo da abertura, pode ocupar a faixa do pé dessa página, sob o texto; um `top` abre a página seguinte. Para ter a imagem na página que a cita, use `auto` ou `bottom`, ou desenhe-a como um elemento de imagem do design da abertura. - Dois flutuantes de coluna citados no mesmo parágrafo ocupam os dois espaços seguintes: normalmente o primeiro fica no pé da coluna que cita, o segundo no topo da próxima coluna vazia, lado a lado na página. - Num layout de uma coluna, um flutuante que ocupa a página é um flutuante de coluna, e valem as mesmas regras: um flutuante `top` citado numa página fica no topo da seguinte. - Um parágrafo que passa de uma página para a outra também conta a partir da linha que cita. Quando o parágrafo começa no pé da página 5 e a referência cai na página 6 (ou o parágrafo inteiro vai para a página 6, porque não cabem linhas suficientes dele no pé da página 5), a referência está na página 6: um flutuante `top` abre a página 7, e um `auto` ocupa o pé da página 6 quando há espaço para ele. O mesmo vale entre as colunas de uma página, e para um boxe dividido entre páginas: uma figura que a segunda parte dele cita espera por essa parte. - **Mudou no postext 1.5.** Até o postext 1.4, um flutuante entrava na fila quando o layout chegava ao parágrafo que o cita, de modo que a página para onde esse parágrafo continuava (ou para onde ia) podia abrir com o flutuante, acima da linha que contém a referência. Uma figura assim agora fica uma página depois, ou no pé da página quando pede `auto`; o número de páginas pode mudar. ### Contorno de texto Uma imagem, uma tabela ou uma caixa mais estreita que a coluna pode ficar de um lado dela com o texto composto ao lado, como numa revista ou num boletim. Dê ao posicionamento um lado de `wrap` e, se quiser, um `width`: ```json { "id": "bed", "typeId": "figure", "kind": "svg", "caption": "O novo canteiro.", "placement": { "position": "here", "wrap": "right", "width": 0.4 } } ``` - **Em linha (`"here"`).** O recurso fica do seu lado da coluna, com o topo na altura do topo da linha seguinte à linha `::resource`, e os parágrafos, citações e itens de lista que vêm depois são compostos ao lado dele na medida que sobra, e depois embaixo na medida inteira. Um parágrafo que começa ao lado e termina embaixo continua sendo um parágrafo só: sem quebra nem espaço extra no pé da imagem. Todas as linhas ficam na grade de linhas de base; o espaço sob a imagem é o afastamento arredondado para linhas inteiras da grade. - **Um flutuante de coluna.** Um flutuante `span: "column"` de uma coluna de largura, no alto (`"top"`, ou `"auto"` no alto de uma coluna) ou no pé (`"bottom"`, `"auto"`) de uma coluna, é posto na sua faixa como qualquer flutuante; as primeiras linhas da coluna, ou as últimas, são então compostas ao lado dele. Numa página de duas colunas o flutuante pertence à sua coluna, e a outra corre na largura toda. - **Uma caixa.** Um `:::callout` aceita os mesmos ajustes como atributos: `:::callout{wrap="right" width=0.4}` põe um olho ou um quadro onde ele aparece, com o texto seguinte ao lado, e `placement="top"` ou `"bottom"` com `wrap` faz a caixa flutuar para o alto ou o pé de uma coluna. Uma caixa contornada é composta inteira e nunca se divide. - **O que vai embaixo.** Um título, uma fórmula em destaque, uma figura ou tabela, uma caixa e um poema não são compostos ao lado de um elemento contornado: vão embaixo dele, e o branco ao lado acima deles fica vazio. Sair da coluna (o pé, um `:::columnbreak`, uma quebra de página) termina ali o contorno: o elemento pertence à sua coluna. Quando o bloco logo depois de um recurso em linha não pode ir ao lado dele, o recurso ocupa a faixa, como sem `wrap`. - **Afastamento e limites.** `wrapGap` (ou `layout.wrap.gap`, ou uma linha do corpo) separa o elemento, legenda incluída, do texto ao lado e do texto embaixo. Se o texto ao lado ficasse mais estreito que `layout.wrap.minTextWidth` (12 em do corpo), ou o elemento fosse mais baixo que `layout.wrap.minLinesBeside` linhas (2), ele ocupa a faixa inteira e um aviso `textWrap` informa. Um em linha alto demais para o espaço que resta na coluna passa para a seguinte com a âncora, com o mesmo aviso. - **Lados.** `left` e `right` são lados do fluxo do texto, como em `align`: num livro da direita para a esquerda `left` é a direita da folha. `start` e `end` nomeiam os mesmos lados. - **Saídas.** O canvas, o visualizador HTML, o PDF e o EPUB de layout fixo compõem as linhas como foram diagramadas; um PDF etiquetado lê a imagem ou a caixa antes do parágrafo que vai ao lado. Um EPUB refluível faz o elemento flutuar para o seu lado com CSS, na mesma proporção da largura do texto. - **Ainda não.** Texto dos dois lados de uma imagem, contorno pela forma, contorno dentro do conteúdo de uma caixa e contorno na escrita vertical (o elemento mantém a faixa, com um aviso). Colunas com um elemento contornado ficam fora do balanceamento de colunas. ### Tamanho do bitmap Um bitmap declara os seus pixels: `bitmap.width` e `bitmap.height` são as contagens de pixels do arquivo, não um tamanho de impressão. Quantos deles vão numa polegada decide o tamanho com que a imagem é composta antes que o seu espaço a limite. Há três maneiras de dimensioná-la: - **Os seus pixels ao dpi da página** (o padrão). Sem resolução, um pixel da imagem é um pixel da diagramação (`page.dpi`, 300 se não for definido): uma fotografia de 2400 px tem 8 pol (203,2 mm) de largura numa página de 300 dpi, e o dobro numa de 150. - **Uma resolução.** `bitmap.resolution` é o ppi da imagem no seu tamanho natural de impressão, então a sua largura natural é `width × page.dpi / resolution` numa página de qualquer dpi: 2400 px com `resolution: 300` têm 203,2 mm de largura numa página diagramada a 150 dpi ou a 300. `layout.bitmapResolution` dá uma resolução a todo bitmap que não tem uma própria: um número (`300`), ou `'file'`, a resolução que o arquivo informa (`bitmap.fileResolution`: o `pHYs` de um PNG, a densidade JFIF ou EXIF de um JPEG, o EXIF de um WebP; numa imagem importada do Word, o tamanho com que o Word a imprimia). Câmeras, capturas de tela e exportações para a web costumam informar 72 ou 96 ppi quando não sabem nada do tamanho de impressão, por isso, com `'file'`, esses dois valores contam como não informados e a imagem mantém os seus pixels ao dpi da página; um 72 declarado no próprio recurso vale como está escrito. `'document'`, o padrão, é a primeira maneira. - **Uma parte da coluna.** `placement.width` estreita um flutuante ou uma inserção em linha a uma fração da sua coluna (ou página), e uma imagem maior que essa parte é reduzida a ela, sejam quais forem os seus pixels (veja [Posicionamento](https://postext.dev/pt/docs/document-format-resources.md#posicionamento)). Em todos os casos o espaço limita a imagem, mantendo as suas proporções, e uma imagem menor nunca é ampliada. O mesmo tamanho natural vale para uma imagem numa célula de tabela e para o elemento `image` de um design com tamanho `'auto'`. O PDF incorpora o arquivo como ele é, no tamanho em que foi colocado. O [preflight](https://postext.dev/pt/docs/configuration-fonts-colors-viewers.md#preflight) verifica a resolução com que cada imagem é impressa, e o [painel Recursos](https://postext.dev/pt/docs/sandbox.md#painel-recursos) do Sandbox a mostra para cada imagem. Desde o postext 1.24. ```json { "id": "harbour", "typeId": "figure", "kind": "bitmap", "caption": "The harbour at dawn.", "bitmap": { "fileId": "harbour.jpg", "format": "jpeg", "width": 2400, "height": 1600, "resolution": 300 } } ``` `bitmapInfo(bytes)` (de `postext` e `postext/bundle`) lê os pixels de um arquivo e a resolução que ele informa, `{ width, height, resolution?: { x, y, source } }`; um pacote aberto com `'file'` preenche `fileResolution` com ela, e o Sandbox a guarda para cada imagem que você envia. ### Área segura Um recurso bitmap ou SVG pode marcar uma **área segura**: o retângulo da imagem que contém o que importa (uma pessoa e uma faixa da paisagem atrás dela, a parte com o gráfico de um diagrama) e que sempre é mostrado. É o `safeArea` do recurso, quatro frações (0–1) do tamanho intrínseco da imagem, medidas a partir do canto superior esquerdo: `x` e `width` são frações da largura, `y` e `height` da altura. O nome diz o que precisa ser mantido; uma caixa de recorte diria onde cortar. ```ts const harbour: Resource = { id: 'harbour', typeId: 'figure', kind: 'bitmap', caption: 'The harbour at dawn.', createdAt: 0, updatedAt: 0, bitmap: { fileId: 'harbour.jpg', format: 'jpeg', width: 2400, height: 1600 }, // os barcos e o cais: 18–68 % da largura, 25–85 % da altura safeArea: { x: 0.18, y: 0.25, width: 0.5, height: 0.6 }, }; ``` Só uma imagem com área segura é recortada. O motor pode então mostrá-la em qualquer proporção entre a imagem inteira e a área segura: mais alta que a proporção da própria imagem, cortando as laterais, no máximo até a largura da área segura, ou mais baixa, cortando em cima e embaixo, no máximo até a altura dela. A largura da figura nunca muda, só a altura. O que fica fora da área segura é cortado dos dois lados em proporção às margens ali, de modo que um motivo à esquerda do centro continua à esquerda do centro. Composto com 60 mm de largura, o porto acima tem 40 mm de altura quando inteiro, e pode ser mostrado com qualquer altura entre 24 mm (cortado em cima e embaixo até 60% da altura) e 80 mm (as laterais cortadas até metade da largura). Valores além das bordas da imagem são limitados a elas; uma área com um valor que não é número, ou um lado menor que 2% da imagem, ou que cobre a imagem inteira, é ignorada, assim como o campo numa tabela. Sem área segura, uma imagem é sempre mostrada inteira, como antes. O motor usa essa margem em quatro lugares: - **O espaço que resta numa coluna.** Uma imagem em linha (`position: 'here'`) um pouco alta demais para o espaço que resta na sua coluna, inclusive uma cuja legenda passaria do pé da página, é recortada dentro da sua área segura para ficar ali, em vez de seguir para a próxima coluna ou página e deixar esta curta. - **Páginas mais baixas que a figura.** Com `layout.fitFiguresToPage`, uma imagem alta demais para a página é primeiro recortada dentro da sua área segura, mantendo a largura, e só é reduzida se ainda estiver alta demais (veja [Configuração › Layout](https://postext.dev/pt/docs/configuration-page-layout.md#diagramação)). - **Faixas mais baixas que a figura.** Um flutuante que o `placement.shrink` reduz ao espaço da sua posição é primeiro recortado dentro da sua área segura, mantendo a largura, e só depois reduzido; a alavanca `flexFigure` abaixo nunca o faz crescer além desse espaço. - **Balanceamento de colunas.** Uma imagem com área segura composta em linha numa coluna curta, ou flutuando no topo ou no pé dessa coluna sobre essa coluna apenas, cresce em linhas inteiras da grade de linhas de base para preencher as linhas vazias da coluna. Uma imagem mais alta não deixa buraco visível, então esse recurso de ajuste, `flexFigure`, é tentado logo depois do boxe que fecha a coluna e antes de qualquer espaço ser acrescentado acima dos títulos ou depois das listas. Um flutuante no topo de uma coluna na página de fechamento de um capítulo ou numa faixa de fechamento não cresce, já que esses topos de coluna ficam nivelados (veja [Configuração › Balanceamento de colunas](https://postext.dev/pt/docs/configuration-page-flow.md#equilíbrio-de-colunas)). A VDT registra o recorte no bloco do recurso: `bodySource` é a parte da imagem mostrada em `bodyRect`, nas mesmas frações (ausente quando a imagem inteira o preenche), e `bodyFlex` dá os px que o corpo ainda poderia encolher e crescer e os px em que os ajustes já o alteraram (`{ shrink, grow, delta }`). A visualização no canvas e o PDF recortam no corpo e desenham a imagem inteira no tamanho sem recorte; o visualizador HTML e o EPUB de layout fixo compõem a imagem com `object-fit: cover` e um `object-position` correspondente; um EPUB refluível, que não tem página a preencher, mostra a imagem inteira. Um host que desenha as imagens por conta própria pode usar as funções auxiliares que o `postext` exporta: `resourceSafeArea` e `normalizeSafeArea` (a área como o motor a lê, ou `undefined`), `safeAreaHeightRange` (o corpo mais baixo e o mais alto numa dada largura), `safeAreaSource` (a parte mostrada numa dada altura) e `uncroppedPictureBox` (onde desenhar a imagem inteira antes de recortar), com o tipo `ResourceSafeArea`. No Sandbox, o campo é **Área segura**, numa imagem do [painel Recursos](https://postext.dev/pt/docs/sandbox.md#painel-recursos). A receita Nº 116 das Receitas, [Fotos que crescem para preencher uma coluna curta](https://postext.dev/pt/cookbook/photos-fill-short-columns.md), compõe uma reportagem de revista em duas colunas duas vezes, sem e com áreas seguras, para que você compare as páginas lado a lado. ### Âncoras de falante e zonas a evitar Uma imagem que é a arte de um quadro de quadrinhos também pode dizer onde estão as personagens, para o letreiramento (veja [Quadrinhos](https://postext.dev/pt/docs/document-format-directives.md#quadrinhos)). `anchors` lista um ponto por falante e `avoid` as regiões que nenhum balão cobre, ambos em frações da imagem, como a área segura: ```ts const radio: Resource = { id: 'lh-radio', typeId: 'figure', kind: 'bitmap', createdAt: 0, updatedAt: 0, bitmap: { fileId: 'lh-radio.jpg', format: 'jpeg', width: 1000, height: 1000 }, safeArea: { x: 0, y: 0.36, width: 0.62, height: 0.56 }, anchors: [ // o faroleiro: boca, cabeça (para balões de pensamento) e rosto { id: 'tomas', x: 0.345, y: 0.52, head: { x: 0.38, y: 0.44 }, face: { x: 0.29, y: 0.4, width: 0.16, height: 0.18 } }, ], avoid: [{ x: 0, y: 0.44, width: 0.22, height: 0.26 }], // o rádio }; ``` O `id` de uma âncora é a chave de falante do roteiro (`tomas: …`), ou `sfx` para o ponto onde se reúnem as onomatopeias do quadro; `x` e `y` são a boca para onde aponta o rabicho de um balão de fala, `head` o ponto para onde apontam as bolinhas de um balão de pensamento (a boca, quando não definido) e `face` um retângulo que nenhum balão cobre. O motor projeta cada ponto pelo recorte e pelo espelhamento do quadro, de modo que um rabicho continua no seu falante seja qual for a forma do quadro; uma âncora fora da área segura gera `comicAnchorOutsideSafeArea`, porque um recorte pode cortá-la. As âncoras pertencem à imagem e servem a todas as traduções dos quadrinhos. Uma terceira lista, `faces`, guarda os rostos de quem não fala, como retângulos iguais aos de `avoid`: nenhum balão os cobre, enquanto uma zona a evitar cede quando o quadro não tem outro lugar. Só os quadros de quadrinhos as leem; uma figura as ignora. No Sandbox, elas são marcadas no diálogo **Área segura e letreiramento** do [painel Recursos](https://postext.dev/pt/docs/sandbox.md#painel-recursos). ### Vídeos Um recurso de **vídeo** (`kind: 'video'`) é um vídeo do YouTube ou do Vimeo, ou um vídeo seu: um arquivo guardado no livro (MP4, WebM) ou um que está num endereço da web, seja um arquivo num servidor ou um **stream HLS** (uma playlist `.m3u8`). Ele é posicionado, legendado, flutuado e citado como uma imagem, e numerado numa sequência própria: o tipo embutido `video` imprime *Vídeo 1.1*, *Vídeo 1.2*… ao lado de *Figura 1.1* e *Tabela 1.1* (veja [Configuração › Tipos de recurso](https://postext.dev/pt/docs/configuration-resources.md#tipos-de-recurso)). Cada saída o mostra como pode: | Saída | O que mostra | | --- | --- | | Canvas, PDF | O **pôster**, um quadro do vídeo, com uma marca de reprodução e um código QR que abre o vídeo ([Configuração › Estilo de vídeo](https://postext.dev/pt/docs/configuration-resources.md#estilo-de-vídeo)). No PDF, o pôster também é um link para o vídeo. | | Folio | O pôster, tal como impresso. Um clique nele reproduz o vídeo **na própria página**, e ele continua tocando enquanto a folha vira (veja [Vídeos nas páginas do Folio](https://postext.dev/pt/docs/document-format-resources.md#vídeos-nas-páginas-do-folio) mais abaixo). Os vídeos do YouTube e do Vimeo continuam sendo pôsteres. | | Visualizador HTML | O **player** do vídeo: o do YouTube ou do Vimeo, ou o player HTML5 do navegador para um arquivo ou um endereço. Um stream HLS toca nativamente no Safari e nas versões recentes do Chrome; nos demais, o host anexa um player como o hls.js, como faz o Sandbox. Com `videoStyle.html: 'poster'`, mostra o pôster impresso no lugar do player. | | EPUB | Um arquivo toca no player do próprio sistema de leitura, empacotado no livro ou lido do seu endereço de produção. Um vídeo do YouTube ou do Vimeo é o seu pôster, com link para o vídeo: um EPUB não pode incorporar o player de uma página da web. Um stream HLS também é o seu pôster com link: uma playlist HLS não é um tipo de mídia que um EPUB possa reproduzir. Onde o sistema de leitura executa scripts, os arquivos de uma mesma página ou capítulo respeitam `player.exclusive`: iniciar um pausa os outros com os quais ele não toca junto. | ```ts const talk: Resource = { id: 'keeper-talk', typeId: 'video', kind: 'video', caption: 'The keeper explains the lamp.', altText: 'A lighthouse keeper beside the lamp', createdAt: 0, updatedAt: 0, video: { source: 'youtube', // 'youtube' | 'vimeo' | 'file' url: 'https://youtu.be/aqz-KE-bpKQ', poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 }, start: 30, // toca a partir de 0:30; o link impresso também começa aí }, }; ``` O texto cita um vídeo como cita uma figura: `:ref{id="keeper-talk"}` imprime *Vídeo 1.1* e faz o pôster flutuar para o primeiro espaço livre depois da referência, e `::resource{id="keeper-talk"}` com `placement.position: 'here'` o coloca no fluxo do texto. Os campos de `Resource.video` (`ResourceVideo`): | Campo | Tipo | Significado | | --- | --- | --- | | `source` | `'youtube'` · `'vimeo'` · `'file'` | De onde o vídeo é reproduzido: uma página do YouTube ou do Vimeo, ou um vídeo seu (`'file'`), enviado ou num endereço. | | `url` | `string` | YouTube ou Vimeo: o endereço do vídeo, em qualquer forma (uma página de exibição, `youtu.be`, Shorts, um link de incorporação, `youtube-nocookie.com`; uma página do Vimeo, uma página de canal ou um link não listado com o seu hash). Um arquivo: o seu **endereço de produção**, onde o livro publicado vai encontrá-lo. Um vídeo seu sem arquivo próprio toca a partir desse endereço: um MP4 ou WebM num servidor, ou um stream HLS (`…/master.m3u8`). | | `fileId`, `format` | `string` | Um arquivo: o vídeo enviado, guardado à parte como um bitmap, e o seu formato: `'mp4'`, `'webm'`, `'ogv'`, `'mov'`, ou `'hls'` para um stream HLS. Sem formato, a extensão do endereço o indica (`.m3u8` é `'hls'`); se não, `'mp4'`. | | `poster` | `{ fileId, format, width, height }` | O quadro do pôster, um bitmap. | | `width`, `height`, `duration` | `number` | O tamanho do quadro do vídeo em px (a sua proporção quando não há pôster) e a duração em segundos. | | `posterTime` | `number` | O segundo do arquivo cujo quadro serve de pôster, guardado para poder ser escolhido de novo. | | `start`, `end` | `number` | Reproduz de `start` a `end` segundos. O código QR e o link do PDF também começam em `start`. | | `player` | `VideoPlayerOptions` | As opções de player deste vídeo, aplicadas por cima de `videoStyle.player`. | **O pôster.** Ele é composto na medida do seu espaço (ou na fração `placement.width` dela), na sua própria proporção, seja qual for o seu tamanho em pixels: um quadro do tamanho de uma tela é ampliado em vez de sair impresso pequeno. Como um bitmap, pode ter uma [área segura](https://postext.dev/pt/docs/document-format-resources.md#área-segura) e seguir `placement.align`. Um vídeo sem pôster imprime uma caixa escura na proporção do vídeo (16:9 quando nada a indica) com as suas sobreposições e gera um aviso de conteúdo `videoWithoutPoster`. No Sandbox, o pôster de um vídeo do YouTube ou do Vimeo é buscado na plataforma quando o endereço é digitado, e o de um arquivo é um quadro que você escolhe no vídeo. **O endereço.** O código QR e o link do PDF abrem a página do vídeo, `https://youtu.be/` ou `https://vimeo.com/`, a partir de `start`. Um arquivo não tem página: eles abrem o seu endereço de produção, que é também de onde toca um vídeo sem arquivo próprio (um MP4 num servidor, um stream HLS). Sem endereço, a impressão fica sem código QR e sem link (`videoWithoutUrl`), e uma saída HTML ou EPUB que não carrega o arquivo mostra o pôster. Um endereço do YouTube ou do Vimeo que não aponta para nenhum vídeo da plataforma gera `videoUrlInvalid`; o pôster aparece no lugar de um player. **Os players.** As opções de player (controles, botão de download, tela cheia, menu de velocidade, picture-in-picture, transmissão para outra tela, reprodução automática, início sem som, repetição, pré-carregamento, incorporações com privacidade reforçada) são definidas para o livro inteiro em `videoStyle.player` e para um vídeo em `video.player`; cada player respeita o que consegue (veja [Configuração › Estilo de vídeo](https://postext.dev/pt/docs/configuration-resources.md#estilo-de-vídeo)). O renderizador HTML recebe a URL reproduzível de um arquivo pela opção `resourceVideoUrl(fileId)`, assim como recebe as imagens por `resourceImageUrl`, e na falta dela usa o endereço de produção. A sua opção `videos: { files, streams, hls }` escolhe entre player e pôster por origem, por cima de `videoStyle.html` (`hls`, um vídeo reproduzido a partir de um endereço HLS, segue `files` se não for definido); o gerador de EPUB a utiliza. Um `