Każdy powtarzający się symbol umieść we własnym zewnętrznym elemencie SVG z dostępną nazwą, ponownie wykorzystując wyłącznie znajdujący się w nim rysunek. Ten poradnik pokazuje, jak na Macu zbudować niewielką listę podpisanych grafik i oddzielić układ strony, współrzędne SVG oraz nadawanie dostępnych nazw.

W przypadku prostej grafiki MDN zaleca umieszczenie role="img" i etykiety na zewnętrznym elemencie SVG, aby technologie asystujące mogły traktować go jako jeden obraz. Praktyczny wzorzec polega na utworzeniu osobnego elementu opakowującego dla każdego wystąpienia i wskazaniu w każdym z nich własnej etykiety. Rola ARIA: img

Gdzie umieścić dostępną etykietę każdej instancji?

Nazwę umieść na elemencie reprezentującym dane wystąpienie. Gdy kilka osobnych grafik korzysta z tego samego symbolu, nadaj każdemu zewnętrznemu elementowi svg własne odwołanie aria-labelledby albo aria-label. Wspólny symbol powinien zawierać wyłącznie geometrię przeznaczoną do ponownego użycia.

Wynika to z różnicy między definicją a jej renderowanymi instancjami. Element SVG use odwołuje się do grafik i renderuje ponownie używaną zawartość za pośrednictwem drzewa cieni; wygenerowane kształty nie są zwykłymi węzłami potomnymi w DOM strony. Ponowne użycie rysunku nie tworzy więc w HTML osobnych, edytowalnych kopii jego wewnętrznej etykiety. Struktura dokumentu — SVG 2

Tytuł zapisany we wspólnym symbolu nie może też zapewnić różnego tekstu dla poszczególnych wystąpień bez zastosowania innego mechanizmu nadawania nazw. Na przykład ten sam neutralny rysunek kafelka może w jednym miejscu oznaczać Próbka Alfa, a w innym Próbka Beta. Nazwy te należy powiązać z dwoma wystąpieniami, mimo że ich geometria jest identyczna.

Wybierz sposób nadawania nazwy odpowiednio do tego, gdzie znajduje się potrzebny tekst:

Sytuacja Zalecany wzorzec
Krótki widoczny podpis określa grafikę Na zewnętrznym elemencie SVG użyj aria-labelledby, wskazując unikalny identyfikator.
Grafika wymaga nazwy, ale nie ma widocznego podpisu Umieść unikalny element title wewnątrz każdego zewnętrznego elementu SVG i odwołaj się do niego za pomocą aria-labelledby albo użyj aria-label.
Grafika jedynie ozdabia tekst, który już przekazuje wszystkie potrzebne informacje Ukryj SVG przed technologiami asystującymi zamiast dodawać zbędną nazwę.
Kilka wystąpień ma być osobno dostępnych dla użytkownika Nie grupuj ich wszystkich w jeden zewnętrzny obraz role="img".

MDN zaleca odwoływanie się do widocznego tekstu, jeśli może on nazwać SVG. Dokumentacja roli obrazu wyjaśnia też, że role="img" przedstawia zawartość jako jeden element, dlatego granica elementu opakowującego ma znaczenie. Element SVG nadający dostępną nazwę, Rola ARIA: img

Zbuduj kompletną stronę z dwiema instancjami o niezależnych nazwach

Poniższy przykład to kompletny dokument HTML zawierający wyłącznie syntetyczny tekst oraz prosty rysunek z kołem i kwadratem. Nie wymaga JavaScriptu, zewnętrznego arkusza symboli, biblioteki ani procesu budowania. Na Macu zapisz go w edytorze kodu zwykłego tekstu jako symbol-labels.html, a następnie otwórz plik w przeglądarce na komputerze.

Oba wystąpienia odwołują się do tile-mark, ale zewnętrzne elementy SVG wskazują różne widoczne podpisy. Jest to wzorzec nadawania nazw na podstawie widocznego tekstu opisany przez MDN. Atrybut href to aktualny mechanizm odwołań w SVG; MDN oznacza xlink:href jako przestarzały. Element SVG nadający dostępną nazwę, Element SVG use

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Independently labeled SVG instances</title>
  <style>
    body {
      margin: 2rem;
      font-family: system-ui, sans-serif;
      color: #222;
    }
    .sprite {
      position: absolute;
      width: 0;
      height: 0;
      overflow: hidden;
    }
    .samples {
      display: grid;
      grid-template-columns: repeat(2, minmax(0, 1fr));
      gap: 1rem;
      max-width: 36rem;
      padding: 0;
      list-style: none;
    }
    .sample {
      padding: 1rem;
      border: 1px solid #777;
    }
    .sample svg {
      display: block;
      width: 5rem;
      height: 5rem;
      margin-bottom: 0.75rem;
    }
    @media (max-width: 30rem) {
      .samples { grid-template-columns: 1fr; }
    }
  </style>
</head>
<body>
  <svg class="sprite" xmlns="http://www.w3.org/2000/svg"
       aria-hidden="true">
    <defs>
      <symbol id="tile-mark" viewBox="0 0 48 48">
        <rect x="4" y="4" width="40" height="40" rx="6"
              fill="none" stroke="currentColor" stroke-width="2" />
        <circle cx="24" cy="24" r="9" fill="currentColor" />
      </symbol>
    </defs>
  </svg>

  <h1>Sample tiles</h1>
  <ul class="samples">
    <li class="sample">
      <svg xmlns="http://www.w3.org/2000/svg"
           viewBox="0 0 48 48" role="img"
           aria-labelledby="sample-alpha-label">
        <use href="#tile-mark" width="48" height="48"
             aria-hidden="true" />
      </svg>
      <span id="sample-alpha-label">Sample Alpha</span>
    </li>
    <li class="sample">
      <svg xmlns="http://www.w3.org/2000/svg"
           viewBox="0 0 48 48" role="img"
           aria-labelledby="sample-beta-label">
        <use href="#tile-mark" width="48" height="48"
             aria-hidden="true" />
      </svg>
      <span id="sample-beta-label">Sample Beta</span>
    </li>
  </ul>
</body>
</html>

Zamierzone dostępne nazwy to Próbka Alfa i Próbka Beta. Są to oczekiwane wyniki wynikające z kodu, a nie rezultaty zgłoszonych testów w przeglądarce. Rysunek wewnątrz każdego elementu opakowującego jest jawnie ukryty przed technologiami asystującymi, a nazwany zewnętrzny element SVG pozostaje dostępny. Mapowania dostępności SVG rozróżniają ukryte elementy potomne od udostępnionego elementu nadrzędnego. Mapowania API dostępności SVG

Dodając trzecie wystąpienie, ponownie użyj href="#tile-mark", utwórz nowy identyfikator podpisu i zaktualizuj aria-labelledby tego wystąpienia, aby do niego pasowało. Wspólne pozostaw odwołanie do symbolu, a odwołanie do etykiety przypisz konkretnemu wystąpieniu.

Widoczne podpisy mogą być też odczytywane osobno przez czytnik ekranu. Jeśli kafelek nie wnosi niczego ponad to, co przekazuje podpis, zastosuj wzorzec dla elementów dekoracyjnych: usuń role="img" i aria-labelledby z zewnętrznego elementu SVG, a następnie dodaj do niego aria-hidden="true". Widoczny podpis pozostaw. Mapowania SVG opisują wykluczanie za pomocą aria-hidden. Mapowania API dostępności SVG

Który mechanizm przeglądarki steruje poszczególnymi częściami układu?

W tym przykładzie są trzy niezależne zadania: rozmieszczenie kart, rysowanie symbolu i obliczanie dostępnych nazw. Zmiana jednego z nich nie powoduje automatycznego wykonania pozostałych.

CSS Grid rozmieszcza elementy listy HTML. Deklaracja display: grid sprawia, że bezpośrednie elementy potomne kontenera stają się elementami siatki; grid-template-columns definiuje kolumny. W tym przykładzie zapytanie o media zmienia układ listy z dwóch kolumn na jedną. Wpływa to na układ kart na stronie. Podstawowe pojęcia dotyczące układu siatki

Współrzędne SVG kontrolują kształty wewnątrz każdej grafiki. Atrybut viewBox="0 0 48 48" symbolu określa jego prostokąt współrzędnych, a wymiary elementu use ustalają rozmiar obszaru widoku przywołanego symbolu. Te wymiary nie tworzą kolumn kart HTML ani odstępów wokół podpisów. SVG 2 wyraźnie rozróżnia układ ponownie używanych grafik od układu pudełkowego CSS. Struktura dokumentu — SVG 2

Nadawanie dostępnej nazwy łączy każdy zewnętrzny element SVG z tekstem za pomocą aria-labelledby. Nie rysuje tekstu, nie ustawia podpisu ani nie zmienia rozmiaru grafiki. Wskazówki W3C dotyczące nadawania nazw opisują ten atrybut jako odwołanie do treści używanej przy obliczaniu dostępnej nazwy. Nadawanie dostępnych nazw i opisów

To rozdzielenie daje przydatną zasadę diagnozowania problemów: jeśli karty są źle rozmieszczone, sprawdź Grid; jeśli rysunki są źle umieszczone, sprawdź współrzędne SVG; jeśli etykiety są nieprawidłowe, sprawdź odwołania używane do nadawania nazw. Dodanie x albo y do use przesuwa ponownie używane grafiki w przestrzeni SVG; nie przesuwa podpisu HTML. Ponadto wymiary use nie zastępują ogólnego mechanizmu skalowania dowolnych przywoływanych kształtów: MDN opisuje ich działanie przy odwoływaniu się do elementu SVG lub symbolu zawierającego viewBox. Element SVG use

Co zrobić, gdy nie ma widocznego podpisu?

Użyj tytułu przypisanego do danego wystąpienia, jeśli grafika wymaga nazwy, ale projekt nie zawiera odpowiedniego widocznego tekstu. Poniższy fragment zastępuje pierwszy widoczny element SVG w kompletnym przykładzie. Nadal korzysta z istniejącego symbolu tile-mark:

<svg xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 48 48" role="img"
     aria-labelledby="sample-alpha-title">
  <title id="sample-alpha-title">Sample Alpha</title>
  <use href="#tile-mark" width="48" height="48"
       aria-hidden="true" />
</svg>

Każdemu kolejnemu wystąpieniu nadaj inny identyfikator tytułu i zaktualizuj odwołanie w jego elemencie nadrzędnym. MDN opisuje title jako element SVG służący do nadawania dostępnej nazwy i zaleca umieszczanie go na pierwszym miejscu ze względu na zgodność z SVG 1.1. Tekst tytułu nie jest widocznie renderowany jako część rysunku, chociaż przeglądarki zwykle wyświetlają go jako podpowiedź. Element SVG nadający dostępną nazwę

Aby użyć krótkiej nazwy bez elementu tytułu, zamień aria-labelledby na aria-label="Sample Alpha" w zewnętrznym elemencie SVG danego wystąpienia. Nie pozostawiaj konkurujących atrybutów nazwy: W3C informuje, że aria-labelledby ma pierwszeństwo przed aria-label. Pozostawione odwołanie może więc uniemożliwić użycie nowego ciągu jako nazwy. Nadawanie dostępnych nazw i opisów

Nie próbuj przypisywać tytułu konkretnego wystąpienia przez edycję wygenerowanego klonu. SVG 2 określa instancyjne drzewo cieni jako tylko do odczytu. Obecny projekt roboczy Mapowań API dostępności SVG ogranicza również dopasowywanie odwołań ARIA do identyfikatorów w drzewach cieni use. Są to udokumentowane ograniczenia; nie stanowią dowodu na to, że wszystkie przeglądarki działają identycznie. Umieszczenie etykiety w autorskim elemencie opakowującym pozwala uniknąć zależności od wyszukiwania klonów. Struktura dokumentu — SVG 2, Mapowania API dostępności SVG

Jak sprawdzić i rozwiązywać problemy z wynikiem?

Osobno sprawdź widoczny efekt i dostępne nazwy w przeglądarce na Macu. Obejrzyj każdy zewnętrzny element SVG w narzędziach dostępności przeglądarki, a następnie sprawdź go za pomocą VoiceOver. W3C szczególnie zaleca testowanie z użyciem technologii asystujących w przypadku nazw obliczanych przez aria-labelledby. Nadawanie dostępnych nazw i opisów

Użyj tych oczekiwanych rezultatów jako krótkiej listy kontrolnej:

  1. Oba rysunki są widoczne wraz z odpowiednimi podpisami.
  2. Każdy zewnętrzny element SVG ma rolę obrazu i odpowiadającą jej nazwę.
  3. Definicja symbolu nie pojawia się jako dodatkowa, znacząca grafika.
  4. Zmniejszenie szerokości okna zmienia układ kart, a każda grafika zachowuje swoją etykietę.
  5. Zmiana wyłącznie drugiego podpisu zmienia tylko obliczoną nazwę drugiej grafiki.

Jeśli obie grafiki otrzymują tę samą nazwę, najpierw porównaj ich wartości aria-labelledby. Następnie sprawdź, czy każdy wskazany identyfikator odnosi się do właściwego tekstu. Nie zakładaj, że powiązanie wynika z bliskości wizualnej: ten atrybut jawnie wskazuje element za pomocą identyfikatora. Nadawanie dostępnych nazw i opisów

Jeśli cały rysunek jest ogłaszany jako jeden obraz, choć potrzebujesz kilku niezależnych obrazów, sprawdź położenie role="img". Jedna rola obrazu obejmująca całą kolekcję oznacza, że technologie asystujące mają traktować ją jako jeden element. Dla osobnych prostych grafik stosuj osobne opakowania o roli obrazu. Rola ARIA: img

Jeśli osadzasz plik SVG za pomocą elementu HTML img, dla każdego wystąpienia użyj atrybutu alt tego elementu. WHATWG definiuje alt jako równoważną treść zastępczą dla obrazu. Wbudowane SVG korzysta z innych mechanizmów nadawania nazw i nie obsługuje alt jako atrybutu tekstu alternatywnego. Standard HTML: element img, Wprowadzenie do SVG w HTML

W tym zadaniu dotyczącym układu pozostaw jedną wspólną definicję rysunku i podejmij osobną decyzję o nazwie dla każdego wystąpienia. Wybierz element opakowujący zgodnie z tym, co powinien napotkać czytelnik, połącz go z odpowiednim tekstem i sprawdź dostępną nazwę niezależnie od układu wizualnego.

Źródła