Balise HTML <ruby>

La balise HTML <ruby> définit une annotation ruby — un court segment de texte affiché à côté (généralement au-dessus) d'un texte de base pour indiquer sa prononciation ou sa signification. Les annotations ruby sont particulièrement répandues dans la typographie d'Asie de l'Est : par exemple, afficher la lecture phonétique d'un caractère chinois ou japonais pour permettre à un lecteur qui ne connaît pas le caractère de le prononcer.

La balise <ruby> est l'un des éléments HTML5.

Comment `<ruby>`, `<rt>` et `<rp>` fonctionnent ensemble

Une annotation ruby est construite à partir d'un petit groupe d'éléments qui agissent comme une unité unique :

<ruby> est le conteneur. Le texte de base (les caractères annotés) se place directement à l'intérieur.
<rt> (ruby text) contient l'annotation — la lecture ou la note affichée au-dessus du texte de base.
<rp> (ruby parenthesis) est un mécanisme de repli facultatif. Les navigateurs modernes masquent son contenu, mais les navigateurs ne prenant pas en charge ruby l'affichent à la place, entourant l'annotation de parenthèses afin que la page reste lisible.

Une annotation complète ressemble à ceci :

<ruby>base<rp>(</rp><rt>reading</rt><rp>)</rp></ruby>

Un navigateur compatible affiche reading empilé au-dessus de base. Un navigateur non compatible revient à la forme en ligne base(reading), c'est pourquoi les parenthèses <rp> sont importantes — sans elles, l'annotation serait directement accolée au texte de base sous la forme basereading.

Remarque : Vous pouvez trouver d'anciens exemples qui enveloppent le texte de base dans un élément <rb> (ruby base). <rb> est obsolète — le HTML moderne place le texte de base directement dans <ruby> sans balise englobante. Ne l'ajoutez pas à un nouveau balisage.

Syntaxe

La balise <ruby> s'utilise par paires. Le texte de base et ses annotations <rt>/<rp> sont écrits entre les balises ouvrante (<ruby>) et fermante (</ruby>).

Exemple : furigana japonais

En japonais, les furigana sont de petits caractères hiragana imprimés au-dessus des kanji pour indiquer comment le kanji se prononce. L'élément <ruby> est la méthode standard pour baliser les furigana sur le Web. Ici, le kanji 明日 (signifiant « demain ») est annoté avec sa lecture Ashita :

Balise HTML <ruby>

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <ruby>
      明日 <rp>(</rp><rt>Ashita</rt><rp>)</rp>
    </ruby>
  </body>
</html>

Essayez vous-même »

Résultat

Annoter chaque caractère séparément

Vous pouvez placer plusieurs paires caractère de base/<rt> à l'intérieur d'un même élément <ruby>. Chaque caractère de base est alors annoté avec sa propre lecture, et les lectures s'alignent au-dessus des caractères correspondants :

<ruby>
  漢 <rt>kan</rt>
  字 <rt>ji</rt>
</ruby>

Cela est utile lorsqu'un mot composé de plusieurs caractères se lit différemment selon les caractères. La même structure fonctionne pour le pinyin chinois (prononciation en lettres latines, par exemple 北京 avec Běi / jīng) et pour le bopomofo / zhuyin, où les symboles phonétiques sont placés à côté des caractères de base.

Mise en forme de ruby avec CSS

La balise <ruby> prend en charge les attributs globaux et les attributs d'événements. Elle ne possède pas d'attributs spécifiques à l'élément — l'apparence est contrôlée par CSS.

Vous pouvez colorier le texte de base et le texte d'annotation indépendamment en ciblant les sélecteurs ruby et rt :

ruby {
  color: blue;
}
rt {
  color: red;
}

Deux propriétés CSS sont spécifiques à la mise en page ruby :

ruby-position contrôle l'emplacement de l'annotation par rapport au texte de base. Les valeurs courantes sont over (au-dessus du texte de base — valeur par défaut pour la plupart des scripts), under (en dessous, parfois utilisé pour le bopomofo ou pour garder une hauteur de ligne cohérente), et alternate.
ruby-align contrôle la distribution de l'annotation et du texte de base lorsqu'ils diffèrent en longueur, par exemple start, center ou space-between.

ruby {
  ruby-position: under;
  ruby-align: center;
}

Compatibilité navigateur : Les éléments <ruby>, <rt> et <rp> sont bien pris en charge par tous les navigateurs modernes. La propriété ruby-position est également largement supportée, tandis que ruby-align bénéficie d'un support plus limité — testez-la avant de vous y fier, et conservez le repli <rp> afin que le sens reste intelligible même là où le style ruby est incomplet.

Pratique

Quel est le rôle de la balise HTML <ruby> ?

Elle est utilisée pour intégrer une vidéo.Elle est utilisée pour créer des sections dans un document.Elle représente une annotation ruby : de courts segments de texte affichés à côté du texte de base pour indiquer la prononciation, typiquement dans la typographie d'Asie de l'Est.Elle est utilisée pour définir les parenthèses de repli affichées dans les navigateurs ne la prenant pas en charge.Elle est utilisée pour insérer une image.

Comment <ruby>, <rt> et <rp> fonctionnent ensemble