Akordeon: Zasady stopniowego ujawniania i przykłady

Akordeon to zgrupowany zestaw oznaczonych etykietami kontrolek ujawniania, który pozwala czytelnikowi odkrywać lub zwijać treści pomocnicze w miejscu. Używaj go do opcjonalnych szczegółów referencyjnych, a nie do głównej odpowiedzi strony.

Ta renderowana para demonstruje stopniowe ujawnianie: etykiety pozostają łatwe do skanowania, jeden panel jest otwarty, a obie odpowiedzi są obecne w HTML-u strony, niezależnie od tego, czy odwiedzający wchodzi z nimi w interakcję.

Dlaczego ten element jest ważny

Stopniowe ujawnianie oznacza pokazywanie informacji potrzebnych do bieżącej decyzji, podczas gdy głębsze lub rzadziej potrzebne szczegóły pozostają dostępne na żądanie. Pomaga, gdy strona służy czytelnikom o różnym poziomie wiedzy. Powracający klient może przejść wzrokiem obok notatek implementacyjnych; nowy użytkownik może je otworzyć. Kontrolka zmniejsza gęstość wizualną bez usuwania treści i bez zmuszania każdego czytelnika do przechodzenia przez każdy wyjątek.

Ta sama wygoda może stać się ukrywaniem. Czytelnik, który szuka bezpośredniej odpowiedzi, trafia na stronę i widzi osiem zamkniętych etykiet — musi zgadnąć, który panel ją zawiera i wykonać dodatkową czynność. Na urządzeniach mobilnych wielokrotne otwieranie i zamykanie przesuwa również treść w obrębie okna widoku. Akordeon zasługuje więc na swoje miejsce tylko wtedy, gdy większość czytelników może wykonać swoje główne zadanie bez otwierania każdego panelu.

Ekstrahowalność maszynowa dodaje jeszcze bardziej restrykcyjny test. Ekstrahowalność to zdolność wyszukiwarek, systemów AI odpowiadających na pytania, parserów i narzędzi asystujących do odbierania tekstu i zachowania jego relacji z etykietą. Każda odpowiedź musi być obecna w początkowym, wyrenderowanym po stronie serwera modelu DOM (Document Object Model) — strukturalnej reprezentacji strony w przeglądarce. CSS może wizualnie zwinąć obecny panel; JavaScript nie może pobierać ani tworzyć odpowiedzi dopiero po kliknięciu. Robot indeksujący może nigdy nie kliknąć, nie wykonać kodu klienckiego ani nie czekać na żądanie wtórne.

Postępuj zgodnie z zasadami pisania elementów przed użyciem tego wzorca. Jeśli cel treści pasuje do bardziej szczegółowego, typowanego elementu, ten element ma pierwszeństwo. Akordeon może zawierać dozwolone treści pomocnicze, ale nie może zmieniać nazwy ani spłaszczać ostrzeżenia, porównania, definicji czy sekwencji kroków tylko po to, aby strona wydawała się krótsza.

Kiedy go używać

Używaj akordeonu, gdy spełnione są wszystkie cztery warunki:

1. Czytelnik jest w stanie przewidzieć treść panelu na podstawie jego etykiety.
2. Treść jest użyteczna dla podzbioru czytelników, a nie konieczna dla wszystkich.
3. Cała treść paneli jest dostarczana w początkowym HTML i pozostaje osiągalna bez użycia urządzenia wskazującego.
4. Zwijanie znacząco poprawia skanowanie na przewidywanym oknie widoku.

Dobrymi kandydatami są: opcjonalne szczegóły zgodności, nietypowe gałęzie błędów, definicje pomocnicze, drugorzędne klauzule polityki, wyjątki wysyłkowe oraz zgrupowane odpowiedzi referencyjne. Akordeon może też działać w przypadku dużego zbioru FAQ, gdy każde pytanie pozostaje widoczne, a każda odpowiedź jest samodzielna.

Przykłady bliskie, ale nietrafione, pokazują najczęstsze niewłaściwe użycie:

• Krótka strona z dwoma zwięzłymi sekcjami: widoczne nagłówki i akapity są szybsze do skanowania niż dwie kontrolki.
• Długi artykuł, który ma wyglądać na krótszy: zwinięcie dziesięciu obszernych sekcji zmniejsza postrzeganą wysokość, ale zwiększa interakcję i ukrywa zakres strony.
• Podstawowe informacje o produkcie: cena, dostępność, ograniczenia materiałowe, warunki anulowania i kluczowe specyfikacje wpływają na decyzję i nie mogą zależeć od rozwinięcia.
• Sekwencyjna procedura: kroki wymagają kolejności i kontekstu. Zamknięty panel może spowodować, że czytelnik pominie warunek wstępny lub wykona kroki w złej kolejności.
• Porównanie: czytelnicy potrzebują jednoczesnej widoczności tych samych kryteriów. Oddzielne panele wymuszają porównywanie z pamięci.
• Ostrzeżenie bezpieczeństwa lub zastrzeżenie prawne: konsekwencja jego pominięcia jest większa niż wizualna korzyść z jego ukrycia.
• Substytut nawigacji: akordeon nie jest spisem treści. Ujawnia treść w tym samym miejscu, zamiast przenosić do stabilnych sekcji strony.

W razie wątpliwości publikuj treść widocznie. Dodatkowe przewijanie jest zwykle do nadrobienia; pominięta odpowiedź, nieujawnione ograniczenie lub niedostępny węzeł DOM — nie.

Gdzie go umieścić

Umieść akordeon po tym, jak strona dostarczy swoją bezpośrednią odpowiedź i wystarczająco dużo widocznego wyjaśnienia, aby czytelnik zrozumiał, co zawiera grupa. Wprowadź go nagłówkiem H2 i jednym zdaniem określającym zakres. Grupa działa wtedy jako dodatkowa warstwa referencyjna w obrębie tej sekcji.

Zasady dokładnego umiejscowienia:

• Umieść go po widocznym wyjaśnieniu, które uzupełnia, nigdy między twierdzeniem a dowodem potwierdzającym to twierdzenie.
• Trzymaj go w obrębie sekcji nadrzędnej, której temat opisuje każdy element. Jeśli etykiety mają sens tylko przy brakującym nagłówku, grupa jest źle umieszczona.
• Umieść akordeon ze szczegółami produktu po podstawowej wartości, kontekście cenowym i warunkach zakupu; umieść gałęzie rozwiązywania problemów po wspólnej diagnozie i najbezpieczniejszym pierwszym sprawdzeniu.
• Umieść zamykający akordeon FAQ po głównym podsumowaniu, a przed końcowym następnym działaniem, pod warunkiem że odpowiada na pozostałe, a nie powtarzające się pytania.
• Nadaj grupie stabilną kotwicę sekcji, jeśli czytelnicy mogą do niej linkować. Linki do poszczególnych paneli są opcjonalne, ale jeśli są dostarczone, muszą otwierać i ustawiać fokus na właściwym elemencie.

Akordeon nie może znajdować się bezpośrednio obok zakładek, drugiego akordeonu ani gęstej tabeli porównawczej. Sąsiadujące wzorce interakcji zmuszają czytelników do wyboru mechanizmu, zanim będą mogli wybrać treść. Nie może przerywać uporządkowanych kroków, oddzielać ostrzeżenia od jego konsekwencji ani znajdować się między ceną produktu a warunkami nią rządzącymi. Nie umieszczaj banera promocyjnego wewnątrz grupy ani bezpośrednio po każdym panelu; promocja konkuruje z zadaniem referencyjnym i sprawia, że rozwinięcie wydaje się pułapką sprzedażową.

Anatomia

Oznaczona anatomia składa się z siedmiu części:

1. Nagłówek grupy: nazywa wspólny temat w otaczającej hierarchii dokumentu.
2. Etykieta elementu: przewiduje konkretną treść bez nieprecyzyjnych etykiet, takich jak „Dowiedz się więcej”.
3. Kontrolka ujawniania: natywny summary lub button, który przyjmuje fokus klawiatury i przełącza jeden panel.
4. Wskaźnik stanu: komunikuje wizualnie stan otwarcia lub zamknięcia, podczas gdy programowy stan jest ujawniany przez natywną semantykę lub aria-expanded.
5. Panel: zawiera odpowiedź lub szczegół referencyjny i pozostaje w początkowym DOM.
6. Relacja kontrolki: natywna semantyka <details>/<summary> lub aria-controls z pasującymi ID-ami łączy każdą kontrolkę z dokładnie jednym panelem.
7. Granica elementu: odstępy, obramowanie i grupowanie w DOM zapobiegają wrażeniu, że jedna etykieta kontroluje sąsiednią odpowiedź.

Widoczny strzałka/trójkąt ma charakter dekoracyjny. Ukryj go przed technologiami asystującymi, ponieważ stan rozwinięcia już dostarcza tego znaczenia. Sama rotacja nie może komunikować stanu; musi to robić semantyka kontrolki.

Przykłady projektowe

Każdy wariant używa tych samych pól i reguły obecności w DOM. Wybierz wariant na podstawie zadania czytelnika, a nie dekoracji.

Standardowa grupa z jednym otwartym elementem

Otwarcie jednego elementu zamyka poprzednio otwarty. Używaj, gdy panele są alternatywami, a czytelnicy normalnie potrzebują jednego naraz, na przykład wzajemnie wykluczających się symptomów rozwiązywania problemów.

Grupa referencyjna z wieloma otwartymi elementami

Czytelnicy mogą utrzymywać kilka otwartych paneli. Używaj, gdy mogą porównywać lub łączyć dodatkowe szczegóły, takie jak obsługiwane typy plików i uprawnienia konta. Jeśli jednoczesne porównanie jest głównym zadaniem, użyj widocznej tabeli.

Orientacja z domyślnie otwartym elementem

Otwórz pierwszy lub najczęściej wybierany element przy początkowym ładowaniu, gdy demonstruje on wzorzec treści i zapewnia użyteczną orientację. Nigdy nie otwieraj więcej niż jednego elementu tylko po to, by wypełnić przestrzeń.

Kompaktowy wariant FAQ

Używaj etykiet w formie pytań i zwięzłych samodzielnych odpowiedzi. Sama interakcja nie uzasadnia danych strukturalnych; schemat zależy od typu treści i dokładnych widocznych rekordów.

Stan przeciążenia długą treścią

Panel z więcej niż dwoma krótkimi akapitami sygnalizuje, że materiał może zasługiwać na widoczną sekcję. Wariant przeciążenia istnieje do testowania zawijania, linków, list, fokusu i responsywnego przepływu, a nie jako normalny cel redakcyjny.

Parametry

Kontrakt oddziela zachowanie grupy od treści elementu, aby każda platforma mogła zachować te same etykiety, stany i relacje.

Pierwszy nadrzędny nagłówek mapuje się na heading. Pierwszy nagłówek każdego zagnieżdżonego elementu mapuje się na label, a wszystko po nim na content tego elementu. Jest to jawne mapowanie zagnieżdżonych elementów, zgodne z podstawowymi zasadami pierwszeństwa i treści. open=true ustawia tylko początkową prezentację; nie zmienia ważności treści. Gdy linkable=true, nawigacja do fragmentu elementu musi go rozwinąć, przewidywalnie przenieść fokus i pozostawić nagłówek widocznym poniżej ewentualnego lepkiego nagłówka.

Składnia i przykłady kodu

Wszystkie trzy notacje reprezentują jedną kanoniczną grupę. Mogą renderować różne klasy opakowujące, ale muszą zachować treść w początkowym HTML, kolejność źródłową, dostępne nazwy i stan.

Przenośna dyrektywa Markdown

:::accordion{mode=multiple linkable=true}
## Szczegóły eksportu

::item{id="included-fields" open=true}
### Które pola są uwzględnione?

Eksport zawiera pola aktualnie dostępne na twoim koncie i w zakresie raportu.
::

::item{id="filter-behavior"}
### Czy filtry wpływają na eksport?

Tak. Potwierdź aktywny zakres dat, rynek i filtry statusu przed utworzeniem pliku.
::
:::

Skrócony kod Hugo

{{< accordion heading="Szczegóły eksportu" mode="multiple" linkable="true" >}}
{{< accordion-item id="included-fields" label="Które pola są uwzględnione?" open="true" >}}
Eksport zawiera pola aktualnie dostępne na twoim koncie i w zakresie raportu.
{{< /accordion-item >}}
{{< accordion-item id="filter-behavior" label="Czy filtry wpływają na eksport?" >}}
Tak. Potwierdź aktywny zakres dat, rynek i filtry statusu przed utworzeniem pliku.
{{< /accordion-item >}}
{{< /accordion >}}

Jest to specyfikacja adaptera Hugo. Repozytorium nie spełnia jej przez dodawanie klas do dowolnych nagłówków; potrzebuje renderera, który produkuje natywny HTML ujawniania lub równoważną relację przycisk-panel.

Blok WordPress

<!-- wp:amicited/accordion {"heading":"Szczegóły eksportu","mode":"multiple","linkable":true} -->
<!-- wp:amicited/accordion-item {"id":"included-fields","label":"Które pola są uwzględnione?","open":true} -->
<p>Eksport zawiera pola aktualnie dostępne na twoim koncie i w zakresie raportu.</p>
<!-- /wp:amicited/accordion-item -->
<!-- wp:amicited/accordion-item {"id":"filter-behavior","label":"Czy filtry wpływają na eksport?"} -->
<p>Tak. Potwierdź aktywny zakres dat, rynek i filtry statusu przed utworzeniem pliku.</p>
<!-- /wp:amicited/accordion-item -->
<!-- /wp:amicited/accordion -->

Zarejestrowany blok WordPress przechowuje kanoniczne pola, zamiast polegać na wizualnej grupie niepowiązanych bloków Details. Jego renderowanie serwerowe musi emitować każdą odpowiedź przed interakcją.

Przykłady

Dobry przykład

Szczegóły usunięcia konta pojawia się po widocznym wyjaśnieniu, co robi usunięcie, oraz widocznym ostrzeżeniu, że jest nieodwracalne. Jego trzy etykiety to: „Co się dzieje z zaplanowanymi eksportami?”, „Jak długo pozostaje dostępne żądane archiwum?” oraz „Czy inny administrator może anulować żądanie?” Każdy panel zawiera jedną opcjonalną gałąź, wszystkie odpowiedzi są w HTML, a fokus klawiatury jest widoczny.

Działa to, ponieważ główna konsekwencja i wymagane działanie pozostają widoczne. Akordeon zawiera pytania drugorzędne, które dotyczą różnych czytelników, a każda etykieta pozwala czytelnikowi przewidzieć, czy otwarcie jej jest opłacalne.

Zły przykład

Wybierz swój plan zawiera zamknięte panele oznaczone „Starter”, „Zespołowy” i „Enterprise”. Cena, limity użycia, okres umowy, warunki anulowania i dostępność znajdują się wewnątrz paneli. Tylko jeden plan może być otwarty naraz.

To jest błędne, ponieważ kryteria zakupu wymagają widoczności obok siebie. Czytelnik musi wielokrotnie otwierać panele i zapamiętywać fakty, podczas gdy nieinteraktywny ekstraktor może nie wychwycić cen ładowanych przez klienta. Zastąp to widoczną tabelą cen lub specyfikacji, a ujawnianie zarezerwuj dla opcjonalnych szczegółów, takich jak formaty faktur lub nietypowe zasady kwalifikowalności.

Znaczniki schematu i dostępność

Akordeon nie ma dedykowanego typu Schema.org. Sama interakcja nie dostarcza żadnych danych strukturalnych. Jeśli jego rekordy są rzeczywistymi pytaniami i odpowiedziami, kontrakt treści FAQ może dostarczać FAQPage; jeśli grupa zawiera szczegóły produktu, polityki lub notatki dotyczące rozwiązywania problemów, używaj tylko schematu uzasadnionego przez stronę i treść. Widoczny tekst i wszelkie reprezentacje strukturalne muszą być zgodne.

Preferuj natywne <details> i <summary> dla prostych mechanizmów ujawniania, ponieważ przeglądarka dostarcza obsługę klawiatury i semantykę stanu. Tam, gdzie design lub zachowanie pojedynczego otwarcia wymaga niestandardowej implementacji, każda kontrolka musi być button, ujawniać aria-expanded="true" lub "false", odnosić się do swojego panelu za pomocą aria-controls i mieć unikalne ID, do którego panel może się odnieść za pomocą aria-labelledby. Nie umieszczaj kontrolki na div z obsługą kliknięcia.

Enter lub Spacja muszą obsługiwać kontrolkę z fokusem. Tab przemieszcza się przez kontrolki i interaktywną zawartość w otwartym panelu; fokus nie może wchodzić do zamkniętej treści. Otwarcie lub zamknięcie panelu normalnie pozostawia fokus na jego kontrolce. Nawigacja strzałkami między nagłówkami jest opcjonalna, ale jeśli jest zaimplementowana, nie może zastępować normalnego zachowania Tab.

Utrzymuj wszystkie etykiety w drzewie dostępności i wszystkie odpowiedzi w źródłowym HTML. Wizualnie zamknięty panel może używać natywnego zachowania ujawniania lub obsługiwanego stanu ukrytego, ale jego zawartość musi stać się dostępna po rozwinięciu bez drugiego pobierania. Stan zwinięty nie może powodować duplikowania treści przez osobne kopie na komputer i urządzenia mobilne. Testuj przy 200% powiększeniu, z długimi etykietami, tylko klawiaturą, ograniczonym ruchem i czytnikiem ekranu. Animuj wysokość lub obrót ikony tylko wtedy, gdy ruch może być wyłączony, a treść nie jest opóźniana.

Zasady pisania

Etykieta ponosi koszt interakcji, więc musi składać precyzyjną obietnicę. Pisz 3–14 słów i zwykle nie więcej niż 120 znaków. Używaj bezpośredniego pytania w przypadku treści FAQ i opisowej frazy rzeczownikowej w przypadku treści referencyjnych. Unikaj „Więcej”, „Szczegóły”, „Przeczytaj to” oraz etykiet różniących się tylko numerem.

Używaj 3–8 elementów na grupę. Każdy panel powinien normalnie zawierać 20–120 słów i nie więcej niż 250. Dwa krótkie panele są czytelniejsze jako otwarta proza; dziewięć lub więcej wymaga grupowania, widocznej nawigacji lub konsolidacji redakcyjnej. Utrzymuj etykiety gramatycznie równoległe i układaj elementy według zadania czytelnika, przewidywanej częstotliwości lub rzeczywistej sekwencji kategorii — nie alfabetycznie, chyba że wyszukiwanie jest rzeczywiście alfabetyczne.

Ton panelu jest bezpośredni, samodzielny i rzeczowy. Podaj odpowiedź w pierwszym zdaniu, ponieważ czytelnik zapłacił już koszt interakcji. Zdefiniuj każdy niezbędny termin w panelu lub w widocznym tekście bezpośrednio przed grupą. Nie zaczynaj od pustych fraz, takich jak „Należy wziąć pod uwagę kilka kwestii.”

Nigdy nie umieszczaj wyłącznie w akordeonie:

• bezpośredniej odpowiedzi strony lub unikalnej propozycji wartości;
• ostrzeżeń bezpieczeństwa, przeciwwskazań, obowiązków prawnych lub nieodwracalnych konsekwencji;
• ceny, dostępności, materialnych ograniczeń produktu lub wymaganych warunków zakupu;
• uporządkowanych kroków, warunków wstępnych lub sprawdzenia ukończenia;
• dowodów niezbędnych do poparcia otaczającego twierdzenia;
• podstawowego porównania lub macierzy decyzyjnej;
• formularzy, kontrolek kasy, zgód lub głównego wezwania do działania strony;
• innego akordeonu, zakładek lub karuzeli.

Zwięzła lista, mała tabela, link w tekście lub obraz pomocniczy są dopuszczalne, gdy w całości należą do jednego opcjonalnego elementu i pozostają użyteczne na urządzeniach mobilnych. Jeśli panel potrzebuje własnego spisu treści lub więcej niż jednego poziomu nagłówka, awansuj go do widocznej sekcji lub osobnej strony.

Typy wpisów, które go używają

Tablica postTypes w metadanych jest źródłem tej matrycy użycia. Umieszczenie oznacza, że element jest dostępny pod określonym warunkiem, a nie obowiązkowy na każdej stronie tego typu.

Lista kontrolna QA

• Widoczna bezpośrednia odpowiedź pojawia się przed akordeonem.
• Każdy element to opcjonalna treść referencyjna, a nie informacja potrzebna wszystkim czytelnikom.
• Grupa ma 3–8 elementów z precyzyjnymi, równoległymi etykietami.
• Pełny tekst każdego panelu jest obecny w początkowym HTML-u wyrenderowanym po stronie serwera.
• Żadna odpowiedź nie zależy od żądania sieciowego wywołanego kliknięciem ani wstawienia wyłącznie po stronie klienta.
• Natywne details/summary lub prawdziwe przyciski zapewniają poprawne zachowanie klawiatury.
• Niestandardowe kontrolki ujawniają aria-expanded, aria-controls, unikalne ID-y i powiązaną etykietę panelu.
• Fokus jest widoczny, pozostaje przewidywalny po przełączeniu i nie może wejść do zamkniętego panelu.
• Długie etykiety zawijają się bez przycinania, nakładania ani ukrywania wskaźnika stanu.
• Układ działa przy 200% powiększeniu i na wąskim oknie widoku bez poziomego przewijania.
• Ruch respektuje preferencje ograniczonego ruchu i nigdy nie opóźnia dostępu do treści.
• Linki do poszczególnych fragmentów, jeśli są obsługiwane, otwierają i ujawniają właściwy panel.
• Dane strukturalne opierają się na znaczeniu treści, a nie na wyglądzie akordeonu.
• Rekordy FAQPage, jeśli są emitowane, dokładnie odpowiadają widocznemu tekstowi pytania i odpowiedzi.
• Żaden zagnieżdżony akordeon, sąsiedni zestaw zakładek, powielona kopia mobilna ani główne CTA nie są obecne.
• Strona wciąż komunikuje swoją główną odpowiedź, gdy każdy panel jest zamknięty.

Często zadawane pytania

Metadane przechowują kanoniczne rekordy FAQ dla tej strony. Ich odpowiedzi wzmacniają granicę implementacji: treść może być wizualnie zwinięta, ale pozostaje obecna, dostępna i drugorzędna względem widocznej odpowiedzi.