SVG no Typst: insira a arte e confira a figura

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 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 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 aborda essa tarefa anterior.

Insira o SVG em uma figura nativa

Salve isto como main.typ ao lado do SVG:

#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 explica legendas e numeração; a documentação de referências 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. 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: 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:

#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 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 fornece esse fluxo de inspeção.

As configurações de 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 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 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 explica quando extrair a arte é útil. Se um SVG parece pixelado, inspecione se há uma imagem raster incorporada, 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 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 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 — Entrada SVG, dimensões, modos de ajuste e descrições de imagens.
2. Typst — Figure — Comportamento de legendas e numeração.
3. Typst — Reference — Rótulos e referências automáticas.
4. Typst — Box — Posicionamento inline e ajuste da linha de base.
5. Typst — Text — Configurações de texto nativo do documento.
6. Typst — SVG — Saída SVG e texto como formas de glifos.
7. Typst — 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, compare suas formas e confira a arte aceita no documento antes de preparar o restante do conjunto.