# Figuras e diagramas

O compositor de diagramas: desenhe em uma tela ou escreva o código, em TikZ para LaTeX, fletcher para Typst ou Mermaid para Markdown, com prévia em tempo real e código-fonte editável.

Desenhe um diagrama em uma tela e receba código-fonte simples na linguagem do seu documento: TikZ para LaTeX, um diagrama fletcher para Typst ou um fluxograma Mermaid para Markdown. O desenho e o código ficam sincronizados, então você pode alternar entre eles a qualquer momento.

O compositor roda no seu dispositivo e não precisa de conta. (Para figuras escritas pelo assistente, veja [Desenhar figuras com IA](/docs/ai-figures/).)

## Abrir o compositor

Na tela inicial, escolha **Compositor de diagramas** no dock. Você também pode executar **Abrir o Compositor de diagramas** na paleta de comandos ⌘K (Ctrl+K), ou digitar `/diagram` na omnibarra de busca. Uma caixa de diálogo, **Escolher um compositor de diagramas**, pergunta para que serve o diagrama: **Diagrama TikZ** para documentos LaTeX, **Diagrama Typst** para documentos Typst ou **Diagrama Mermaid** para documentos Markdown.

Em um documento aberto, escolha **Desenhar um diagrama** na barra de ferramentas do editor. O compositor pula a pergunta e usa a linguagem do documento: TikZ em um arquivo `.tex`, Typst em um arquivo `.typ` e Mermaid em um arquivo Markdown. **Voltar ao projeto** leva você de volta ao documento.

O cabeçalho mostra o nome do diagrama, no qual você pode clicar para renomear, e um pequeno rótulo com a linguagem dele.

![Um diagrama TikZ escrito como código e depois editado como formas na tela.](https://cdn.oleafly.com/images/gifs/desktop/tikz-composer.gif?v=2)

## Desenhar na tela

O modo **Desenhar** é a tela. Ele funciona do mesmo jeito nas três linguagens.

Escolha uma forma na paleta (retângulo, caixa arredondada, círculo, elipse, losango, paralelogramo ou texto) e clique e arraste para posicioná-la e dimensioná-la. **Matemática** e **Código** são caixas de texto que começam com uma equação ou uma amostra de código na linguagem do diagrama.

Para conectar duas formas, arraste de um ponto de conexão de uma até a outra. O conector continua preso quando você move qualquer uma das formas. Selecione-o para escolher a ponta da seta (no fim, nas duas pontas ou nenhuma), o roteamento (reto, ortogonal ou curvo) e um rótulo. Selecione uma forma para mudar o rótulo, o preenchimento, a borda, o raio dos cantos ou a fonte.

As formas se alinham automaticamente enquanto você as move, e desfazer e refazer funcionam como de costume. Segure Espaço e arraste para deslocar a visualização, e clique duas vezes em uma forma para editar o texto dela.

![Um diagrama de fluxo de trabalho desenhado com o pacote fletcher e compilado.](https://cdn.oleafly.com/images/gifs/desktop/typst-composer.gif?v=2)

## Editar o código

O modo **Código** mostra o mesmo diagrama como código-fonte, com um menu **Trechos** para peças comuns, como um nó retangular, um nó circular, uma aresta com seta e uma aresta simples. Edite qualquer um dos lados e o outro acompanha: mova uma caixa e o código muda, renomeie um rótulo no código e a tela muda.

O código é código-fonte comum de cada linguagem:

- TikZ: um `tikzpicture` com nós e arestas.
- Typst: um trecho fletcher completo, com a linha `#import "@preview/fletcher:…"` e uma chamada `#diagram(…)` contendo itens `node(…)` e `edge(…)`. A versão do fletcher corresponde à versão do Typst do projeto Typst aberto: 0.5.8 para o Typst 0.13 e posteriores, 0.5.5 para o 0.12 e 0.5.1 para versões mais antigas.
- Mermaid: um fluxograma com formas de nó, ligações com rótulos, linhas `style` para cores e subgrafos para caixas de grupo. O próprio Mermaid organiza o layout do diagrama, então as posições que você define na tela não fazem parte do código.

### Código que a tela não consegue desenhar

No Typst e no Mermaid, o código que a tela não consegue mostrar fica exatamente como você o escreveu. Para o Typst, isso inclui imports, linhas `#let`, código em volta do diagrama, como `#figure(…)`, configurações extras de diagrama e laços. Para o Mermaid, inclui linhas `click`, diretivas, comentários e frontmatter. Um nó ou aresta que você não toca na tela mantém o texto, e um que você toca mantém as opções que a tela não conhece.

Quando a tela não mostra tudo, um botão de notas aparece no cabeçalho com uma contagem, como **2 notas**. Ele lista o que fica só no código e o que a tela mostra de forma aproximada, como nós sem tamanho definido, rótulos formatados ou uma forma do Mermaid que a tela não tem.

O TikZ se comporta de outro jeito. As notas nomeiam os comandos do TikZ que a tela não modela, e uma edição na tela reescreve o TikZ a partir do desenho, então esses comandos se perdem. Mantenha TikZ escrito à mão ou complexo no modo Código.

## Prévia do resultado

**Compilar** renderiza o diagrama sozinho, separado do seu documento, em um painel de prévia ao lado da tela. Escolha uma escala de PNG de 1x, 2x ou 3x e uma cor de fundo ou um fundo transparente.

- O TikZ compila com o Tectonic em uma compilação separada, então um diagrama pela metade nunca toca o seu documento.
- O Typst faz a prévia com a própria versão do Typst do projeto Typst aberto e com o cache de pacotes dele, ou com o Typst embutido quando nenhum projeto Typst está aberto. A primeira prévia do Typst baixa o fletcher do Typst Universe. No modo offline, ou sem conexão, a prévia informa que o pacote está faltando em vez de mostrar um erro genérico.
- O Mermaid faz a prévia com o próprio renderizador Mermaid do aplicativo.

Os erros aparecem no painel de prévia. No Typst e no Mermaid, cada erro indica a linha dele no código, e clicar nela leva até lá.

Se uma compilação falhar, **Corrigir com IA** envia o código e os erros para o seu provedor de IA conectado e pede um código corrigido na mesma linguagem.

## Inserir, salvar e baixar

Compile primeiro e depois abra o menu **Salvar** ao lado de **Compilar**:

- **Inserir como TikZ**, **Inserir como Typst** ou **Inserir como Mermaid** coloca o diagrama no cursor do documento `.tex`, `.typ` ou Markdown aberto, na linguagem desse documento. Se o compositor estiver definido para outra linguagem, o desenho é convertido pela tela primeiro, então código que a tela não consegue mostrar não é levado.
- **Salvar no projeto** grava `figures/<name>.png` e o código-fonte, `figures/<name>.tikz`, `.typ` ou `.mmd`, em um projeto que você escolhe na lista. Salvar em um projeto que usa outra linguagem converte o desenho para a linguagem desse projeto. O Oleafly pergunta antes de substituir arquivos que já existem. Adicione um diagrama Typst salvo a um documento com `#include`, e um diagrama Mermaid dentro de um bloco de código `mermaid`.
- **Salvar no projeto → Novo projeto** cria um projeto de diagrama na linguagem do compositor.
- **Salvar figura** mantém o PNG e o código-fonte no cache de figuras do Oleafly, fora de qualquer projeto.

O menu **Baixar** salva um PNG, um SVG para diagramas Typst e Mermaid, ou o código-fonte como **TikZ (.tikz)**, **Typst (.typ)** ou **Mermaid (.mmd)**. Baixar em outra linguagem converte o desenho pela tela.

![Um fluxograma Mermaid escrito para um caderno em Markdown e exibido na prévia.](https://cdn.oleafly.com/images/gifs/desktop/mermaid-composer.gif?v=2)

## Mermaid em documentos Markdown

Inserir em um documento Markdown adiciona um bloco de código `mermaid`, e a prévia do Markdown o desenha. Um PDF precisa de uma imagem, então o compositor também salva um PNG renderizado em `figures/mermaid-<hash>.png`, e a compilação do Markdown coloca essa imagem no lugar do bloco. O diagrama, portanto, também aparece no PDF compilado. Se você editar o bloco à mão depois, o PDF mostra o código até você inserir ou salvar o diagrama pelo compositor de novo.

## Reabrir e importar diagramas

Os arquivos de código-fonte que o compositor salva terminam com um comentário de uma linha que guarda o modelo da tela. Importe um deles e o desenho volta exatamente como você o deixou.

**Importar arquivo de diagrama** no cabeçalho abre um arquivo `.tikz`, `.tex`, `.typ`, `.mmd` ou `.md` e substitui o rascunho atual. Um arquivo em outra linguagem muda o compositor para essa linguagem. O código que a tela consegue ler é desenhado; todo o resto abre só como código.

## Projetos de diagrama

Um projeto de diagrama guarda uma figura. Crie um em qualquer uma das três linguagens com **Salvar no projeto → Novo projeto**. Um projeto de diagrama Typst tem um `main.typ` independente cuja página é dimensionada para o desenho, então compilá-lo produz o PDF do diagrama.

Abra o arquivo principal do projeto e mude a barra de ferramentas do editor de **Código** para **Tela** (TikZ) ou **Visual** (Typst e Markdown) para editá-lo na mesma tela.

O modelo **Diagrama / Figura** (TikZ) e o modelo **Figura Typst** também iniciam um projeto de uma figura, escrito como código-fonte. Projetos como esses fazem a prévia como a própria figura, e o [menu de exportação](/docs/export/) deles oferece **Exportar como PDF (imagem vetorial)** e **Exportar como PNG**. Use-os para figuras que você reutiliza entre artigos.
