Element <ruby> to specjalistyczny tag HTML do tworzenia adnotacji ruby – małych wyjaśnień fonetycznych lub interpretacyjnych wyświetlanych nad, pod lub obok tekstu bazowego. Dzięki niemu możesz wiernie oddać wymowę znaków w tekstach wschodnioazjatyckich (np. furigana w japońskim, pinyin w chińskim, hangul w koreańskim) i poprawić czytelność treści.
Historia i przeznaczenie elementu <ruby>
Pojęcie „ruby” wywodzi się z tradycji drukarskiej Japonii, gdzie adnotacje fonetyczne drukowano drobną czcionką o rozmiarze 5,5 punktu, nazwaną właśnie ruby (lub rubi). W HTML element ten wprowadzono, aby odwzorować tę konwencję typograficzną i zapewnić prawidłowe, semantyczne i dostępne wyświetlanie w językach takich jak japoński, chiński czy koreański.
Głównym zastosowaniem <ruby> jest prezentacja treści wymagającej adnotacji wymowy lub interpretacji. Kontekst wewnętrzny powinien zawierać: tekst bazowy, adnotacje oraz opcjonalny fallback dla przeglądarek bez wsparcia.
We współczesnych przeglądarkach (m.in. Chrome od wersji 128) <ruby> obsługuje zaawansowane funkcje, takie jak przełamywanie wierszy w adnotacjach i pełną stylizację za pomocą CSS.
Struktura elementu <ruby>
Podstawowa budowa <ruby> wymaga ścisłej hierarchii elementów potomnych:
<rb>– tekst bazowy (podstawa ruby), np. znaki kanji;<rt>lub<rtc>– tekst adnotacji (ruby text), wyświetlany nad/pod bazą;<rp>– opcjonalny fallback w nawiasach dla starszych przeglądarek bez wsparcia ruby.
Wymagane elementy dzieci – co najmniej jeden <rb> oraz przynajmniej jeden <rt> lub <rtc>. Tagi otwierające i zamykające są obowiązkowe – nie wolno ich pomijać.
Domyślny styl CSS dla ruby to display: ruby;, który aktywuje specjalny tryb układu w obsługujących przeglądarkach.
Podstawowy przykład kodu HTML
Oto prosty przykład z japońskiego tekstu „日本語” (nihongo – język japoński):
<p>
<ruby>
<rb>日本語</rb>
<rp>(</rp>
<rt>nihongo</rt>
<rp>)</rp>
</ruby>
</p>
W przeglądarce z odpowiednim wsparciem renderuje się to jako: 日本語(nihongo) – gdzie „nihongo” pojawia się nad znakami bazowymi (jako mały tekst ruby).
Pozycjonowanie i stylizacja z CSS
Domyślnie adnotacje ruby wyświetlają się nad tekstem bazowym. Możesz to zmienić właściwością CSS ruby-position:
<ruby style="ruby-position: under;">
強南大路<rt>江南大路</rt>
</ruby>
To umieszcza adnotację pod bazą, np. dla koreańskiego „강남대로” z chińską wymową.
W pracy ze stylami przydają się również następujące właściwości:
ruby-align– wyrównanie adnotacji względem tekstu bazowego;ruby-merge– kontrola łączenia i grupowania adnotacji nad/pod bazą;white-space: nowrap– wyłącza przełamywanie wiersza wewnątrz ruby.
Przykład z emoji i stylizacją
Poniższy przykład łączy pozycjonowanie i skalowanie tekstu ruby:
<ruby style="ruby-position: under; font-size: 1.2em;">
絵文字<rt>emoji</rt>
</ruby>
Renderuje: 絵文字 z „emoji” pod spodem, w lekko powiększonej formie.
Zaawansowane funkcje – przełamywanie wierszy (od Chrome 128)
Przed Chrome 128 długie adnotacje ruby potrafiły zniekształcać układ. Teraz ruby jest line-breakable, co pozwala naturalnie zawijać długie adnotacje nad zawijaną bazą – również przy końcu wiersza.
Przykład z poezją chińską (pinyin):
<ruby>
<rb>床前明月光</rb>
<rt>chuáng qián míng yuè guāng</rt>
</ruby>
We wcześniejszych wersjach długi pinyin mógł się „psuć”. Teraz zawija się poprawnie nad bazą, a krótkie sekwencje (np. do kilku znaków) zwykle nie są dzielone. Zagnieżdżone <ruby> blokują przełamywanie.
Wyłączenie przełamywania (dla kompatybilności):
ruby {
white-space: nowrap;
}
To pomaga na istniejących stronach z długimi adnotacjami ruby.
Kompatybilność i fallback
Poniżej kluczowe kwestie zgodności, o których warto pamiętać:
- Wsparcie przeglądarek – pełne w nowoczesnych (Chrome, Firefox, Safari, Edge); starsze korzystają z fallbacku w
<rp>; - CSS display –
ruby { display: ruby; }działa tylko, jeśli przeglądarka zna tryb ruby; - Semantyka i dostępność – poprawia doświadczenie czytników ekranu i ułatwia naukę wymowy w językach azjatyckich.
Element nie posiada wymaganych atrybutów – cała semantyka opiera się na poprawnie zagnieżdżonych elementach potomnych.
Praktyczne zastosowania poza Azją
Mimo że <ruby> powstał z myślą o typografii wschodnioazjatyckiej, można go używać kreatywnie także w innych kontekstach:
- Nauczanie języków – furigana nad trudniejszym słownictwem dla uczących się japońskiego;
- Gry i aplikacje – krótkie „tooltipy” nad symbolami lub ikonami bez zajmowania dodatkowego miejsca;
- Poezja wielojęzyczna – romanizacja nad oryginałem dla porównania brzmienia;
- Dostępność – podpowiedzi wymowy i znaczenia dla dzieci lub osób z trudnościami w czytaniu.
Przykład wieloliniowy z przełamywaniem (symulacja literatury japońskiej):
<p>
Długi tekst z
<ruby>
<rb>非常に長い漢字の例</rb>
<rt>hiromaru nagai kanji no rei yondomu yokuwakaru</rt>
</ruby>
i końcem wiersza.
</p>
W Chrome 128 znak końca wiersza może wypaść wewnątrz sekwencji ruby, co eliminuje nieestetyczne puste przestrzenie.
Najczęstsze błędy i dobre praktyki
Poniżej zebrano typowe potknięcia oraz wskazówki, jak im zapobiegać:
- Błąd – brak
<rb>lub<rt>w strukturze, przez co dokument nie przechodzi poprawnej walidacji; - Rozwiązanie – zawsze stosuj pełną strukturę i dodaj
<rp>jako fallback dla starszych przeglądarek; - Błąd – bardzo długie adnotacje ruby bez kontroli zawijania w starszych przeglądarkach;
- Dobre praktyki – trzymaj adnotacje zwięzłe, testuj w wielu silnikach i zadbaj o czytelny kontrast.
Oto krótkie wskazówki krok po kroku:
- Testuj w Chrome DevTools (w razie potrzeby włącz eksperymentalne funkcje ruby).
- Używaj
ruby-position, aby sprawdzić czytelność adnotacji nad i pod tekstem bazowym. - Przy zagnieżdżeniach unikaj wewnętrznego przełamywania, jeśli pogarsza układ.
- Dodaj atrybuty ARIA dla dostępności, np.
aria-describedbydla powiązania adnotacji z bazą.