Соглашения о названиях

С UI Toolkit вам нужно будет запросить визуальные элементы и USS, используя идентификатор строки, так что использование определенного набора стандартов приведет, в целом, к меньшему количеству ошибок и более читаемому коду.

Поскольку команды разработчиков будут обращаться к одним и тем же ассетам UXML и USS, из которых состоит ваш интерфейс, важно стандартизировать соглашения об именовании и визуальных элементов, и таблиц стилей. Соглашения об именовании помогают поддерживать порядок в иерархии UI Builder. Они также снимают догадки о соглашениях по коду и форматированию и помогают сохранять единообразие кодовой базы.

В приведенном ниже примере кода имя элемента button используется для запроса и хранения ссылки на него в C#:

root.Query<Button>("foo").First();

Не существует универсального стиля. Выбирайте и выбирайте то, что лучше всего подходит для вашей команды и проекта. Однако, в целом, рекомендуется придерживаться как можно ближе к отраслевым стандартам. По этой причине, мы рекомендуем Block Element Modifier (BEM) для ваших визуальных элементов и таблиц стилей. BEM широко используется в контексте CSS и современной веб-разработки, из которой UI Toolkit черпает вдохновение.

Имя элемента в стиле BEM может сразу сказать вам, что он делает, где он появляется и как он связан с другими элементами вокруг него. BEM использует три основных компонента в следующем соглашении:

block-name__element-name--modifier-name

Вот пример:

navbar-menu__shop-button--small

Каждая часть имени может состоять из латинских букв, цифр и тире. Также обратите внимание, что каждая часть имени соединяется либо двойной подчеркиванием __, либо двойной тире --. Давайте подробнее рассмотрим три компонента:

Имя блока (block-name) представляет собой компонент высокого уровня, например меню навигационной панели, символы статистики --, любой отдельный и значимый компонент UI в вашем макете. В случае общей кнопки, которая не специфична для какого-либо конкретного блока, это можно просто пропустить, e.g., button--small.
Элемент (element-name) является дочерним элементом или частью блока и поэтому семантическим образом связан с его блоком. Другими словами, элементы зависят от блока для своего контекста и не могут существовать без него. Таким образом, пример shop-button указывает, что эта кнопка стилизована иначе, чем другие кнопки, принадлежащие к блоку navbar-menu (e.g., shop-button в navbar-menu__shop-button).
- Если ваш новый элемент инстанционирует дочерние элементы в своем конструкторе, назначайте дочерним элементам соответствующие классы. Например, my-block__first-child, my-block__other-child.
Наконец, модификатор указывает на разновидность или состояние блока либо элемента. Это может быть нажатие кнопки, выбор и подсветка элемента текстового поля или, как в нашем примере, уменьшённый вариант кнопки магазина. Это упрощает адаптацию к разным сценариям без дублирования кода.

Вот ещё несколько примеров именования BEM:

menu__button-home
menu__button-shop
navbar-menu__shop-button--small
navbar-menu__shop-button--large

Имена классов по BEM самодостаточны: разработчику проще понять структуру и назначение компонентов, а значит, легче поддерживать понятную иерархию для управления стилями и их обновления по мере роста проекта. Общее правило — предпочитать читаемость краткости. Ясность важнее пары секунд, сэкономленных на выброшенных гласных.

В этих примерах используется разделение дефисами (также известное как Kebab case), которое обычно используется для именования CSS. Ваша команда должна решить на раннем этапе проекта, какая схема именования работает лучше всего для них, и придерживаться ее на протяжении всей разработки.

Подробнее о соглашениях именования CSS читайте в этой статье, а также в документации UI Toolkit.

💡 Советы: Конвенции именования в UI Toolkit

Вот некоторые рекомендации для эффективного наименования:

Обеспечьте, чтобы названия были краткими, но достаточно описательными, чтобы передать их цель и роль в UI.
Используйте имена, чтобы подчеркнуть роли и взаимоотношения, например, inventory__slot--equipped вместо inventory__button--equipped. Опустите типовые имена, такие как Button или Label, если они не добавляют ясности.
Избегайте имен/модификаторов, которые могут меняться (e.g., используйте button--quit вместо button--red, когда цветовая схема еще не окончательна). Используйте семантическое именование, а не презентационное, что гарантирует, что имена останутся актуальными, даже если детали стиля изменятся.
Распространите эти соглашения и на художественные ассеты — спрайты и текстуры, связанные с интерфейсом UI Toolkit. Единообразие имён в коде и ассетах помогает сохранять понятную связь между ними и поддерживать порядок во всём проекте.
Если вы используете этот элемент в других проектах, добавьте к своим классам префикс, чтобы избежать конфликтов с уже существующими пользовательскими именами классов. Пространства имён или префиксы помогают избежать столкновений при интеграции с другими проектами и библиотеками.
Используйте AddToClassList() в конструкторе для добавления соответствующих классов USS к экземплярам элементов. Этот метод обеспечивает применение соответствующих стилей путем добавления необходимых классов во время экземплярирования элементов, поддерживая последовательность и ясность в коде UI.

Создать C# руководство по стилю

Если вы или ваша команда хотите уточнить ключевые практики кодирования, чтобы сделать ваш проект более масштабируемым, ознакомьтесь с нашей бесплатной электронной книгой: Создание руководства по стилю C#: Написать более чистый код, который масштабируется. Используйте это руководство по мере необходимости, чтобы помочь стандартизировать стиль кода и соглашения о названиях.