VisuallyHidden

Паттерны

Подпись элемента управления с одной иконкой

Когда использовать:

• элемент управления визуально состоит только из иконки, но ему всё равно нужно доступное имя

Заметки о композиции:

• делайте скрытую подпись краткой
• предпочитайте одну ясную скрытую фразу

Компромиссы:

• сохраняет компактный внешний вид
• видимая ясность по-прежнему зависит от узнаваемости иконки

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 (
    <IconButton type='button' variant='secondary' appearance='ghost' onClick={() => setUnread(0)} style={{ position: 'relative' }}>
      <Icon><BellIcon /></Icon>
      <VisuallyHidden asChild>
        <span>Notifications, {unread} unread</span>

Скрытое ARIA-описание

Когда использовать:

• полю нужен дополнительный контекст только для вспомогательных технологий

Заметки о композиции:

• задайте скрытому узлу id
• сошлитесь на него из элемента управления через aria-describedby

Компромиссы:

• гибко и переиспользуемо
• легко забыть обновить скрытый текст

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<HTMLFormElement>) => {
    event.preventDefault();
    setBudget(String(new FormData(event.currentTarget).get('budget')));
  };

  return (

Скрытый текст статуса

Когда использовать:

• визуальному индикатору загрузки или статуса нужен текст только для вспомогательных технологий

Заметки о композиции:

• держите текст синхронизированным с реальным состоянием
• не дублируйте вводящие в заблуждение устаревшие сообщения

Компромиссы:

• улучшает ясность для невизуального восприятия
• состояние легко рассинхронизировать, если логика родителя небрежна

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<string[]>([]);
  const [announcement, setAnnouncement] = useState('');

  const add = (product: string) => {
    const next = [...cart, product];

Сравнение

Быстрое правило выбора

Используйте VisuallyHidden, когда содержимое должно оставаться доступным для вспомогательных технологий, но не отображаться визуально. Используйте обычный текст, когда информация должна быть видна всем.

VisuallyHidden или видимый вспомогательный текст

• Используйте VisuallyHidden для содержимого, предназначенного только для доступности.
• Используйте видимый вспомогательный текст, когда подсказка полезна всем пользователям.

VisuallyHidden или aria-label

• Используйте VisuallyHidden, когда нужно реальное содержимое в DOM, на которое можно сослаться или которое можно компоновать.
• Используйте aria-label для коротких прямых подписей, когда отдельный узел с содержимым не нужен.

Выбирайте этот компонент, когда

• содержимое должно оставаться доступным, но не видимым
• полезен скрытый узел с описанием или подписью

Не выбирайте этот компонент, когда

• информация должна быть видна в обычном интерфейсе
• скрытым текстом пытаются обойти исправление видимого UX

Решение проблем

Скрытый текст звучит неверно или устарел

Симптом

Пользователи вспомогательных технологий получают текст, который больше не соответствует видимому интерфейсу.

Вероятная причина

Скрытый текст не обновили вместе с видимым состоянием.

Как проверить

• сравните скрытую строку с текущими переходами видимого состояния

Исправление

Формируйте скрытое содержимое из того же состояния, что и видимый интерфейс.

Интерфейс остаётся неясным даже со скрытым текстом

Симптом

Доступность немного улучшилась, но видимый интерфейс по-прежнему слабый или двусмысленный.

Вероятная причина

VisuallyHidden используется, чтобы компенсировать плохие видимые подписи.

Как проверить

• оцените интерфейс без содержимого, предназначенного только для вспомогательных технологий

Исправление

Сначала улучшите видимые подписи, а скрытый текст оставьте только там, где он действительно полезен.

Скрытое содержимое неожиданно появляется снова

Симптом

Содержимое, которое должно быть скрыто, становится видимым в некоторых раскладках или после переопределений.

Вероятная причина

CSS визуального скрытия был переопределён.

Как проверить

• проверьте вычисленные стили на правила обрезки и позиционирования

Исправление

Сохраняйте стандартный CSS-контракт визуального скрытия и не переопределяйте его без необходимости.