DetailedElementInfo (Подробная информация об элементе)

Мощное дополнение для NVDA, предоставляющее подробную информацию о доступности HTML-элементов на веб-страницах.

Обзор

Detailed Element Info — это вспомогательное дополнение для NVDA, которое позволяет инспектировать HTML-элементы и просматривать их атрибуты доступности, ARIA-роли и семантическую информацию. Это особенно полезно для веб-разработчиков, аудиторов доступности и пользователей NVDA, которые хотят понять, как экранные ридеры воспринимают веб-контент.

Возможности

• Отображение ARIA-ролей: Просмотр вычисленной ARIA-роли любого HTML-элемента
• Показ доступных имён: Просмотр доступного имени и его источника (aria-label, alt-текст, содержимое и т. д.)
• Обнаружение семантических несоответствий: Выявление случаев, когда явные ARIA-роли конфликтуют с родной семантикой HTML
• Инспектирование атрибутов: Просмотр всех атрибутов IA2 и свойств ARIA
• Показ DOM-пути: Просмотр краткого DOM-пути для элемента в фокусе
• Навигация по родительским элементам: Перемещение по родительским элементам для понимания структуры документа
• Отслеживание состояний: Просмотр состояний элементов (развёрнуто, отмечено, выбрано и т. д.) в виде ARIA-атрибутов
• Определение источника: Понимание того, откуда берутся доступные имена (aria-label, содержимое, alt, title и т. д.)
• Уверенность в источнике имени: Просмотр того, насколько дополнение уверено в источнике доступного имени (определённо, предположительно, неизвестно)
• Несколько представлений ролей: Сравнение явной ARIA-роли, родной HTML-роли, роли NVDA и итоговой вычисленной роли
• Роль MSAA и уровень заголовка: Просмотр сырой роли MSAA и, для заголовков, уровня заголовка
• Производные атрибуты состояний: Просмотр ARIA-подобных атрибутов, полученных из состояний NVDA (развёрнуто, отмечено, выбрано и т. д.)
• Настраиваемые поля: Выбор точно тех полей, которые должны отображаться в отчёте, в настройках дополнения с возможностью выделить всё и снять всё выделение
• Расширенная поддержка — Chrome Bridge (экспериментально): Подключение к сопутствующему расширению Chrome для получения реальных DOM-данных страницы, HTML-атрибутов и активных свойств напрямую
• AI-анализ с Gemini (экспериментально): Запрос к Google Gemini для получения пояснения на простом языке о том, что такое элемент в фокусе и как его можно использовать

Горячие клавиши

| Сочетание клавиш | Действие | |----------|--------| | NVDA+Shift+F1 | Показать детали элемента в фокусе |

Примечание: Вы можете изменить эту комбинацию в разделе Параметры > Жесты ввода в NVDA.

Как использовать

1. Перейдите к любому HTML-элементу на веб-странице с помощью клавиши Tab или клавиш со стрелками
2. Нажмите NVDA+Shift+F1, чтобы показать детали элемента в фокусе
3. Откроется окно сообщения с возможностью навигации, в котором будет показано:
   • Имя тега элемента и количество атрибутов
   • Доступное имя и его источник
   • Вычисленная ARIA-роль
   • Источник роли (родной или явный)
   • Семантические несоответствия
   • Все сырые атрибуты IA2
   • DOM-путь элемента в фокусе
   • Родительские элементы вверх по DOM-дереву

Отображаемая информация

Доступное имя

Имя, которое экранные ридеры объявляют для элемента.

Источник имени

Откуда берётся доступное имя:

• aria-label: Явная ARIA-метка
• aria-labelledby: Ссылка на другой элемент
• contents: Текстовое содержимое элемента
• alt: Alt-текст (для изображений)
• value: Атрибут значения элемента
• title: Атрибут title
• placeholder: Текст-заполнитель

Вычисленная роль

ARIA-роль, определяемая из:

1. Явных xml-ролей (атрибут role)
2. Родной семантики HTML
3. Сопоставления типов элементов управления NVDA
4. Неизвестно (запасной вариант)

Семантический источник

Откуда берётся роль:

• native HTML: Неявная семантика HTML (например, <button> → роль button)
• explicit role: Переопределение атрибута role
• redundant explicit role: Атрибут role соответствует родной семантике
• unknown: Невозможно определить

Семантическое несоответствие

Указывает, конфликтует ли явная ARIA-роль с родной семантикой HTML элемента.

DOM-путь

Краткий технический путь, который помогает определить местоположение элемента в структуре страницы (например: main > form#login > input[name="email"]).

Настройки

Откройте меню NVDA > Параметры > Параметры > Detailed Element Info, чтобы настроить дополнение:

• Выберите, какие поля показывать: Включение или отключение каждого поля отчёта — сводка тега, доступное имя, источник имени и уверенность, тег DOM и путь, явные/родные/роли NVDA/итоговые роли, семантический источник и несоответствие, сырые атрибуты IA2, атрибуты, полученные из состояний NVDA, роль MSAA и родительские элементы.
• Выбрать все / Снять все: Включение или отключение всех полей сразу.
• Включить расширенную поддержку (AI и расширение Chrome): Включает экспериментальные функции Chrome Bridge и AI, описанные ниже.
• Токен Gemini AI: Введите собственный ключ API Google Gemini для запуска AI-анализа.

Расширенная поддержка — Chrome Bridge (экспериментально)

Detailed Element Info может опционально подключаться к сопутствующему расширению Chrome, чтобы заглянуть за пределы виртуального буфера NVDA и читать реальный DOM страницы.

• Когда расширенная поддержка включена, дополнение запускает легковесный локальный сервер (127.0.0.1:63333), который общается с расширением Chrome через HTTP long polling.
• Затем отчёт включает раздел Активные DOM-атрибуты элемента с живыми HTML-атрибутами и свойствами, полученными из Chrome.
• Для этого требуется установить сопутствующее расширение Chrome. Функция является экспериментальной и находится в активной разработке.

AI-анализ с Gemini (экспериментально)

При включённой расширенной поддержке и установленном токене Gemini API в отчёте предлагается действие Запросить комментарий AI.

• Собранные DOM-данные отправляются в Google Gemini, который возвращает краткое пояснение на простом языке о том, что такое элемент, его назначение и как пользователь экранного ридера может с ним взаимодействовать.
• Для этого требуется собственный ключ API Google Gemini, введённый в настройках. Функция является экспериментальной.

Технические детали

Это дополнение использует родную архитектуру без зависимостей:

• Чистые стандартные библиотеки Python (http.server, urllib.request) для избежания проблем с зависимостями pip.
• Интерфейсы IAccessible2 (IA2) для атрибутов доступности
• Объектная модель NVDA и типы элементов управления
• Спецификации WAI-ARIA 1.2
• Роли MSAA Windows
• HTTP long polling: легковесный мост к сервис-воркеру Manifest V3 сопутствующего расширения Chrome, поддерживаемый в живом состоянии с помощью сердечных сигналов content-скрипта.

Автор

Mustafa Elçiçek mustafaelcicek5656@gmail.com

Поддерживаемые версии NVDA

• Минимальная: NVDA 2023.1
• Последняя проверка: NVDA 2026.1

Лицензия

GPL-2.0

Вклад в разработку

Приветствуется любой вклад! Пожалуйста, прочитайте руководство по внесению вклада (CONTRIBUTING.md) в репозитории проекта перед сообщением об ошибках, предложением улучшений или открытием запроса на включение.

Участники

Detailed Element Info создаётся с помощью участников кода, тестировщиков и сторонников. Полный список участников и того, над чем каждый из них работал, см. в CONTRIBUTORS.md в репозитории проекта.

Журнал изменений

Версия 1.0.1 (Совместимость с NVDA 2026.1)

• Обновлены метаданные совместимости дополнения для NVDA 2026.1

Версия 1.0.0 (Первый выпуск)

• Первоначальный выпуск Detailed Element Info
• Отображение ARIA-ролей и атрибутов
• Показ доступных имён и их источников
• Обнаружение семантических несоответствий
• Навигация по родительским элементам