Propriedade CSS stroke-dashoffset
Como usar a propriedade CSS stroke-dashoffset para definir onde o traço começa. Conheça a propriedade e veja os valores com exemplos práticos.
A propriedade stroke-dashoffset define a distância ao longo de um caminho SVG na qual o padrão de traços de um contorno começa. Ela funciona em conjunto com stroke-dasharray, que define os comprimentos dos traços e espaços. O stroke-dasharray decide como é o padrão; o stroke-dashoffset decide em que ponto do caminho esse padrão começa.
Esta página explica como o deslocamento altera o padrão de traços, por que animá-lo produz o popular efeito de "linha que se desenha sozinha" e os valores que ele aceita.
O stroke-dashoffset pode ser definido de duas formas: como um atributo de apresentação no elemento SVG (stroke-dashoffset="5") ou como uma propriedade CSS (stroke-dashoffset: 5;). Quando ambos estão presentes, a regra CSS prevalece sobre o atributo de apresentação, e uma declaração style inline prevalece sobre ambos.
Como o deslocamento funciona
Imagine o padrão de traços como uma régua posicionada ao longo do caminho. O stroke-dashoffset desliza essa régua para frente ou para trás antes que o caminho seja pintado:
- Um valor positivo desloca o padrão para trás ao longo do caminho (o traço que estava logo antes do início entra em cena).
- Um valor negativo desloca o padrão para frente.
- O deslocamento se repete em torno do comprimento total de um ciclo traço-e-espaço, portanto um deslocamento igual ao comprimento do ciclo parece idêntico a
0.
Como o valor é apenas uma distância, as unidades (px, em) são opcionais no espaço de usuário SVG — um número simples é interpretado em unidades de usuário.
A propriedade stroke-dashoffset pode ser usada tanto como propriedade CSS quanto como atributo de apresentação. Pode ser aplicada a qualquer elemento, mas só tem efeito nos seguintes elementos: <altGlyph>, <circle>, <ellipse>, <path>, <line>, <polygon>, <polyline>, <rect>, <text>, <textPath>, <tref> e <tspan>.
As unidades "Px" ou "em" não são obrigatórias.
| Valor inicial | 0 |
|---|---|
| Aplica-se a | Elementos de forma e de conteúdo de texto. |
| Herdado | Sim. |
| Animável | Sim. |
| Versão | Especificação SVG 1.1 |
| Sintaxe DOM | Object.strokeDashoffset = 5; |
Sintaxe
Sintaxe CSS de stroke-dashoffset
stroke-dashoffset: length | percentage | initial | inherit;Exemplo da propriedade stroke-dashoffset:
O valor de stroke-dashoffset desloca o ponto de início do padrão de traços ao longo do caminho.
Exemplo de código CSS stroke-dashoffset
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<h2>Stroke-dashoffset property example</h2>
<svg viewBox="-3 0 33 10" >
<line x1="0" y1="1" x2="30" y2="1" stroke="#1c87c9" />
<line x1="0" y1="3" x2="30" y2="3" stroke="#ccc"
stroke-dasharray="4 1" />
<line x1="0" y1="5" x2="30" y2="5" stroke="#8ebf42"
stroke-dasharray="3 1"
stroke-dashoffset="3" />
<line x1="0" y1="7" x2="30" y2="7" stroke="#FF0000"
stroke-dasharray="3 1"
stroke-dashoffset="-3" />
<line x1="0" y1="9" x2="30" y2="9" stroke="#666"
stroke-dasharray="3 1"
stroke-dashoffset="1" />
<path d="M0,5 h-3 M0,7 h3 M0,9 h-1" stroke="#000"/>
</svg>
</body>
</html>Resultado
Cada linha acima usa o mesmo stroke-dasharray, mas um deslocamento diferente, portanto os traços se alinham em pontos de início distintos. O <path> de pequenas marcas mostra exatamente onde cada padrão começa.
A animação de "linha que se desenha sozinha"
O motivo mais comum para usar stroke-dashoffset é animar um SVG de forma que ele pareça se desenhar. O truque é definir tanto o array de traços quanto o deslocamento com o comprimento total do caminho: isso torna todo o contorno um único espaço gigante (invisível). Animar o deslocamento de volta para 0 desliza o traço único para a visão, desenhando a linha do início ao fim.
<!DOCTYPE html>
<html>
<head>
<style>
.draw {
fill: none;
stroke: #1c87c9;
stroke-width: 4;
/* One dash and one gap, each as long as the path */
stroke-dasharray: 300;
stroke-dashoffset: 300;
animation: draw 2s ease forwards;
}
@keyframes draw {
to {
stroke-dashoffset: 0;
}
}
</style>
</head>
<body>
<h2>Self-drawing line</h2>
<svg viewBox="0 0 110 110" width="160">
<path class="draw" d="M5,55 C5,5 105,5 105,55 S5,105 5,55" />
</svg>
</body>
</html>Para tornar isso exato para qualquer forma, leia o comprimento do caminho em JavaScript com path.getTotalLength() e use-o para o stroke-dasharray e o stroke-dashoffset inicial.
Problemas comuns
- O padrão não se move de jeito nenhum. O
stroke-dashoffsetsó funciona quando umstroke-dasharraytambém está definido. Sem traços, não há nada para deslocar. - Nenhum contorno visível. O elemento precisa de uma cor
strokee umstroke-widthdiferente de zero; o deslocamento não tem efeito em um contorno que não pode ser visto. - A animação de desenho só "desenha pela metade". Certifique-se de que tanto
stroke-dasharrayquanto ostroke-dashoffsetinicial sejam pelo menos tão longos quantogetTotalLength(); se forem menores, o espaço é pequeno demais para ocultar todo o caminho.
Valores
| Valor | Descrição |
|---|---|
| length | Define o comprimento da propriedade. As unidades "Px" ou "em" não são obrigatórias. |
| percentage | A propriedade é especificada em porcentagem. |
| initial | Faz a propriedade usar seu valor padrão. |
| inherit | Herda a propriedade do elemento pai. |