SVG Stroking

Estilizando contornos SVG com propriedades de traço

O stroke de um elemento SVG é a pintura aplicada ao longo do contorno de uma forma, linha ou texto — ao contrário do fill, que pinta o interior. O SVG oferece uma família de propriedades stroke-* que controlam todos os aspectos desse contorno: sua cor, espessura, transparência, como suas extremidades são terminadas, como seus cantos são unidos e se é sólido ou tracejado.

Essas propriedades são atributos de apresentação, portanto você pode defini-las diretamente em um elemento (stroke="purple") ou através de CSS (stroke: purple;). Elas também herdam, razão pela qual é comum defini-las uma vez em um elemento <g> (grupo) e deixar que as formas filhas as herdem.

Este capítulo abrange o conjunto completo de propriedades de traço. Para as formas que você irá estilizar com traço, veja SVG Path, SVG Line e SVG Text. Se você é novo no SVG, comece com a Introdução ao SVG e mantenha a Referência SVG à mão para uma consulta rápida de cada atributo.

As propriedades de traço em resumo:

stroke — a cor (ou outra pintura) do contorno.
stroke-width — a espessura do contorno.
stroke-opacity — o nível de transparência do traço, de 0 a 1.
stroke-linecap — a forma desenhada nas extremidades abertas de uma linha: butt, round ou square.
stroke-linejoin — a forma desenhada onde dois segmentos de linha se encontram: miter, round ou bevel.
stroke-miterlimit — o quanto uma junção miter pode se estender antes de ser substituída por um bevel.
stroke-dasharray — o padrão de traços e espaços para um contorno tracejado.
stroke-dashoffset — a distância ao longo do caminho em que o padrão de traços começa.

A propriedade stroke

A propriedade stroke define a cor do contorno. Ela aceita qualquer valor de cor CSS — uma cor nomeada, um código hexadecimal, rgb(), hsl(), ou uma referência a um gradiente ou padrão. Por padrão, as formas não têm traço (none), portanto nada é desenhado até que você defina um.

No exemplo abaixo, fill="none" é definido no grupo para que apenas os contornos sejam visíveis, e cada caminho é estilizado com uma cor diferente.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <svg width="250" height="100">
      Sorry, your browser doesn't support inline SVG.
      <g fill="none">
        <path stroke="purple" d="M5 30 l215 0" />
        <path stroke="lightgreen" d="M5 60 l215 0" />
        <path stroke="pink" d="M5 90 l215 0" />
      </g>
    </svg>
  </body>
</html>

Experimente Você Mesmo »

O texto "Sorry, your browser doesn't support inline SVG." é conteúdo de fallback. Ele deve ser um filho de texto direto do elemento <svg> para que um navegador sem suporte a SVG embutido o exiba em vez do gráfico. Navegadores modernos o ignoram e renderizam o SVG.

A propriedade stroke-width

A propriedade stroke-width define a espessura do contorno. O traço é desenhado centralizado no caminho, portanto metade de sua largura fica em cada lado da linha geométrica.

Um número isolado é interpretado em unidades de usuário (o sistema de coordenadas SVG) — stroke-width="5" e stroke-width="5px" são equivalentes em um SVG simples. Você também pode usar unidades CSS explícitas (px, em, pt) ou uma porcentagem, que é calculada em relação à diagonal do viewport SVG, e não à sua largura ou altura.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <svg width="250" height="100">
      <g fill="none" stroke="lightgreen">
        <path stroke-width="3" d="M5 30 l215 0" />
        <path stroke-width="5" d="M5 60 l215 0" />
        <path stroke-width="7" d="M5 90 l215 0" />
      </g>
    </svg>
  </body>
</html>

Experimente Você Mesmo »

A propriedade stroke-opacity

A propriedade stroke-opacity controla a transparência do traço individualmente, independentemente da opacidade do preenchimento. Ela recebe um número de 0 (totalmente transparente) a 1 (totalmente opaco); um valor como 0.5 torna o traço semitransparente. Isso é útil para sobrepor contornos ou deixar o fundo aparecer através de um contorno sem afetar o preenchimento da forma.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <svg width="250" height="100">
      <g fill="none" stroke="purple" stroke-width="8">
        <path stroke-opacity="1" d="M5 30 l215 0" />
        <path stroke-opacity="0.5" d="M5 60 l215 0" />
        <path stroke-opacity="0.2" d="M5 90 l215 0" />
      </g>
    </svg>
  </body>
</html>

Result

A propriedade stroke-linecap

A propriedade stroke-linecap define a forma desenhada nas extremidades abertas de um caminho estilizado com traço. Ela aceita três valores:

butt (o padrão) — o traço para exatamente no ponto final do caminho com uma borda plana e sem extensão. O comprimento desenhado é igual ao comprimento geométrico do caminho.
round — um semicírculo cujo raio é metade da largura do traço é adicionado em cada extremidade, portanto a linha se estende além do ponto final por stroke-width / 2 e termina em uma curva suave.
square — uma tampa plana é adicionada que se estende além do ponto final por stroke-width / 2. Parece com butt, mas é mais longa; o comprimento extra em cada extremidade é o mesmo que round, apenas com uma borda plana em vez de uma curva.

A diferença é mais visível com um traço espesso. Observe como as linhas round e square abaixo parecem ligeiramente mais longas do que a linha butt, mesmo que todos os três caminhos compartilhem as mesmas coordenadas.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <svg width="250" height="100">
      <g fill="none" stroke="lightblue" stroke-width="10">
        <path stroke-linecap="butt" d="M5 30 l215 0" />
        <path stroke-linecap="round" d="M5 60 l215 0" />
        <path stroke-linecap="square" d="M5 90 l215 0" />
      </g>
    </svg>
  </body>
</html>

Experimente Você Mesmo »

A propriedade stroke-linejoin

A propriedade stroke-linejoin define a forma usada onde dois segmentos de linha de um caminho se encontram — os cantos. Ela aceita três valores comuns:

miter (o padrão) — as bordas externas dos dois segmentos são estendidas até se encontrarem em um ponto agudo.
round — o canto é arredondado com um arco.
bevel — o canto é cortado com uma borda plana.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <svg width="250" height="120">
      <g fill="none" stroke="orange" stroke-width="12">
        <path stroke-linejoin="miter" d="M15 90 L40 20 L65 90" />
        <path stroke-linejoin="round" d="M105 90 L130 20 L155 90" />
        <path stroke-linejoin="bevel" d="M185 90 L210 20 L235 90" />
      </g>
    </svg>
  </body>
</html>

Result

A propriedade stroke-miterlimit

Quando stroke-linejoin é miter, ângulos muito agudos podem produzir pontas extremamente longas e pontiagudas. A propriedade stroke-miterlimit limita o tamanho que tal ponta pode atingir. Ela define a razão máxima permitida entre o comprimento do miter e a largura do traço, onde o comprimento do miter é a distância do canto interno até a ponta externa do ponto. Se a razão de uma junção excederia o limite, essa junção é silenciosamente substituída por um bevel.

O padrão é 4, o que significa que um miter pode se estender até quatro vezes a largura do traço antes de ser cortado (isso preserva o ponto para qualquer ângulo de canto de aproximadamente 29° ou mais amplo). Quanto mais agudo o canto, mais longo o miter, portanto quanto menor o limite definido, maior o ângulo em que os cantos começam a ser chanfrados. Um limite de 1 chanfra quase todos os cantos que não são uma linha reta; um limite grande como 10 permite até picos muito agudos. O valor deve ser pelo menos 1.

No exemplo abaixo, ambos os caminhos formam o mesmo pico agudo, mas o da esquerda (stroke-miterlimit="1") é forçado a um chanfro, enquanto o da direita (stroke-miterlimit="10") mantém sua ponta.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <svg width="250" height="120">
      <g fill="none" stroke="purple" stroke-width="10" stroke-linejoin="miter">
        <path stroke-miterlimit="1" d="M20 100 L45 25 L70 100" />
        <path stroke-miterlimit="10" d="M120 100 L145 25 L170 100" />
      </g>
    </svg>
  </body>
</html>

Result

A propriedade stroke-dasharray

A propriedade stroke-dasharray transforma um contorno sólido em tracejado. Seu valor é uma lista de números separados por vírgulas ou espaços que descrevem os comprimentos de traços e espaços, aplicados em ordem alternada ao longo do caminho:

Um único valor como stroke-dasharray="10" produz traços e espaços de comprimento igual (10,10).
Dois valores como stroke-dasharray="3,5" significam um traço de 3 unidades seguido de um espaço de 5 unidades, repetido.
Com um número par de valores, a lista é usada como está e se repete.

Se você fornecer um número ímpar de valores, o SVG repete a lista uma segunda vez para torná-la par, de modo que as funções de traço/espaço se alternam. Por exemplo, stroke-dasharray="30,15,10,10,10,15" é lido como um padrão de traço-30, espaço-15, traço-10, espaço-10, traço-10, espaço-15 e depois se repete.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <svg width="250" height="100">
      <g fill="none" stroke="orange" stroke-width="5">
        <path stroke-dasharray="3,5" d="M5 30 l215 0" />
        <path stroke-dasharray="12,12" d="M5 60 l215 0" />
        <path stroke-dasharray="30,15,10,10,10,15" d="M5 90 l215 0" />
      </g>
    </svg>
  </body>
</html>

Experimente Você Mesmo »

A propriedade stroke-dashoffset

A propriedade stroke-dashoffset desloca onde o padrão de traços começa ao longo do caminho. Um valor de 0 (o padrão) inicia o padrão no ponto inicial do caminho; um valor positivo move o ponto inicial para frente ao longo do caminho, enquanto um valor negativo o move para trás. É isso que torna possível animar efeitos de "formigas marchando" ou de desenho de linha, alterando gradualmente o deslocamento.

No exemplo abaixo, as três linhas compartilham o mesmo padrão de traços, mas o iniciam em deslocamentos diferentes, de modo que os traços aparecem deslocados uns em relação aos outros.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <svg width="250" height="100">
      <g fill="none" stroke="lightgreen" stroke-width="5" stroke-dasharray="20,10">
        <path stroke-dashoffset="0" d="M5 30 l215 0" />
        <path stroke-dashoffset="10" d="M5 60 l215 0" />
        <path stroke-dashoffset="20" d="M5 90 l215 0" />
      </g>
    </svg>
  </body>
</html>

Result

Animando com stroke-dashoffset

Como o deslocamento pode ser animado, stroke-dashoffset é a base para dois efeitos populares:

Formigas marchando — anima o deslocamento por um período completo de traço para que os traços pareçam se mover ao longo do contorno (como um marcador de seleção).
Desenho de linha — define stroke-dasharray com o comprimento total do caminho para que todo o caminho se torne um traço longo, depois anima o deslocamento desse comprimento até 0 para que a linha pareça se desenhar sozinha.

O CSS abaixo produz o efeito de formigas marchando. A animação vai de um deslocamento de 0 a 30 (o comprimento de um ciclo de traço-mais-espaço 15,15), o que torna o loop contínuo:

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      .ants {
        stroke: purple;
        stroke-width: 3;
        fill: none;
        stroke-dasharray: 15, 15;
        animation: march 1s linear infinite;
      }
      @keyframes march {
        to {
          stroke-dashoffset: 30;
        }
      }
    </style>
  </head>
  <body>
    <svg width="220" height="120">
      <rect class="ants" x="10" y="10" width="200" height="100" />
    </svg>
  </body>
</html>

Result

Para desenhar formas inteiras dessa forma, veja SVG Path e SVG Line; a lista completa de atributos de traço está na Referência SVG.

Prática

Qual(is) das afirmações a seguir é/são verdadeira(s) sobre o SVG stroking em HTML?

A propriedade stroke é usada para definir a cor de uma forma SVG.A propriedade stroke-width é usada para definir a largura do traço em uma forma SVG.A propriedade stroke-dasharray é usada para definir ou remover linhas tracejadas em uma forma SVG.A propriedade stroke-linecap é usada para especificar a cor dos cantos de uma forma SVG.A propriedade stroke-linejoin é usada para especificar a forma a ser usada nos cantos dos caminhos quando são estilizados com traço.A propriedade stroke-opacity é usada para aumentar a largura do traço em uma forma SVG.