Просмотр кода страницы Настройка именования элементов пользовательского интерфейса для взаимодействия с пользователем

= Настройка именования элементов пользовательского интерфейса для взаимодействия с пользователем =

'''Ранний доступ'''

Каждое взаимодействие пользователя включает в себя подробную информацию о задействованном элементе пользовательского интерфейса. Для веб-интерфейсов это '''HTML'''-элементы. Их имена используются в описаниях взаимодействий пользователей в приложении '''Пользователи и сессии'''. На этой странице объясняется, как работает именование элементов пользовательского интерфейса и как вы можете его настроить.

== Определение имени элемента пользовательского интерфейса по умолчанию ==

'''JavaScript'''-код '''RUM''' определяет имя элемента пользовательского интерфейса и сохраняет его в поле <code>ui_element.detected_name</code> при взаимодействии с пользователем. Для этого он проверяет атрибуты в следующем порядке и использует первое доступное совпадение:

# <code>aria-label</code>
# <code>title</code>
# <code>name</code> (например, для элементов <code>input</code>, <code>form</code>, <code>iframe</code>)
# <code>data-testid</code> (широко используемый пользовательский атрибут для идентификации узла '''DOM''' во время тестирования)
# <code>placeholder</code> (для элементов ввода)
# <code>id</code>

Если вы не зададите собственное имя, Ключ-АСТРОМ будет использовать <code>ui_element.detected_name</code> для определения поля <code>ui_element.name</code>, используемого в описаниях взаимодействия с пользователем в приложении '''Пользователи и сессии'''. Имя ограничено 32 символами. Для получения подробной информации о полях см. раздел «Взаимодействие с пользователем» в семантическом словаре.

== Обработка элемента <code>aria-hidden</code> ==

Когда пользователь щелкает по элементу внутри поддерева <code>aria-hidden="true"</code>, '''JavaScript'''-код '''RUM''' автоматически проходит вверх по цепочке предков, чтобы найти первого предка за пределами самого внешнего <code>aria-hidden="true"</code> поддерева, и использует его имя. Для вложенных <code>aria-hidden</code> поддеревьев найденным элементом является предок самой внешней скрытой границы. Это поведение применяется только к взаимодействиям по клику.

Это гарантирует, что захваченные имена будут отражать видимый элемент управления (например, кнопку «Удалить»), а не скрытый декоративный дочерний элемент (например, '''SVG'''-элемент <code>&lt;path&gt;</code>). Элемент, являющийся прямым дочерним элементом <code>&lt;body&gt;</code>, будет использовать исходный элемент.

'''Пример'''
<pre>
<!-- Кнопка-иконка в стиле Material UI -->
<button aria-label="Удалить" class="MuiIconButton-root">
  <svg aria-hidden="true" class="MuiSvgIcon-root" viewBox="0 0 24 24">
    <path d="M6 19c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V7H6v12z" />
  </svg>
</button>
</pre>

Когда пользователь щелкает по элементу <code>&lt;path&gt;</code>, зафиксированное взаимодействие отображает следующее:

* <code>tag_name</code>: <code>"button"</code>
* <code>detected_name</code>: <code>"Delete"</code>
* <code>name_origin</code>: <code>"aria-label"</code>

Чтобы отменить автоматическое разрешение, добавьте <code>data-dt-children-name</code> к родительскому элементу; см. раздел «Задание пользовательского имени для элемента и его дочерних элементов».

== Задайте пользовательское имя ==

Если имя, обнаруженное по умолчанию, не соответствует вашим требованиям, вы можете его настроить. '''JavaScript RUM''' сохраняет пользовательские имена в поле взаимодействия с пользователем <code>ui_element.custom_name</code>, наряду со стандартным полем <code>ui_element.detected_name</code>. Затем Ключ-АСТРОМ использует <code>ui_element.custom_name</code> вместо <code>ui_element.detected_name</code> для определения <code>ui_element.name</code>.

=== Задайте пользовательское имя для конкретного элемента ===

Чтобы задать пользовательское имя для конкретного элемента, добавьте '''HTML'''-атрибут <code>data-dt-name</code>. Пустые значения или значения, состоящие только из пробелов, <code>data-dt-name</code> игнорируются.

<pre>
<!-- Кнопка получает одновременно свойства ui_element.detected_name="Submit" и ui_element.custom_name="Checkout Button" -->
<button name="Отправить" data-dt-name="Кнопка оформления заказа">Отправить</button>
</pre>

=== Правильно обрабатывайте кнопки-иконки ===

Кнопки с иконками — это кнопки, видимой частью которых является вложенный элемент иконки (например, <code>svg</code>), и именно по нему чаще всего происходит клик. Если вы зададите <code>data-dt-name</code> пользовательское имя только для самой кнопки, оно будет использоваться только при клике на элемент кнопки. Если клик попадет на вложенную иконку, пользовательское имя не будет сохранено.

<pre>
<!-- Нажатие кнопки: ui_element.custom_name="Удалить элемент"; Нажатие на иконку: нет пользовательского имени -->
<button data-dt-name="Удалить элемент">
  <svg> <!-- значок корзины --> </svg>
</button>
</pre>

Чтобы закрыть и кнопку, и её значок, используйте <code>data-dt-children-name</code> методы, описанные в следующем разделе.

=== Задайте пользовательское имя для элемента и его дочерних элементов ===

Добавьте атрибут <code>data-dt-children-name</code>, чтобы задать пользовательское имя для самого элемента и для всех его дочерних элементов. Это позволит вам:

* Обозначить все элементы в списке или таблице.
* Присвоить имена всем элементам управления на панели инструментов или в разделе формы.
* Применять единообразное именование к динамическому контенту.
* Именовать элементы контейнера, представляющие бизнес-сущности.

Пустые значения или значения, содержащие только пробелы, <code>data-dt-children-name</code> игнорируются.

'''Примеры'''
<pre>
<!-- Сам div панели инструментов получает ui_element.custom_name="Действие панели инструментов" -->
<!-- Все кнопки внутри также получают ui_element.custom_name="Toolbar Action" -->
<div class="toolbar" data-dt-children-name="Toolbar Action">
  <button> ✂️ </button> <!-- ui_element.custom_name="Toolbar Action" -->
  <button> 📋 </button> <!-- ui_element.custom_name="Toolbar Action" -->
  <button> 🔍 </button> <!-- ui_element.custom_name="Toolbar Action" -->
</div>

<!-- Fieldset получает ui_element.custom_name="Billing Field" -->
<!-- Все поля ввода наследуют одно и то же пользовательское имя -->
<fieldset data-dt-children-name="Поле для выставления счетов">
  <input type="text" name="address"> <!-- ui_element.detected_name="address", ui_element.custom_name="Billing Field" -->
  <input type="text" name="city"> <!-- ui_element.detected_name="city", ui_element.custom_name="Billing Field" -->
  <input type="text" name="zip"> <!-- ui_element.detected_name="zip", ui_element.custom_name="Billing Field" -->
</fieldset>

<!-- Контейнер карточки и его содержимое получают осмысленные имена элементов пользовательского интерфейса -->
<div class="card" data-dt-children-name="Product Card">
  <!-- Сам div-элемент карточки содержит ui_element.custom_name="Product Card" -->
  <img src="product.jpg"> <!-- ui_element.custom_name="Product Card" -->
  <h3>Название товара</h3> <!-- ui_element.custom_name="Карточка товара" -->
  <button>Добавить в корзину</button> <!-- ui_element.custom_name="Карточка товара" -->
</div>
</pre>

=== Объединить атрибуты именования ===

Вы можете комбинировать <code>data-dt-name</code> и <code>data-dt-children-name</code>. В этом случае следуйте этим рекомендациям и помните о правилах наследования.

'''Передовые методы'''
* Используйте <code>data-dt-name</code> для обозначения конкретных, уникальных элементов, требующих индивидуальной идентификации.
* Используйте <code>data-dt-children-name</code> для групп, в которых контейнер и/или его дочерние элементы имеют общий бизнес-контекст.
* Объедините оба атрибута, если контейнеру требуется собственное имя, а дочерним элементам — другое общее имя:

<pre>
<div data-dt-name="Панель навигации" data-dt-children-name="Элемент навигации">
  <!-- Контейнер: ui_element.custom_name="Панель навигации" -->
  <a href="/home">Главная</a> <!-- ui_element.custom_name="Nav Item" -->
  <a href="/products">Магазин</a> <!-- ui_element.custom_name="Nav Item" -->
</div>
</pre>

=== Правила наследования ===

Пользовательское имя элемента определяется в следующем порядке приоритета:

# Приоритет всегда имеет собственный элемент <code>data-dt-name</code>.
# Если у элемента нет собственного <code>data-dt-name</code>, используется его собственный <code>data-dt-children-name</code>.
# Если у самого элемента нет ни одного из этих атрибутов, используется атрибут <code>data-dt-children-name</code> ближайшего предка.

'''Примеры'''
<pre>
<!-- Этот div имеет ui_element.custom_name="Card" (использует собственное имя дочерних элементов data-dt-children-name) -->
<div data-dt-children-name="Card">

  <!-- Этот div имеет ui_element.custom_name="Card Action" (использует собственное имя data-dt-children-name) -->
  <div data-dt-children-name="Действие карточки">
    <button>Редактировать</button> <!-- ui_element.custom_name="Действие карточки" (наследует) -->
    <button data-dt-name="Сохранить">Сохранить</button> <!-- ui_element.custom_name="Сохранить" (собственный data-dt-name имеет приоритет) -->
  </div>

  <p>Содержимое карточки</p> <!-- ui_element.custom_name="Card" (наследует от родительского элемента) -->
</div>

<!-- Этот div содержит ui_element.custom_name="Dashboard Widget" -->
<div data-dt-children-name="Виджет панели управления">

  <!-- ui_element.custom_name="Widget Header" (data-dt-name имеет приоритет над наследованием) -->
  <header data-dt-name="Заголовок виджета">
    <h2>Продажи</h2> <!-- ui_element.custom_name="Dashboard Widget" (наследует от родительского элемента) -->
  </header>

  <!-- Этот div имеет ui_element.custom_name="Chart Container" (использует собственное имя data-dt-children-name) -->
  <div data-dt-children-name="Контейнер диаграммы">
    <canvas>Диаграмма</canvas> <!-- ui_element.custom_name="Контейнер диаграммы" (наследует от родительского элемента) -->
  </div>

  <footer>
    <button>Обновить</button> <!-- ui_element.custom_name="Виджет панели управления" (наследует от предка) -->
  </footer>
</div>
</pre>