> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.

# SVG no Typst: insira a arte e confira a figura

> Insira SVG no Typst com funções nativas image e figure. Confira tamanho, legendas, alinhamento inline e o PDF exportado antes de entregar seu documento.

Source: https://perfectvector.com/pt-BR/blog/svg-in-typst

Language: pt-BR
Author: Irene Kim
Published: 2026-09-14T08:00:00+09:00

Para incluir um SVG no Typst, passe seu caminho de arquivo para `image`. Envolva-o em `figure` quando precisar de legenda e número, ou em `box` quando ele fizer parte de uma frase. SVG é um formato de entrada compatível; você não precisa converter um SVG simples para PDF apenas para inseri-lo. A [referência oficial de image](https://typst.app/docs/reference/visualize/image/) documenta essas opções.

A verificação útil vem depois que ele aparece: a arte está completa, a legenda é texto nativo do documento e a versão pequena ainda comunica sua forma? Este passo a passo usa um motivo original semelhante a uma célula para separar essas perguntas. Ele é uma ilustração, não um modelo biológico nem um espécime medido.

## Mantenha a arte e o texto do documento separados

Comece com um SVG sem texto e um pequeno arquivo Typst na mesma pasta. Isso remove uma fonte de confusão: uma mudança na tipografia do documento não pode ser confundida com uma mudança em letras incorporadas à arte.

Salve este motivo como `cell.svg`:

```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 160">
  <rect x="20" y="20" width="200" height="120" rx="40"
    fill="#e5f5ed" stroke="#197c70" stroke-width="6"/>
  <circle cx="100" cy="80" r="27" fill="#e89173"/>
  <circle cx="100" cy="80" r="9" fill="#263b60"/>
  <path d="M150 52C172 42 193 62 178 76C164 91 146 72 150 52Z"
    fill="#197c70"/>
</svg>
```

O arquivo tem um limite externo arredondado, um círculo coral com centro escuro e uma forma verde separada. Esses são os detalhes a comparar após a inserção. Não há valores de eixos, rótulos, barras de escala nem fotografias incorporadas a reconstruir.

Para uma ilustração científica existente, mantenha um mestre editável e uma cópia de entrega. Se o mestre é um gráfico numérico, regenere sua exportação a partir da ferramenta de plotagem e dos dados de origem. Não vetorize os pixels plotados para recuperar valores de pesquisa. Para um esboço simples que precisa de limpeza de formas, o [guia de preparação de arte linear](https://perfectvector.com/pt-BR/blog/line-art-to-svg) aborda essa tarefa anterior.

![Ilustração que mostra o mesmo motivo simples de célula como arte SVG, dentro de uma figura de documento com legenda e como pequeno marcador inline](https://perfectvector.com/blog/svg-in-typst/artwork-figure-inline.webp)

*Ilustração: a arte fornece as formas; o documento fornece a legenda, a referência e o posicionamento inline.*

## Insira o SVG em uma figura nativa

Salve isto como `main.typ` ao lado do SVG:

```typst
#set page(paper: "a5", margin: 18mm)
#set text(size: 11pt)

= A schematic cell

The drawing in @fig-cell is an illustrative motif, not a measured specimen.

#figure(
  image(
    "cell.svg",
    width: 70%,
    alt: "Rounded cell outline with a circular center and a separate curved interior shape.",
  ),
  caption: [A simplified cell motif, not drawn to scale.],
) <fig-cell>

Inline marker: #box(
  baseline: 20%,
  image("cell.svg", height: 1em, alt: "Cell motif"),
) next to the word cell.
```

A figura agrupa a imagem com sua legenda. O rótulo `<fig-cell>` nomeia essa figura, e `@fig-cell` a referencia no parágrafo. Mantenha esse identificador único no documento. A [documentação de figure do Typst](https://typst.app/docs/reference/model/figure/) explica legendas e numeração; a [documentação de referências](https://typst.app/docs/reference/model/ref/) explica referências baseadas em rótulos.

Essa organização permite revisar a legenda sem reabrir a ilustração. Ela também evita digitar um número de figura no SVG e depois descobrir que o documento renumerou suas figuras.

O `alt` da imagem descreve seu conteúdo visível. Para esta figura de uma única imagem, coloque essa descrição na imagem, como [recomenda a documentação de image](https://typst.app/docs/reference/visualize/image/). A legenda tem outra função: ela diz ao leitor como interpretar o motivo. Nenhum dos campos torna completa uma explicação científica incompleta; escreva a descrição adequada à ilustração real.

## Defina um tamanho que preserve o desenho inteiro

O exemplo principal define uma dimensão, `width: 70%`. Comece com uma largura que caiba na área de texto ao redor e inspecione o resultado no modelo real. Uma coluna estreita e uma página inteira dão espaços diferentes à mesma arte.

Se precisar especificar largura e altura, deixe explícito o comportamento de ajuste. O Typst define três escolhas em sua [referência de fit de image](https://typst.app/docs/reference/visualize/image/#parameters-fit): `contain` mantém a imagem inteira sem alterar sua proporção, `cover` preenche a área recortando, e `stretch` altera as proporções para preenchê-la.

Para este motivo, uma área de 8 cm por 3 cm é deliberadamente mais larga que a tela original. Esta comparação torna a escolha visível:

```typst
#set page(paper: "a5", margin: 18mm)

= Fixed-area comparison

Contain:
#image("cell.svg", width: 8cm, height: 3cm, fit: "contain")

Cover:
#image("cell.svg", width: 8cm, height: 3cm, fit: "cover")

Stretch:
#image("cell.svg", width: 8cm, height: 3cm, fit: "stretch")
```

Use o limite arredondado e o círculo central como verificações visuais. Um limite cortado indica que algo foi recortado. Um oval onde a imagem original tinha um círculo indica que as proporções mudaram. Espaço extra ao redor de um desenho completo pode ser aceitável; arte ausente geralmente exige uma decisão editorial deliberada.

Não compense uma área de desenho inadequada no arquivo original alterando repetidamente as dimensões da página. Se o SVG tem espaço vazio excessivo, corrija primeiro sua tela no mestre, substitua a cópia de entrega e repita a verificação de posicionamento.

## Trate a versão inline como uma verificação de design separada

A última linha de `main.typ` coloca o motivo ao lado das palavras. Sua altura de `1em` acompanha o tamanho do texto ao redor. O `baseline: 20%` da caixa é um ajuste inicial para este exemplo, não um valor universal de alinhamento de ícones. A [referência de box do Typst](https://typst.app/docs/reference/layout/box/) explica como a linha de base controla o alinhamento com o texto próximo.

Inspecione o marcador no tamanho normal de leitura. O ponto central escuro da ilustração grande pode ser claro, enquanto o mesmo detalhe mal aparece inline. Isso é motivo para simplificar deliberadamente o marcador ou escolher outro símbolo, em vez de ampliar todos os parágrafos para acomodá-lo.

Confira uma frase real com ascendentes e descendentes, como as palavras “cell biology”, e depois uma linha quebrada. Procure um ícone que parece flutuar, afunda abaixo do texto ou deixa o espaçamento entre linhas irregular. Mantenha qualquer ajuste óptico local ao componente do marcador para que o texto comum do documento não seja afetado.

## Confira as letras independentemente das legendas

Nosso SVG original não contém texto. Se o seu contém, estabeleça primeiro se as letras são texto editável ou formas em contornos. O [guia de mudança de fontes SVG](https://perfectvector.com/pt-BR/blog/svg-font-changes) fornece esse fluxo de inspeção.

As [configurações de text](https://typst.app/docs/reference/text/text/) do Typst controlam o texto do documento que você escreve no Typst. Não suponha que escolher uma fonte de corpo também reescreve o conteúdo interno de uma imagem importada. Confira um rótulo com glifos incomuns, um subscrito ou uma palavra longa no arquivo entregue, especialmente quando outra máquina o compilará.

Se as letras precisam continuar editáveis como conteúdo do documento, escreva esse conteúdo no Typst ou mantenha um fluxo de criação adequado. Converter letras em contornos pode preservar uma forma desenhada, mas é uma entrega diferente de texto pesquisável. Teste a propriedade necessária, em vez de avaliá-la apenas pela aparência.

## Exporte e inspecione o documento real

Incluir um SVG e exportar um documento Typst inteiro como SVG são operações diferentes. A [documentação de exportação SVG do Typst](https://typst.app/docs/reference/svg/) diz que o texto do documento é exportado como formas de glifos, o que impede a extração comum de texto desse SVG. Escolha o formato de saída conforme o propósito do documento; a [documentação de PDF](https://typst.app/docs/reference/pdf/) descreve a exportação PDF do Typst e as opções de padrões.

Para o fluxo local por linha de comando, compile a partir da pasta do exemplo com `typst compile main.typ main.pdf`. Abra esse PDF no visualizador que o destinatário provavelmente usará.

Compilamos estes exemplos originais com Typst 0.15.1 e inspecionamos os PDFs: a referência e a legenda da figura correspondiam, o marcador inline apareceu ao lado do texto e os três modos de ajuste mostraram os resultados proporcionais, recortados e esticados esperados. Teste o arquivo exportado após mudanças no arquivo original ou no modelo do documento.

Antes da entrega, confira:

1. O limite externo e cada forma interna separada estão presentes.
2. O círculo central continua circular no tamanho escolhido de figura.
3. A legenda e a referência cruzada mostram o número pretendido da figura.
4. O marcador inline é legível ao lado de texto comum.
5. O texto importante do documento pode ser selecionado ou pesquisado conforme necessário.
6. O documento exportado ainda se comporta corretamente no visualizador e modelo de destino.

Uma prévia nítida não comprova conformidade com uma revista, conformidade de acessibilidade nem preservação de todos os recursos SVG. Se o arquivo original já é um PDF, considere seu destino pretendido antes de adicionar outra conversão; o [guia de PDF para SVG](https://perfectvector.com/pt-BR/blog/convert-pdf-to-svg) explica quando extrair a arte é útil. Se um SVG parece pixelado, inspecione se há uma [imagem raster incorporada](https://perfectvector.com/pt-BR/blog/svg-contains-raster-image), em vez de alterar sua extensão novamente.

## Quando a ilustração original existe apenas como pixels

Se um motivo ilustrativo simples existe apenas como PNG ou digitalização, o [fluxo de diagrama científico para SVG](https://perfectvector.com/pt-BR/scientific-diagram-to-svg) do PerfectVector pode ajudar a recuperar uma versão candidata editável da arte. Recorte até o motivo, inspecione a prévia em busca de aberturas perdidas e formas extras de fundo e compare o resultado com a imagem original. Depois, insira o SVG aceito no Typst e repita as verificações de tamanho da figura e de uso inline.

Use essa opção para geometria ilustrativa. Mantenha medições, gráficos numéricos, barras de escala e interpretação científica vinculados aos dados e ferramentas originais de criação. Um vetorizador não restaura informações de pesquisa ausentes nem fornece aprovação de submissão. Se o vetor original existe, use-o diretamente.

Os [guias de preparação de SVG do blog](https://perfectvector.com/pt-BR/blog) abordam as verificações do arquivo de origem que vêm antes do layout do documento.

## Perguntas frequentes

**O Typst aceita imagens SVG diretamente?**
Sim. Use image com o caminho do arquivo SVG. Adicione um envoltório figure para uma legenda numerada ou box para posicionamento inline.

**Por que parte do meu SVG é recortada?**
Confira se você forneceu largura e altura com uma proporção incompatível. O modo de ajuste cover recorta para preencher a área. Experimente contain quando o desenho inteiro precisa continuar visível e inspecione também a área de desenho do arquivo original.

**Como alinho um SVG com texto no Typst?**
Coloque a imagem dentro de uma box, escolha uma altura de imagem adequada ao texto ao redor e ajuste a linha de base da caixa. Inspecione a linha real; uma porcentagem não é adequada a todos os ícones e fontes.

**Uma exportação SVG preservará texto selecionável do documento?**
A saída SVG do Typst representa o texto como formas de glifos. Use uma saída de documento adequada, como PDF, quando a extração de texto importa e verifique o resultado exportado, em vez de supor que a nitidez visual comprova o comportamento do texto.

## Fontes

1. [Typst — Image](https://typst.app/docs/reference/visualize/image/) — Entrada SVG, dimensões, modos de ajuste e descrições de imagens.
2. [Typst — Figure](https://typst.app/docs/reference/model/figure/) — Comportamento de legendas e numeração.
3. [Typst — Reference](https://typst.app/docs/reference/model/ref/) — Rótulos e referências automáticas.
4. [Typst — Box](https://typst.app/docs/reference/layout/box/) — Posicionamento inline e ajuste da linha de base.
5. [Typst — Text](https://typst.app/docs/reference/text/text/) — Configurações de texto nativo do documento.
6. [Typst — SVG](https://typst.app/docs/reference/svg/) — Saída SVG e texto como formas de glifos.
7. [Typst — PDF](https://typst.app/docs/reference/pdf/) — Opção de exportação do documento e opções de padrões de saída.

***

Comece com uma figura e uma instância inline. Se uma ilustração original perdida precisa de recuperação, [prepare uma versão candidata em SVG](https://perfectvector.com/pt-BR/scientific-diagram-to-svg), compare suas formas e confira a arte aceita no documento antes de preparar o restante do conjunto.

## Explore

- [Read the HTML article](https://perfectvector.com/pt-BR/blog/svg-in-typst)
- [SVG no LaTeX: preserve formas e componha os rótulos](https://perfectvector.com/pt-BR/blog/svg-in-latex.md)
- [Detecção de bordas SVG: prévia com feConvolveMatrix](https://perfectvector.com/pt-BR/blog/svg-convolution-edge-preview.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
