Fragments de texte

Concepts et utilisation

Historiquement, l'une des caractéristiques clés du web a toujours été sa capacité à fournir des liens entre différents documents — c'est ce qui fait du web un réseau :

• Vous pouvez lier le haut d'un document en pointant vers son URL, par exemple :
  • https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a.
• Vous pouvez lier une section spécifique d'un document en pointant vers son URL plus le fragment de document (ID) de cette section, par exemple :
  • https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a#compatibilité_des_navigateur.

Le problème avec les liens vers des fragments de document spécifiques est que l'auteur·ice de la page liée doit placer une ancre pour que le lien fonctionne réellement. Le second exemple ci-dessus pointe vers un élément h2 avec un ID compatibilité_des_navigateur :

<h2 id="compatibilité_des_navigateur">
  <a href="#compatibilité_des_navigateur">Compatibilité des navigateurs</a>
</h2>

Tous les documents ne possèdent pas de telles ancres, et même s'ils en ont, lier un titre peut être bien moins précis que de lier directement le texte cité. C'est là que les fragments de texte sont utiles : ils permettent à l'auteur·ice du lien de contrôler exactement le texte à cibler, sans nécessiter de balisage particulier dans le document cible. Par exemple, un moteur de recherche peut référencer une phrase précise dans ses résultats, et cliquer sur le lien amènera directement à cette phrase.

Cependant, les fragments de texte ont aussi une limite : le texte d'un document est moins stable que sa structure. Si le texte du document lié est modifié, le fragment ne correspond plus et le navigateur va en haut de la page. Cela convient pour des liens temporaires comme ceux des résultats de recherche, mais si vous souhaitez que le lien fonctionne dans le temps, les fragments de document sont plus fiables.

Syntaxe

https://example.com#:~:text=[prefix-,]textStart[,textEnd][,-suffix]

Les fragments de texte sont un type de fragment d'URL, et s'écrivent après le #. Les éléments clés à comprendre sont les suivants :

:~:

Aussi appelée directive de fragment, cette séquence de caractères indique au navigateur que ce qui suit est une ou plusieurs instructions à destination de l'agent utilisateur, qui sont retirées de l'URL lors du chargement afin que les scripts de l'auteur·ice ne puissent pas y accéder directement. Les instructions d'agent utilisateur sont aussi appelées directives.

text=

Une directive de texte. Elle fournit un fragment de texte au navigateur, définissant le texte à cibler dans le document lié.

textStart

Une chaîne de caractères définissant le début du texte ciblé.

textEnd Facultatif

Une chaîne de caractères définissant la fin du texte ciblé.

prefix- Facultatif

Une chaîne de caractères suivie d'un tiret, définissant le texte qui doit précéder immédiatement le texte ciblé (en autorisant uniquement des espaces entre les deux). Cela aide le navigateur à sélectionner le bon texte ciblé en cas de correspondances multiples.

-suffix Facultatif

Un tiret suivi d'une chaîne de caractères, définissant le texte qui doit suivre immédiatement le texte ciblé (en autorisant uniquement des espaces entre les deux). Cela aide le navigateur à sélectionner le bon texte ciblé en cas de correspondances multiples.

Les navigateurs compatibles feront défiler la page et surligneront le premier fragment de texte du document lié qui correspond à la directive spécifiée. Il est possible de définir plusieurs fragments de texte à surligner dans la même URL en les séparant par des esperluettes (&).

Notes d'utilisation

• Les chaînes de caractères utilisées pour les valeurs textStart, textEnd, prefix- et -suffix doivent être encodées en pourcentage. De plus, la norme ^(angl.) exige que le tiret sûr pour les URLs '-' soit également encodé en pourcentage.

• Les correspondances ne tiennent pas compte de la casse.

• Chaque chaîne de caractères textStart, textEnd, prefix- et -suffix doit se trouver entièrement dans le même élément de niveau bloc, mais les correspondances complètes peuvent s'étendre sur plusieurs éléments.

• Pour des raisons de sécurité, lors de la création d'un lien vers une page d'un autre site avec cette fonctionnalité, il faut ouvrir le lien dans un contexte noopener — ajoutez rel="noopener" à vos éléments HTML <a>, et ajoutez noopener à vos appels window.open() lors de l'utilisation de cette fonctionnalité.

• Les fragments de texte ne sont invoqués que lors de navigations initiées par l'utilisateur·ice.

• Les fragments de texte ne s'appliquent qu'à la trame principale : le texte ne sera pas recherché dans les <iframe>, et la navigation dans un iframe n'invoquera pas de fragment de texte.

• Pour les sites qui souhaitent se désengager, les navigateurs basés sur Chromium prennent en charge une valeur d'en-tête Document Policy ^(angl.) que l'on peut envoyer pour que les agents utilisateur n'interprètent pas les fragments de texte :

  http

  Document-Policy: force-load-at-top
  

Exemples

Fragment de texte avec textStart

• https://example.com/#:~:text=use fait défiler et surligne la première occurrence du texte use dans le document.
• https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a#:~:text=human fait défiler et surligne la première occurrence du texte human dans le document.
• https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a#:~:text=linked%20URL fait défiler et surligne la première occurrence du texte linked URL dans le document.

textStart et textEnd

• https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a#:~:text=human,URL scrolls to and highlights the first instance of a text string starting with human and ending with URL.
• https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a#:~:text=linked%20URL,defining%20a%20value scrolls to and highlights the first instance of a text string starting with linked URL and ending with defining a value. Note how the highlighted text spans across multiple block-level elements.

Exemples avec prefix- et/ou -suffix

• https://example.com/#:~:text=avoid-,use fait défiler et surligne la deuxième occurrence du texte use dans le document.
• https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a#:~:text=sent-,referrer fait défiler et surligne la première occurrence du texte referrer précédée directement du texte sent. Il s'agit de la 5^e occurrence de referrer dans le document ; sans le préfixe, la première occurrence serait surlignée.
• https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a#:~:text=linked%20URL,-'s%20format fait défiler et surligne la première occurrence du texte linked URL suivie directement du texte 's format. Il s'agit de la 5^e occurrence de linked URL dans le document ; sans le suffixe, la première occurrence serait surlignée.
• https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a#:~:text=downgrade:-,The%20Referer,be%20sent,-to%20origins fait défiler et surligne l'occurrence du texte The Referer ... be sent précédée de downgrade: et suivie de to origins. Cela illustre un exemple plus complexe où le préfixe/suffixe sont utilisés pour cibler précisément l'occurrence souhaitée. Essayez de retirer le préfixe, par exemple, pour voir ce qui est alors surligné.

URLs avec plusieurs fragments de texte

Vous pouvez définir plusieurs fragments de texte à surligner dans la même URL en les séparant par des esperluettes (&). Voici quelques exemples :

• https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a#:~:text=Causes&text=linked fait défiler et surligne les premières occurrences des chaînes de caractères Causes et linked.
• https://developer.mozilla.org/fr/docs/Web/HTML/Reference/Elements/a#:~:text=linked%20URL,-'s%20format&text=Deprecated-,attributes,attribute fait défiler et surligne deux occurrences de texte :
  • La première occurrence du texte linked URL suivie directement du texte 's format.
  • La première occurrence d'une chaîne de caractères commençant par attributes et se terminant par attribute, précédée de Deprecated.

Si vous ne voyez pas un ou plusieurs de vos fragments de texte surlignés alors que vous êtes certain·e d'avoir la bonne syntaxe, il se peut que ce soit une autre occurrence que celle attendue. Elle peut être surlignée, mais hors écran.

Mise en forme des fragments de texte surlignés

Les navigateurs sont libres de styliser le texte surligné comme ils le souhaitent par défaut. Le module CSS Pseudo-Elements Level 4 ^(angl.) définit un pseudo-élément, ::target-text, qui permet de personnaliser la mise en forme.

Par exemple, dans notre démo scroll-to-text ^(angl.), nous avons le CSS suivant :

::target-text {
  background-color: rebeccapurple;
  color: white;
}

Essayez de suivre le lien ci-dessus dans un navigateur compatible pour voir l'effet obtenu.

Détection de la fonctionnalité

L'objet FragmentDirective, accessible via la propriété Document.fragmentDirective, permet de tester si les fragments de texte sont pris en charge dans un navigateur.

Essayez d'exécuter ce qui suit dans les outils de développement d'un navigateur compatible, dans un onglet avec un ou plusieurs fragments de texte surlignés :

document.fragmentDirective;
// retourne un objet FragmentDirective vide, si pris en charge
// undefined sinon

Cette fonctionnalité sert principalement à la détection de prise en charge pour l'instant. À l'avenir, l'objet FragmentDirective pourrait inclure des informations supplémentaires.

Référence

API

FragmentDirective

Un objet représentant les fragments de texte. Actuellement vide et principalement destiné à la détection de fonctionnalité.

Document.fragmentDirective

Retourne l'objet FragmentDirective du document courant.

CSS

::target-text

Représente les fragments de texte surlignés dans le document courant. Permet aux auteur·ice·s de personnaliser la mise en forme des fragments de texte.

Spécifications

Compatibilité des navigateurs

html.elements.a.text_fragments

api.FragmentDirective

css.selectors.target-text

Voir aussi

• Créer des liens profonds vers du texte : Text Fragments ^(angl.)