Propriété CSS offset-distance

La propriété CSS offset-distance définit la distance parcourue par un élément le long de son chemin de mouvement — le chemin défini par la propriété offset-path. Pensez à offset-path comme un rail, et à offset-distance comme la position de l'élément sur ce rail : 0 le place au début, 100% à la fin.

C'est l'un des éléments fondamentaux du module CSS Motion Path, qui permet à un élément de se déplacer le long d'une forme arbitraire (une ligne, une courbe, un chemin SVG) plutôt que d'être limité aux transitions rectilignes avec top/left. Seule, offset-distance est statique, mais l'animer de 0 à 100% est ce qui fait glisser l'élément le long du chemin.

Quand l'utiliser

Animer un élément le long d'un chemin courbe ou personnalisé — un avion suivant une route, une perle sur un fil, une icône traçant un cercle. Les transitions CSS rectilignes ne peuvent pas faire cela ; un chemin de mouvement le peut.
Arrêter un élément à un point précis sur un chemin — définissez une valeur fixe telle que offset-distance: 50% pour placer l'élément à mi-chemin de son offset-path.
Mouvement piloté par le défilement ou l'interaction — mettez à jour offset-distance avec JavaScript (ou une animation de défilement) pour déplacer un élément le long d'un chemin en réponse aux actions de l'utilisateur.

offset-distance n'a aucun effet si l'élément ne possède pas également un offset-path. Sans chemin, il n'y a rien par rapport à quoi mesurer la distance.

Valeurs

Elle accepte une seule valeur <length-percentage> :

<length> — une distance absolue depuis le début du chemin, par exemple 40px.
<percentage> — une distance relative à la longueur totale du chemin. 0% est le début, 100% est la fin.

La valeur initiale est 0.

Info

Les valeurs négatives et supérieures à 100 % sont valides. Une valeur comme -20% ou 120% étend l'élément au-delà des extrémités du chemin ; pour un chemin fermé, il fait le tour. C'est pratique lorsque vous souhaitez qu'un élément commence hors du chemin et s'y anime.

Avertissement

offset-distance fait partie du module CSS Motion Path expérimental. Dans les premières versions de la spécification, cette propriété s'appelait motion-offset. Vérifiez la prise en charge actuelle par les navigateurs avant de l'utiliser en production.

Propriété	Valeur
Valeur initiale	`0`
S'applique à	Éléments transformables
Héritée	Non
Animatable	Oui
Version	Motion Path Module Level 1
Syntaxe DOM	`object.style.offsetDistance = "100%";`

Syntaxe

offset-distance: <length-percentage>;

Par exemple :

/* A fixed point partway along the path */
offset-distance: 70%;

/* Absolute distance from the start */
offset-distance: 50px;

/* Animate from start to end of the path */
@keyframes move {
  to {
    offset-distance: 100%;
  }
}

Exemples

Animer un élément le long d'un chemin personnalisé

L'élément ci-dessous possède un offset-path en forme de courbe. Animer offset-distance de sa valeur par défaut 0 à 100% fait glisser le bloc en douceur le long de ce chemin. Notez que offset-rotate: reverse fait pivoter le bloc pour qu'il soit orienté dans la direction du déplacement.

Exemple représenté avec une maison et des ciseaux

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      body {
        background-color: #ccc;
      }
      .mover {
        width: 80px;
        height: 80px;
        background: linear-gradient(#eee 50%, #1c87c9 50%);
        position: absolute;
        left: 20%;
        top: 100px;
        offset-path: path("M18.45,58.46s52.87-70.07,101.25-.75,101.75-6.23,101.75-6.23S246.38,5.59,165.33,9.08s-15,71.57-94.51,74.56S18.45,58.46,18.45,58.46Z");
        offset-rotate: reverse;
        animation: move 4s linear infinite;
      }
      @keyframes move {
        100% {
          offset-distance: 100%;
        }
      }
    </style>
  </head>
  <body>
    <h2>Offset-distance property example</h2>
    <div class="mover"></div>
  </body>
</html>

Essayez vous-même »

Spécifier la distance en pourcentage

Ici, la valeur s'anime en pourcentage de la longueur totale du chemin, de sorte que l'élément effectue exactement un passage complet quelle que soit la longueur du chemin. Utiliser 100% plutôt qu'une longueur absolue est la méthode la plus portable pour animer le long d'un chemin.

Exemple de la propriété CSS offset-distance

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      .scissorHalf {
        offset-path: path('M900,190  L993,245 V201  A11,11 0 0,1 1004,190  H1075  A11,11 0 0,1 1086,201  V300  L1294,423 H1216  A11,11 0 0,0 1205,434  V789  A11,11 0 0,1 1194,800  H606  A11,11 0 0,1 595,789  V434  A11,11 0 0,0 584,423  H506 L900,190');
        animation: followpath 4s linear infinite;
      }
      @keyframes followpath {
        to {
          offset-distance: 100%;
        }
      }
    </style>
  </head>
  <body>
    <h2>Offset-distance property example</h2>
    <svg class="box" width="700" height="450" viewBox="350 0 1400 900">
      <title>House and Scissors</title>
      <rect x="595" y="423" width="610" height="377" fill="#1c87c9" />
      <polygon points="506,423 900,190 1294,423" fill="#8ebf42" />
      <polygon points="993,245 993,190 1086,190 1086,300" fill="#666" />
      <path id="house" d="M900,190 L993,245 V201 A11,11 0 0,1 1004,190 H1075 A11,11 0 0,1 1086,201 V300 L1294,423 H1216 A11,11 0 0,0 1205,434 V789 A11,11 0 0,1 1194,800 H606 A11,11 0 0,1 595,789 V434 A11,11 0 0,0 584,423 H506 L900,190" fill="none" stroke="black" stroke-width="13" stroke-linejoin="round" stroke-linecap="round" />
      <path id="secondScissorHalf" class="scissorHalf" d="M30,0 H-10 A10,10 0 0,1 -20,-10 A20,20 0 1,0 -40,10 H20 A10,10 0 0,0 30,0 M-40,-20 A10,10 1 0,0 -40,0 A10,10 1 0,0 -40,-20 M0,0" transform="translate(0,0)" fill="forestgreen" stroke="black" stroke-width="5" stroke-linejoin="round" stroke-linecap="round" fill-rule="evenodd" />
    </svg>
  </body>
</html>

Essayez vous-même »

Valeurs acceptées

Valeur	Description
`<length-percentage>`	Une longueur ou un pourcentage indiquant la position le long du chemin offset, mesurée depuis son début.
`initial`	Définit la propriété à sa valeur par défaut (`0`).
`inherit`	Hérite la valeur de l'élément parent.

Propriétés associées

offset-distance est rarement utilisée seule — elle fonctionne avec les autres propriétés CSS Motion Path :

offset-path — définit le chemin le long duquel l'élément se déplace.
offset-rotate — contrôle la rotation de l'élément au fur et à mesure qu'il suit le chemin.
offset-anchor — choisit quel point de l'élément est placé sur le chemin.
offset — le raccourci qui définit toutes les propriétés de chemin de mouvement à la fois.
animation — pilote les images-clés de offset-distance qui produisent le mouvement.

Pratique

Que permet la propriété CSS 'offset-distance' ?

Elle permet de définir le dégradé pour un arrière-plan en dégradé linéaire.Elle permet de définir la distance le long du chemin à laquelle l'élément doit être positionné.Elle permet de définir une marge entre deux éléments.Elle permet de définir la rotation d'un élément.Elle permet de placer un élément le long d'un chemin identifié.