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

# Operações booleanas SVG no Paper.js: corte e una arte importada

> Importe traçados SVG no Paper.js, una formas sobrepostas, subtraia uma abertura real e confira o arquivo exportado com um pequeno exemplo reproduzível no navegador.

Source: https://perfectvector.com/pt-BR/blog/paperjs-svg-booleans

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

Importe o SVG, encontre os objetos de traçado pretendidos e chame `unite()` para unir regiões preenchidas ou `subtract()` para remover uma região de outra. Mantenha os operandos até conferir o resultado e reabra o SVG exportado antes de usá-lo em outro lugar.

A decisão importante vem antes da operação booleana: quais formas devem ficar juntas? Um grupo importado pode conter retângulos de fundo, traçados de recorte, letras e partes decorativas. Combinar todos os filhos pode apagar as separações que você queria preservar. Este passo a passo usa três traçados fechados com nomes para que você veja exatamente o que muda.

## Comece com geometria preenchida que você consiga identificar

O [importador SVG](https://paperjs.org/reference/project/#importsvg) do Paper.js aceita marcação SVG, um elemento SVG ou uma URL. Essas opções precisam de tratamentos diferentes de carregamento: este exemplo importa uma string inline; um arquivo remoto deve ser processado na função de retorno da importação após o carregamento.

Para esta tarefa, os operandos precisam ser objetos `Path` ou `CompoundPath`. Um grupo é um contêiner, e uma imagem raster não fornece o limite necessário para uma operação booleana de traçados. Se um arquivo se comporta apenas como uma única imagem, confira primeiro [por que um SVG não pode ser desagrupado](https://perfectvector.com/pt-BR/blog/svg-wont-ungroup).

Use IDs para as partes que você controla. Não suponha que `children[0]` significa “o logo” em qualquer exportação. Inspecione artes desconhecidas e atribua as partes deliberadamente. Mantenha um [traçado composto](https://paperjs.org/reference/compoundpath/) existente intacto quando seus subtraçados já definem os vazados pretendidos.

## Execute uma pequena importação, união e subtração

Testamos o código abaixo com **Paper.js 0.12.18** em um navegador. A arte é um SVG original feito manualmente: um corpo quadrado, uma aba sobreposta e um quadrado branco que marca a abertura pretendida. Não é uma amostra de conversão do PerfectVector.

Em uma pasta vazia, instale a biblioteca com versão fixada:

```bash
npm install --save-exact paper@0.12.18
```

Salve isto como `index.html`:

```html
<!doctype html>
<meta charset="utf-8">
<title>SVG Boolean example</title>
<canvas id="work" width="300" height="220" hidden></canvas>
<div id="result" style="background:#d8e8e0; width:300px"></div>
<pre id="svg-output"></pre>
<script src="node_modules/paper/dist/paper-full.min.js"></script>
<script src="example.js"></script>
```

Salve isto como `example.js` e abra o HTML em um navegador:

```javascript
paper.setup(document.getElementById('work'));
const source = `<svg xmlns="http://www.w3.org/2000/svg" width="300" height="220" viewBox="0 0 300 220">
  <path id="body" fill="#176b62" d="M40 40H180V180H40Z"/>
  <path id="tab" fill="#ee9852" d="M160 80H260V140H160Z"/>
  <path id="hole" fill="#ffffff" d="M80 80H130V130H80Z"/>
</svg>`;
const imported = paper.project.importSVG(source, { insert: false, expandShapes: true });
function operand(name) {
  const item = imported.getItem({ name });
  if (!(item instanceof paper.Path || item instanceof paper.CompoundPath)) {
    throw new Error(`Expected path geometry for ${name}`);
  }
  return item;
}
const joined = operand('body').unite(operand('tab'), { insert: false });
const cut = joined.subtract(operand('hole'), { insert: false });
cut.fillColor = '#176b62';
cut.strokeColor = null;
paper.project.activeLayer.addChild(cut);
const output = paper.project.exportSVG({ asString: true, bounds: new paper.Rectangle(0, 0, 300, 220) });
document.getElementById('result').innerHTML = output;
document.getElementById('svg-output').textContent = output;
```

A importação fica fora da cena com `insert: false`. `expandShapes: true` solicita ao importador que transforme formas primitivas compatíveis em traçados; nosso exemplo já contém elementos path. A verificação explícita de classe ainda importa, pois um ID importado pode identificar um contêiner ou outro tipo de item.

A [API booleana](https://paperjs.org/reference/path/#unite) retorna um novo item de traçado. Aqui, o resultado é mantido fora da cena até a forma final recortada ser adicionada. As partes originais continuam disponíveis em `imported`, portanto uma operação que falha não exige reconstruir a arte original.

`joined.subtract(hole)` remove o vazado da silhueta unida. Inverter os operandos faz outra pergunta e pode produzir um resultado vazio ou inesperado. O [modo padrão de subtração](https://paperjs.org/reference/path/#subtract) do Paper.js trata os operandos como áreas. Sua opção `trace` se refere à geometria booleana; não tem relação com vetorizar um PNG.

![Comparação no navegador de três traçados SVG importados, uma silhueta unida com abertura quadrada transparente e o resultado exportado reaberto](https://perfectvector.com/blog/paperjs-svg-booleans/boolean-browser.webp)

*O fundo listrado continua oculto atrás da área branca original e aparece através da abertura subtraída. A exportação mantém essa abertura quando é importada novamente.*

## Confira o resultado como geometria e como arquivo

Neste exemplo, a união retornou um `Path`; a subtração retornou um `CompoundPath` com dois contornos. Os limites finais foram x = 40, y = 40, largura = 220 e altura = 140 em unidades SVG. A arte fica dentro de uma área de visualização de exportação de 300 × 220, portanto os limites e o tamanho do documento são intencionalmente diferentes.

Conferimos o centro da abertura em `(105, 105)`: ele estava dentro da silhueta unida e fora do resultado subtraído. Um ponto no corpo sólido em `(60, 60)` permaneceu dentro. Reimportar o SVG exportado preservou os limites e voltou a excluir o centro do vazado. Esses são resultados deste exemplo simples de teste, não uma garantia para todos os arquivos importados.

A [API de exportação](https://paperjs.org/reference/project/#exportsvg) pode retornar uma string SVG e receber limites explícitos. Copie a marcação exibida abaixo do resultado para `result.svg` e abra esse arquivo de forma independente. Nossa exportação salva continha um elemento path com dois subtraçados fechados; ela também foi renderizada corretamente ao ser aberta diretamente no navegador.

Para sua arte, confira:

* a silhueta e cada abertura em relação ao original;
* se algum fundo ou alguma forma auxiliar oculta foi incluída por acidente;
* o preenchimento pretendido, pois uma forma unida não consegue preservar dois preenchimentos chapados editáveis de forma independente;
* a área de visualização exportada, especialmente quando a arte chega à borda do documento;
* o arquivo no aplicativo que realmente o usará.

Uma sobreposição branca pode parecer uma abertura em papel branco. Coloque o resultado sobre um fundo contrastante para conferir a transparência. O [guia de vazados SVG preenchidos](https://perfectvector.com/pt-BR/blog/svg-holes-fill-in) explica os problemas relacionados a traçados compostos e regras de preenchimento.

## Quando a operação produz a forma errada

**Um método está ausente.** Inspecione a classe do item selecionado. Encontre o traçado pretendido dentro de um grupo ou converta formas primitivas compatíveis durante a importação. Não resolva isso combinando todos os descendentes: traçados compostos também contêm filhos, e as relações de seus vazados importam.

**O resultado parece inalterado.** Certifique-se de exibir o item retornado. Deixar os originais visíveis pode encobrir uma subtração bem-sucedida. No exemplo, somente o resultado final entra na camada ativa.

**Um contorno desaparece ou muda de significado.** Este exemplo opera em regiões fechadas e preenchidas. Uma linha grossa visível não é automaticamente a mesma forma que a área coberta por seu contorno. Se você precisa dessa borda como operando preenchido, prepare uma cópia com o contorno convertido em forma em um editor vetorial e inspecione-a antes de importar. Mantenha o original editável.

**Uma arte detalhada se comporta mal.** Isole dois operandos e inspecione seus contornos antes de aplicar uma sequência a uma ilustração inteira. Duplicatas, autointerseções e fragmentos minúsculos precisam de verificações específicas para cada caso. Este pequeno exemplo não mede desempenho nem compatibilidade ampla com SVG. Para um reparo pontual, as ferramentas de seleção e nós de um [editor vetorial](https://perfectvector.com/pt-BR/blog/how-to-edit-an-svg) podem ser mais fáceis do que escrever um fluxo de processamento de geometria.

## Quando sua imagem original ainda é um PNG ou JPG

Se o original editável está ausente, o [fluxo de imagem para vetor](https://perfectvector.com/pt-BR/image-to-vector) do PerfectVector pode ajudar a preparar um SVG a partir de uma arte raster adequada. Visualize o resultado, inspecione os contornos e espaços negativos e baixe uma versão candidata para testar no Paper.js.

A vetorização não identifica quais partes seu programa deve unir ou subtrair. Você ainda precisa inspecionar a estrutura importada, selecionar os operandos certos e conferir o resultado exportado. Use o vetor original quando você o tiver; desenhe diretamente um quadrado ou círculo simples em vez de vetorizá-lo. A [visão geral de vetorização de imagens](https://perfectvector.com/pt-BR/blog/what-is-image-vectorization) aborda essa decisão sobre o arquivo de origem.

## Perguntas frequentes

**Posso chamar unite em um grupo SVG importado?**
Selecione primeiro os operandos Path ou CompoundPath pretendidos dentro do grupo. Um grupo descreve organização, e combinar todos os filhos pode incluir fundos ou destruir separações intencionais.

**subtract remove os traçados originais?**
Ele retorna um novo item de traçado. Este exemplo usa insert: false para a importação e os resultados booleanos e insere apenas o resultado final. Os operandos de origem continuam disponíveis no contêiner importado.

**Por que um vazado ainda parece branco?**
Confira-o contra um fundo colorido. Um objeto com preenchimento branco cobre o que está atrás; uma abertura subtraída revela esse fundo. Reabra o arquivo exportado para confirmar que a relação é preservada.

**A vetorização fará a limpeza booleana por mim?**
Não. Ela pode recuperar arte em traçados a partir de uma imagem raster adequada, mas seu aplicativo ainda precisa escolher qual geometria unir, qual área remover e como validar o resultado.

## Fontes

1. [Paper.js — referência de Project](https://paperjs.org/reference/project/) — Documenta importação e exportação SVG, limites e conteúdo do projeto.
2. [Paper.js — referência de Path](https://paperjs.org/reference/path/) — Define união e subtração, os itens de traçado retornados e as opções booleanas.
3. [Paper.js — referência de CompoundPath](https://paperjs.org/reference/compoundpath/) — Descreve a geometria composta e seus traçados constituintes.

***

Se uma imagem raster é seu único material de origem, [prepare uma versão candidata em SVG](https://perfectvector.com/pt-BR/image-to-vector), inspecione suas partes e teste a menor operação booleana útil antes de processar o restante da arte.

## Explore

- [Read the HTML article](https://perfectvector.com/pt-BR/blog/paperjs-svg-booleans)
- [Unidades de clipPath em SVG: ajuste uma forma ao alvo](https://perfectvector.com/pt-BR/blog/svg-clippath-units.md)
- [SVG no PowerPoint: converta em formas e edite partes](https://perfectvector.com/pt-BR/blog/powerpoint-svg-convert-to-shape.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
