Compreender o Formato PlantUML

O Que É o PlantUML?

O PlantUML é uma ferramenta open-source que permite criar diagramas a partir de descrições em texto simples. Em vez de arrastar caixas num canvas, escreve algumas linhas de sintaxe simples e o PlantUML renderiza um diagrama profissional para si. Esta abordagem é frequentemente designada por "diagrama como código" ou "texto para diagrama".

Um diagrama PlantUML mínimo tem este aspeto: abre com uma tag @start<tipo>, descreve a estrutura em algumas linhas legíveis e fecha com @end<tipo>. A ferramenta processa este texto e produz um SVG, PNG ou PDF — onde quer que o renderize.

Porquê escrever diagramas como texto?

• Controlo de versões — Texto simples gera diffs limpos no Git. Pode acompanhar cada alteração a um diagrama, revê-la num pull request e reverter se algo falhar.
• Velocidade — Escrever [Tarefa A] lasts 5 days é mais rápido do que desenhar uma barra num canvas e redimensioná-la.
• Consistência — O motor de renderização aplica espaçamento, fontes e cores uniformes automaticamente. Foca-se no conteúdo, não no layout.
• Portabilidade — Um ficheiro de texto .puml é minúsculo, legível por humanos e renderiza de forma idêntica em qualquer lugar.
• Automação — Os diagramas podem ser gerados programaticamente a partir de dados, integrados em pipelines de CI e mantidos em sincronia com o código.

Como o GanttTool Utiliza o PlantUML

O GanttTool oferece-lhe um editor visual com interface gráfica — adiciona tarefas, define durações, estabelece dependências, escolhe cores — mas nos bastidores tudo o que constrói é compilado em código PlantUML. Esse código é depois enviado para um servidor de renderização que o converte num diagrama SVG exibido no seu navegador.

O pipeline de renderização

A rota da API em /api/kroki atua como um proxy entre o seu navegador e os servidores de renderização. Funciona em duas etapas:

• Primário: servidor PlantUML.com — O código PlantUML é comprimido com Deflate (nível 9) e codificado usando a variante base-64 personalizada do PlantUML. A string resultante é anexada a https://www.plantuml.com/plantuml/svg/~1{codificado} como um pedido GET. Um timeout de 3 segundos protege contra respostas lentas.
• Alternativa: servidor Kroki.io — Se o PlantUML.com falhar ou exceder o timeout, o texto PlantUML em bruto é enviado via POST como text/plain para https://kroki.io/plantuml/svg com um timeout de 5 segundos. O Kroki é um gateway de renderização open-source que suporta muitos formatos de diagramas.

Qualquer que seja o servidor que responder primeiro com um SVG válido, essa imagem é devolvida ao navegador com o cabeçalho Content-Type: image/svg+xml e renderizada inline. Nunca precisa de pensar em codificação ou fallback — simplesmente funciona.

Sintaxe de Diagramas de Gantt em PlantUML

Cada diagrama de Gantt em PlantUML é envolvido pelas tags @startgantt / @endgantt. No interior, descreve o seu projeto num estilo natural e legível.

Estrutura básica de tarefas

@startgantt
' Título do projeto e escala
title Projeto de Redesign do Website
Project starts 2026-07-01
printscale weekly

' Separador de fase
-- Descoberta --

' Tarefas regulares: [Nome] lasts N days
[Levantamento de requisitos] lasts 5 days
[Análise da concorrência] lasts 3 days

-- Design --

[Wireframes] lasts 7 days
[Design visual] lasts 10 days
[Design visual] starts at [Wireframes]'s end

-- Desenvolvimento --

[Frontend] lasts 14 days
[Frontend] starts at [Design visual]'s end
[Integração backend] lasts 10 days
[Integração backend] starts at [Frontend]'s end

@endgantt

Marcos

Os marcos têm duração zero e aparecem como um losango na linha do tempo. Defina-os com happens at em vez de lasts.

@startgantt
Project starts 2026-07-01

[Desenvolvimento] lasts 14 days and is colored in CornflowerBlue
[Testes QA] lasts 5 days and is colored in LightGreen
[Testes QA] starts at [Desenvolvimento]'s end

' Marco — acontece no final de uma tarefa específica
[Lançamento v1.0] happens at [Testes QA]'s end

' Percentagem de conclusão
[Desenvolvimento] is 70% completed

@endgantt

Separadores de fase e configurações do projeto

Envolva os nomes das secções entre duplos traços (-- Nome da fase --) para inserir uma linha separadora. Combine com configurações globais do projeto para controlo total.

@startgantt
title Lançamento de Produto T3
Project starts 2026-07-01
printscale weekly zoom 2
saturday are closed
sunday are closed
today is colored in Lavender

-- Planeamento --
[Reunião de arranque] lasts 1 day
[Definição do âmbito] lasts 3 days
[Definição do âmbito] starts at [Reunião de arranque]'s end

-- Construção --
[Sprint de engenharia 1] lasts 10 days
[Sprint de engenharia 1] starts at [Definição do âmbito]'s end
[Sprint de engenharia 2] lasts 10 days
[Sprint de engenharia 2] starts at [Sprint de engenharia 1]'s end

-- Lançamento --
[Testes de smoke] lasts 2 days
[Testes de smoke] starts at [Sprint de engenharia 2]'s end
[Entrada em produção] happens at [Testes de smoke]'s end

@endgantt

Sintaxe Gantt essencial de relance

PlantUML Além dos Diagramas de Gantt

O Gantt é apenas um de mais de uma dúzia de tipos de diagramas que o PlantUML suporta. A mesma filosofia de texto simples — tag de início, descrição, tag de fim — aplica-se a todos eles. Aqui fica um panorama dos tipos mais utilizados.

@startuml
title Fluxo de Login do Utilizador

Browser -> API: POST /login {email, password}
API -> Base de Dados: SELECT user WHERE email=?
Base de Dados --> API: registo do utilizador
alt credenciais válidas
    API --> Browser: 200 OK + token JWT
else inválidas
    API --> Browser: 401 Não Autorizado
end
@enduml

@startuml
class Projeto {
    +id: String
    +nome: String
    +dataInicio: Date
    +obterTarefas(): Tarefa[]
}

class Tarefa {
    +id: String
    +nome: String
    +duracao: Number
    +concluir(): void
}

class Marco {
    +nome: String
    +data: Date
}

Projeto "1" o-- "many" Tarefa
Projeto "1" o-- "many" Marco
Tarefa <|-- Marco
@enduml

Mais tipos de diagramas PlantUML

Aqui fica um exemplo rápido de um mapa mental em PlantUML para ilustrar como os diagramas não-Gantt seguem a mesma filosofia de texto primeiro:

@startmindmap
* Planeamento do Projeto
** Âmbito
*** Requisitos
*** Entregáveis
** Cronograma
*** Diagrama de Gantt
*** Marcos
** Equipa
*** Funções
*** Recursos
** Riscos
*** Plano de mitigação
@endmindmap

Experimente o PlantUML Online

Não precisa de instalar nada para começar a experimentar o PlantUML. O ecossistema dispõe de excelentes renderizadores online gratuitos:

Comece a Criar Diagramas de Gantt

O GanttTool oferece-lhe o poder do PlantUML sem precisar de escrever uma única linha de código. Use o editor visual para construir o cronograma do seu projeto e deixe a aplicação tratar da sintaxe PlantUML e da renderização do diagrama automaticamente.

• Adicione tarefas, marcos e separadores de fase com um clique.
• Defina durações, dependências, cores e percentagens de conclusão visualmente.
• Inspecione o código PlantUML gerado a qualquer momento — copie e reutilize-o onde quiser.
• Exporte como SVG ou copie para a área de transferência como PNG para apresentações e documentos.
• Descreva o seu projeto em linguagem natural e deixe o assistente de IA gerar um rascunho completo de Gantt.