Proprietà CSS stroke-dashoffset

La proprietà stroke-dashoffset definisce la distanza lungo un percorso SVG a partire dalla quale inizia il pattern di trattini del bordo. Funziona in sinergia con stroke-dasharray, che imposta le lunghezze dei trattini e degli spazi. stroke-dasharray determina come appare il pattern; stroke-dashoffset determina dove lungo il percorso quel pattern ha inizio.

Questa pagina spiega come l'offset sposta il pattern di trattini, perché animarlo produce il popolare effetto "linea che si disegna da sola", e quali valori accetta.

stroke-dashoffset può essere impostato in due modi: come attributo di presentazione sull'elemento SVG (stroke-dashoffset="5") oppure come proprietà CSS (stroke-dashoffset: 5;). Quando entrambi sono presenti, la regola CSS ha la precedenza sull'attributo di presentazione, e una dichiarazione style inline ha la precedenza su entrambi.

Come funziona l'offset

Immagina il pattern di trattini come un righello posizionato lungo il percorso. stroke-dashoffset fa scorrere quel righello in avanti o indietro prima che il percorso venga disegnato:

Un valore positivo sposta il pattern indietro lungo il percorso (il trattino che si trovava appena prima dell'inizio entra nel campo visivo).
Un valore negativo sposta il pattern in avanti.
L'offset si avvolge attorno alla lunghezza totale di un ciclo trattino-spazio, quindi un offset pari alla lunghezza del ciclo appare identico a 0.

Poiché il valore è semplicemente una distanza, le unità (px, em) sono facoltative nello spazio utente SVG — un numero senza unità viene interpretato in unità utente.

Informazione

La proprietà stroke-dashoffset può essere usata sia come proprietà CSS che come attributo di presentazione. Può essere applicata a qualsiasi elemento, ma produce effetti solo sui seguenti elementi: <altGlyph>, <circle>, <ellipse>, <path>, <line>, <polygon>, <polyline>, <rect>, <text>, <textPath>, <tref> e <tspan>.

Informazione

Le unità "Px" o "em" non sono obbligatorie.

Valore iniziale	0
Si applica a	Forme ed elementi di contenuto testuale.
Ereditato	Sì.
Animabile	Sì.
Versione	SVG 1.1 Specification
Sintassi DOM	Object.strokeDashoffset = 5;

Sintassi

Sintassi CSS di stroke-dashoffset

stroke-dashoffset: length | percentage | initial | inherit;

Esempio della proprietà stroke-dashoffset:

Il valore stroke-dashoffset sposta il punto di partenza del pattern di trattini lungo il percorso.

Esempio di codice 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>

Provalo tu stesso »

Risultato

Ogni linea sopra usa lo stesso stroke-dasharray ma un offset diverso, quindi i trattini si allineano in punti di partenza differenti. Il <path> di piccoli segni di graduazione mostra esattamente dove inizia ogni pattern.

L'animazione "linea che si disegna da sola"

Il motivo più comune per usare stroke-dashoffset è animare un SVG in modo che sembri disegnarsi da solo. Il trucco consiste nell'impostare sia il dash array sia l'offset alla lunghezza totale del percorso: questo trasforma l'intero bordo in un unico grande spazio vuoto (invisibile). Animando l'offset fino a 0 si fa scorrere il singolo trattino nel campo visivo, disegnando la linea dall'inizio alla fine.

<!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>

Per rendere questa tecnica precisa per qualsiasi forma, leggi la lunghezza del percorso in JavaScript con path.getTotalLength() e usala sia per stroke-dasharray sia per il valore iniziale di stroke-dashoffset.

Problemi comuni

Il pattern non si muove affatto. stroke-dashoffset produce un effetto solo quando è impostato anche un stroke-dasharray. Senza trattini non c'è nulla da scostare.
Nessun bordo visibile. L'elemento deve avere un colore stroke e un stroke-width diverso da zero; l'offset non ha effetto su un bordo che non si vede.
L'animazione di disegno si ferma a metà. Assicurati che sia stroke-dasharray sia il valore iniziale di stroke-dashoffset siano almeno pari a getTotalLength(); se sono più corti, lo spazio è troppo piccolo per nascondere l'intero percorso.

Valori

Valore	Descrizione
length	Imposta la lunghezza della proprietà. Le unità "Px" o "em" non sono obbligatorie.
percentage	La proprietà è specificata come percentuale.
initial	Fa usare alla proprietà il suo valore predefinito.
inherit	Eredita la proprietà dall'elemento padre.

Pratica

Qual è lo scopo della proprietà CSS stroke-dashoffset e come viene utilizzata?

Viene usata per modificare la posizione dei trattini in una linea tratteggiata.Specifica le dimensioni dell'immagine del bordo.Modifica lo stile del contorno di un elemento.Usa valori <length> per definire l'offset del trattino del bordo.Accetta solo valori percentuali per definire l'offset del trattino del bordo.