Propiedad CSS stroke-dashoffset
Cómo usar la propiedad CSS stroke-dashoffset para especificar dónde debe comenzar el trazo discontinuo. Valores, ejemplos y casos de uso.
La propiedad stroke-dashoffset define la distancia a lo largo de una ruta SVG en la que comienza el patrón de guiones del trazo. Funciona en conjunto con stroke-dasharray, que establece las longitudes de los guiones y los espacios. stroke-dasharray determina cómo es el patrón; stroke-dashoffset determina en qué punto de la ruta comienza ese patrón.
Esta página explica cómo el desplazamiento mueve el patrón de guiones, por qué animarlo produce el popular efecto de "línea que se dibuja sola" y los valores que acepta.
stroke-dashoffset se puede establecer de dos formas: como atributo de presentación en el elemento SVG (stroke-dashoffset="5") o como propiedad CSS (stroke-dashoffset: 5;). Cuando ambas están presentes, la regla CSS tiene prioridad sobre el atributo de presentación, y una declaración style en línea tiene prioridad sobre ambas.
Cómo funciona el desplazamiento
Imagina el patrón de guiones como una regla colocada a lo largo de la ruta. stroke-dashoffset desliza esa regla hacia adelante o hacia atrás antes de pintar la ruta:
- Un valor positivo desplaza el patrón hacia atrás a lo largo de la ruta (el guión que estaba justo antes del inicio entra en el campo de visión).
- Un valor negativo desplaza el patrón hacia adelante.
- El desplazamiento se ajusta al total de la longitud de un ciclo guión-espacio, por lo que un desplazamiento igual a la longitud del ciclo tiene el mismo aspecto que
0.
Como el valor es simplemente una distancia, las unidades (px, em) son opcionales en el espacio de usuario SVG — un número sin unidad se interpreta en unidades de usuario.
La propiedad stroke-dashoffset puede usarse tanto como propiedad CSS como atributo de presentación. Se puede aplicar a cualquier elemento, pero solo tiene efecto en los siguientes: <altGlyph>, <circle>, <ellipse>, <path>, <line>, <polygon>, <polyline>, <rect>, <text>, <textPath>, <tref> y <tspan>.
Las unidades "px" o "em" no son obligatorias.
| Valor inicial | 0 |
|---|---|
| Se aplica a | Formas y elementos de contenido de texto. |
| Heredable | Sí. |
| Animable | Sí. |
| Versión | Especificación SVG 1.1 |
| Sintaxis DOM | Object.strokeDashoffset = 5; |
Sintaxis
Sintaxis CSS de stroke-dashoffset
stroke-dashoffset: length | percentage | initial | inherit;Ejemplo de la propiedad stroke-dashoffset:
El valor de stroke-dashoffset desplaza el punto de inicio del patrón de guiones a lo largo de la ruta.
Ejemplo 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 línea anterior utiliza el mismo stroke-dasharray pero un desplazamiento diferente, por lo que los guiones se alinean en distintos puntos de inicio. El <path> de pequeñas marcas de verificación muestra exactamente dónde comienza cada patrón.
La animación de "línea que se dibuja sola"
La razón más común para usar stroke-dashoffset es animar un SVG para que parezca dibujarse a sí mismo. El truco consiste en establecer tanto el array de guiones como el desplazamiento en la longitud total de la ruta: esto convierte todo el trazo en un espacio gigante (invisible). Animar el desplazamiento de vuelta a 0 desliza el único guión a la vista, dibujando la línea de principio a fin.
<!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 lograr este efecto con precisión en cualquier forma, lee la longitud de la ruta en JavaScript con path.getTotalLength() y úsala tanto para stroke-dasharray como para el stroke-dashoffset inicial.
Problemas comunes
- El patrón no se mueve en absoluto.
stroke-dashoffsetsolo funciona cuando también se establece unstroke-dasharray. Sin guiones no hay nada que desplazar. - No hay trazo visible. El elemento necesita un color de
strokey unstroke-widthdistinto de cero; el desplazamiento no tiene efecto en un trazo que no se puede ver. - La animación de dibujo solo se "dibuja a medias". Asegúrate de que tanto
stroke-dasharraycomo elstroke-dashoffsetinicial sean al menos tan largos comogetTotalLength(); si son más cortos, el espacio es demasiado pequeño para ocultar toda la ruta.
Valores
| Valor | Descripción |
|---|---|
| length | Establece la longitud de la propiedad. Las unidades "px" o "em" no son obligatorias. |
| percentage | La propiedad se especifica mediante un porcentaje. |
| initial | Hace que la propiedad use su valor predeterminado. |
| inherit | Hereda la propiedad de su elemento padre. |