Соглашения об именовании в UI Toolkit

UI Toolkit naming conventions

If debugging is the process of removing software bugs, then programming must be the process of putting them in. — Edsger W. Dijkstra, computer science pioneer

While our guide so far has focused on C# code style, we also want to touch upon naming conventions for using UI Toolkit and working with UXML and CSS. With UI Toolkit you’ll need to query the visual elements and Unity Style Sheets (USS) using a string identifier, so using a defined set of standards will lead overall to fewer errors and more readable code. We generally recommend the Block Element Modifier (BEM) naming convention for your visual elements in the UXML and Style Sheets classes. BEM is widely used in the context of CSS and modern web development that is the inspiration for UI Toolkit. At a glance, an element’s BEM-style name can tell you what it does, where it appears, and how it relates to other elements around it. BEM uses three main components in the following convention: block-name__element-name--modifier-name

Here’s an example: navbar-menu__shop-button--small Each name part may consist of Latin letters, digits, and dashes. Also note that each name part is joined together with either a double underscore __ or a double dash --. The block name (block-name) represents a high level-compontent, like a navigation menu or character stats – a distinct and meaningful UI component in your layout. In the case of a generic button that is not specific to any particular block, that can simply be left out, e.g., button--small. The element element-name is a child or part of a block and therefore, semantically tied to its block. In other words, elements rely on the block for their context and cannot exist without it. So, in the case of the shop-button example, its style indicates that it’s different from other buttons belonging to the navbar-menu block (e.g., shop-button in navbar-menu__shopbutton). If your new element instantiates child elements in its constructor, assign the relevant classes to the children. For example, my-block__first-child, my-block__other-child. Finally, the modifier indicates a variation or state of a block or element. That could be when a button is pressed, a textbox item is selected and highlighted or in our example when it’s a small variant of the shop button. This makes it easy to adapt to different scenarios without duplicating code. Here are some more examples of BEM naming: —

menu__home-button

menu__shop-button

navbar-menu__shop-button--small

BEM class names are self-descriptive, making it easier for developers to understand the structure and purpose of components and making a clear hierarchy helps manage and update styles as projects grow. These examples use hyphen delimiting (aka Kebab case), which is common for CSS naming. Like with our other general guidelines, teams can decide which naming scheme works best for them, but should aim to choose early in the project and stay consistent later on. Read more about CSS naming conventions in this article, as well as in the UI Toolkit documentation.

Tips for naming conventions in UI Toolkit Here are some guidelines for effective naming: —

Keep names short and clear (unambiguous). It’s important to ensure that names are concise yet descriptive enough to convey their purpose and role within the UI.

Avoid using type names (Button, Label) or element names (#my-button) in your BEM selectors. This avoids redundancy and potential confusion. BEM names should represent their roles and states, not their types.

Avoid names/modifiers that can change (e.g., use “button–quit” instead of “button– red” when the color scheme is not yet final). Use semantic naming rather than presentational naming, which ensures names remain relevant even if styling details change.

Extend these conventions to art assets, like sprites and textures associated with the UI Toolkit interface. Consistency in naming between code and assets helps maintain a clear relationship and better organization throughout the project.

If you use the element in other projects, consider prefixing your classes to avoid conflicts with existing user class names. Namespacing or prefixing can prevent clashes when integrating with other projects or libraries.

Use AddToClassList() in the constructor to add the relevant USS classes to your element instances. This method ensures that the appropriate styles are applied by adding the necessary classes at the time of element instantiation, maintaining consistency and clarity in your UI code.