# VisuallyHidden ## Кратко `VisuallyHidden` оставляет содержимое доступным для вспомогательных технологий, убирая его из визуальной раскладки. Поддерживает нативную обёртку или композицию через `asChild` с помощью `Slot`. ## Импорт ```tsx import { VisuallyHidden, type VisuallyHiddenProps } from '@vega-ui/react'; ``` ## Экспортируемые типы - `VisuallyHiddenProps` ## Базовое использование ```tsx import { Heading, Link, Text, VisuallyHidden } from '@vega-ui/react'; const plans = [ { name: 'Starter', price: '$0', slug: 'starter' }, { name: 'Team', price: '$12', slug: 'team' }, { name: 'Enterprise', price: 'Custom', slug: 'enterprise' }, ]; export default function BasicUsage() { return ( ); } ``` ## Варианты - Рендер: обёртка по умолчанию или `asChild` - Применение: скрытая подпись, описание или текст статуса ## Пограничные случаи - Скрытый текст должен оставаться синхронизированным с видимым состоянием интерфейса. - `VisuallyHidden` по умолчанию не заменяет видимые подписи. - `asChild` сохраняет стили скрытия, но меняет нижележащий элемент. ## Частые ошибки - Скрытый текст устаревает, когда меняется видимое состояние. - Скрытый текст маскирует плохие видимые подписи. - Скрыто содержимое, которое на самом деле должно быть видно большинству пользователей. ## Примеры ### Базовый #### Базовый: уникальные имена для повторяющихся ссылок Три ссылки «Learn more» в списке ссылок звучат одинаково. Скрытый текст дополняет каждое имя («Learn more about the Team plan»), не меняя раскладку. ```tsx import { Heading, Link, Text, VisuallyHidden } from '@vega-ui/react'; const plans = [ { name: 'Starter', price: '$0', slug: 'starter' }, { name: 'Team', price: '$12', slug: 'team' }, { name: 'Enterprise', price: 'Custom', slug: 'enterprise' }, ]; export default function BasicUsage() { return ( ); } ``` #### Базовый: кнопка-иконка с текстовым именем Скрытый текст внутри кнопки становится её доступным именем и может содержать данные, которые бейдж показывает лишь числом. Сам бейдж помечен `aria-hidden`, чтобы число не читалось дважды. `asChild` рендерит ``, потому что `
` по умолчанию недопустим внутри кнопки. ```tsx import { Icon, IconButton, VisuallyHidden } from '@vega-ui/react'; import { BellIcon } from '@vega-ui/icons'; import { useState } from 'react'; export default function IconOnlyControlLabel() { const [unread, setUnread] = useState(4); return ( setUnread(0)} style={{ position: 'relative' }}> Notifications, {unread} unread {unread > 0 && ( )} ); } ``` ### Контролируемый/с состоянием #### Контролируемый/с состоянием: живое объявление для визуального счётчика Счётчик корзины меняется беззвучно для скринридера. Скрытая область `role='status'` получает полное предложение при каждом изменении, а визуальный счётчик остаётся `aria-hidden`. ```tsx import { Button, Icon, VisuallyHidden } from '@vega-ui/react'; import { ShoppingCartIcon } from '@vega-ui/icons'; import { useState } from 'react'; const products = ['Linen shirt', 'Canvas tote', 'Wool socks']; export default function HiddenStatusText() { const [cart, setCart] = useState([]); const [announcement, setAnnouncement] = useState(''); const add = (product: string) => { const next = [...cart, product]; setCart(next); setAnnouncement(`${product} added. Cart has ${next.length} items.`); }; return (
{products.map((product) => ( ))}

{announcement}
); } ``` ### Форма/интеграция #### Форма/интеграция: скрытое описание визуального украшения Префикс `$` только визуальный. Скрытое описание, связанное через `aria-describedby`, сообщает скринридеру валюту; значение читается через `FormData` при отправке. `VisuallyHidden` не принимает `id`, поэтому id задаётся на `span` через `asChild`. ```tsx import { Button, Label, TextField, TextFieldInput, VisuallyHidden } from '@vega-ui/react'; import { FormEvent, useState } from 'react'; export default function HiddenHelperDescription() { const [budget, setBudget] = useState(''); const handleSubmit = (event: FormEvent) => { event.preventDefault(); setBudget(String(new FormData(event.currentTarget).get('budget'))); }; return (
Amount in US dollars {budget === '' ? '' : `Budget set to $${budget}`}
); } ``` ### Раскладка/оверлей #### Раскладка/оверлей: скрытый заголовок диалога У лайтбокса нет видимого заголовка, но диалогу всё равно нужно имя. Скрытый `

` подключён через `aria-labelledby`, поэтому диалог объявляется как «Floor plan, apartment 4B». ```tsx import type { CSSProperties } from 'react'; import { Button, Dialog, DialogClose, DialogContent, DialogTrigger, Icon, IconButton, VisuallyHidden, } from '@vega-ui/react'; import { ImageIcon, XIcon } from '@vega-ui/icons'; export default function HiddenDialogCue() { return (

Floor plan, apartment 4B
); } ``` ### Ошибка #### Ошибка: озвучиваемый префикс сообщения об ошибке Ошибка показана цветом и иконкой. Скрытый префикс «Error:» даёт тот же сигнал пользователям скринридера, когда они попадают на сообщение через `aria-describedby`. ```tsx import { Button, HelperText, Icon, Label, TextField, TextFieldInput, VisuallyHidden } from '@vega-ui/react'; import { CircleAlertIcon } from '@vega-ui/icons'; import { FormEvent, useState } from 'react'; export default function HiddenValidationCue() { const [error, setError] = useState(''); const [saved, setSaved] = useState(''); const handleSubmit = (event: FormEvent) => { event.preventDefault(); const domain = String(new FormData(event.currentTarget).get('domain')); if (!domain.includes('.')) { setError('Add a top-level domain, for example acme.com'); setSaved(''); return; } setError(''); setSaved(domain); }; return (
{error !== '' && ( Error: {error} )} {saved === '' ? '' : `Connected ${saved}`}
); } ``` ### Отключённый #### Отключённый: почему вариант недоступен Распроданные размеры отключены и зачёркнуты. Зачёркивание только визуальное, поэтому скрытый текст добавляет «, sold out» к имени кнопки — скринридер читает его и в режиме просмотра. ```tsx import { Button, VisuallyHidden } from '@vega-ui/react'; import { useState } from 'react'; const sizes = [ { label: 'S', inStock: true }, { label: 'M', inStock: true }, { label: 'L', inStock: false }, { label: 'XL', inStock: false }, ]; export default function HiddenDisabledExplanation() { const [selected, setSelected] = useState('M'); return (
{sizes.map((size) => ( ))}

Selected size: {selected}

); } ``` ### Пограничный случай #### Пограничный случай: текстовая альтернатива рейтинга из символов Символы звёзд читаются по одному как «чёрная звезда». Они скрыты через `aria-hidden`, а скрытый `span` внутри абзаца читается как «Rated 3 out of 5». `asChild` оставляет `` внутри `

`, где `

` недопустим. ```tsx import { Text, VisuallyHidden } from '@vega-ui/react'; const reviews = [ { author: 'Maria K.', rating: 5, text: 'Arrived in two days, fits perfectly.' }, { author: 'Tom B.', rating: 3, text: 'Good fabric, but the sleeves run long.' }, ]; export default function SlottedHiddenElement() { return (
    {reviews.map((review) => (
  • {review.author}

    Rated {review.rating} out of 5

    {review.text}
    • ))}
); } ``` #### Пограничный случай: пустой на вид заголовок таблицы У колонки действий часто нет видимого заголовка, но пустой `` оставляет ячейки без контекста. Скрытый заголовок «Actions» решает это, а колонка визуально остаётся пустой. ```tsx import { Icon, IconButton, VisuallyHidden } from '@vega-ui/react'; import { PencilIcon } from '@vega-ui/icons'; import { useState } from 'react'; const members = [ { name: 'Jane Cooper', role: 'Owner' }, { name: 'Wade Warren', role: 'Editor' }, { name: 'Esther Howard', role: 'Viewer' }, ]; export default function HiddenTableHeader() { const [editing, setEditing] = useState(''); return (
{members.map((member) => ( ))}
Name Role Actions
{member.name} {member.role} setEditing(member.name)} >

{editing === '' ? '' : `Editing ${editing}`}

); } ``` ## Анатомия ### Обзор `VisuallyHidden` — примитив из одной части, который применяет к своему содержимому стандартный CSS-паттерн визуального скрытия. ### Обязательные части #### `VisuallyHidden` Обязательна. Отвечает за рендер, при котором содержимое скрыто визуально, но остаётся доступным. ### Необязательные части Экспортируемых дочерних частей нет. ### Порядок композиции 1. `VisuallyHidden` 2. скрытое содержимое ### Допустимые паттерны композиции ```tsx import { Heading, Link, Text, VisuallyHidden } from '@vega-ui/react'; const plans = [ { name: 'Starter', price: '$0', slug: 'starter' }, { name: 'Team', price: '$12', slug: 'team' }, { name: 'Enterprise', price: 'Custom', slug: 'enterprise' }, ]; export default function BasicUsage() { return (
    {plans.map((plan) => (
  • {plan.name} {plan.price} Learn more about the {plan.name} plan
    • ))}
); } ``` ### Недопустимые паттерны композиции #### Скрытый текст по умолчанию вместо видимой подписи Интерфейсом становится труднее пользоваться зрячим пользователям. #### Скрытое содержимое не синхронизировано с видимым состоянием Пользователи вспомогательных технологий получают устаревшую информацию.