> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/all-out-docs/ru/ui/uidoc-html-css-support.md). # Поддержка HTML и CSS в UIDoc *** UIDoc намеренно реализует практический подмножество, похожее на браузер, для игрового UI. Он заранее компилирует ресурсы и отображает их через движок; он не запускает браузер, JavaScript или живой DOM. Для рабочего первого экрана начните с [UIDoc: Быстрый старт](/all-out-docs/ru/ui/uidoc-quick-start.md). Сгенерированная ссылка на репозиторий, `docs/uidoc_supported_css.md`, — это исчерпывающий список свойств/значений. Он выводится `UIDoc::debug_supported_css_reference()` и проверяется тестами UIDoc. Эта страница объясняет этот контракт на уровне автора. Неизвестные объявления, отклонённые значения, неподдерживаемые селекторы, некорректный HTML и неподдерживаемые медиазапросы — это ошибки компиляции. Парсер может продолжить сбор диагностик, но ресурс недействителен, пока ошибки не будут исправлены. Неподдерживаемые блочные at-правила CSS пропускаются молча; не полагайтесь на поведение at-правил браузера. HTML и CSS UIDoc не перезагружаются «на лету» в запущенной игре. Перезапустите игру после изменений в ресурсах. Для отладки во время выполнения, `uidoc_runtime_inspect` показывает живые узлы DOM, текущие привязки, вычисленные стили, полезные нагрузки обработчиков событий/ключей и прямоугольники. Его `screen_rect`, `client_ui_tree` и `client_click` используют координаты вьюпорта движка с началом в левом нижнем углу; пиксели скриншота используют начало в левом верхнем углу. Инструмент `compile` включает структурированные диагностики UIDoc прямо в строке, когда предварительная обработка ресурса завершается сбоем. `uidoc_diagnostics` с `viewportMatrix: true` возвращает суммарные количества успешных проходов и группирует одну и ту же категорию проблемы для одного и того же исходного узла по профилям. `unique_issue_count` — это сгруппированное количество узел/категория; `issue_occurrence_count` — это сырая сумма по всем записям viewport/scale. Устанавливайте `viewportMatrixVerbose: true` только когда каждая неудачная запись полезна. Разные исходные узлы не объединяются, даже если они разделяют селектор или строку исходника CSS, так что проблема в общем правиле может все равно появиться как несколько групп; исправьте правило один раз и запустите диагностику снова. Два распространенных предупреждения при авторинге требуют контекста: * `dynamic_text_intrinsic_layout` означает, что часто меняющийся текст может изменить блок с неявно заданным размером и сделать недействительным кэшированный макет. Добавьте `data-text-reserve` с самым широким ожидаемым, учитывающим локализацию примером, или задайте элементу определённую ширину и высоту. Это не ошибка дублирования текста или рендеринга. * `image_aspect_drift` означает, что у изображения независимые ширина и высота с `object-fit: fill`. Используйте `contain`, `cover` или `aspect-ratio` для обычной графики. Специально созданная полоса заполнения прогресса, намеренно растянутая в своей дорожке, — допустимое исключение; визуально проверьте этот случай. ## HTML и атрибуты UIDoc Имена элементов принимаются как обычные узлы макета. У этих элементов есть особое поведение во время выполнения: | Элемент | Поведение | | -------- | -------------------------------------------------- | | `span` | Встроенный текстовый контент | | `img` | Изображение ресурса движка, загружаемое из `src` | | `button` | Взаимодействие указателем и события клика | | `input` | Редактируемый текст, связанный с `data-bind-value` | Непустой текстовый контент создает текстовые узлы. Используйте `{{name}}` для привязки текста верхнего уровня и `{{item.name}}` внутри повторяющегося списка. Значения изображения `src` также поддерживают эту интерполяцию. Имена классов и `data-key` значения статичны. | Атрибут | Назначение | | ---------------------------------- | ------------------------------------------------------------------------------------------------------- | | `id`, `class`, `style` | Сопоставление CSS и встроенный стиль | | `src`, `width`, `height` | Источник изображения и размеры | | `value`, `placeholder`, `disabled` | Состояние ввода и элемента управления | | `data-if="binding"` | Включить поддерево, пока булева привязка верхнего уровня истинна; необязательный `!` инвертирует ее | | `data-for="item in items"` | Повторить поддерево для списка, привязанного к CSL | | `data-for-key="item.id"` | Разрешить ключ `event.key` повторного клика из прямого выражения | | `data-key="role"` | Назначить узлу статическую роль взаимодействия/ввода | | `data-bind-value="name"` | Подключить ввод к текстовому значению UIDoc | | `data-text-reserve="00:00"` | Измерить стабильный буквальный образец при отрисовке живого связанного текста | | `data-on-click="event:name"` | Отправить событие клика в колбэк CSL; `event.handler` получает точное полное значение, включая `event:` | | `data-style-transform-x/y` | Привязать числовое смещение без перерасчета макета | | `data-style-transform-scale` | Привязать числовой визуальный масштаб | | `data-style-opacity` | Привязать числовую непрозрачность | | `data-style-color` | Привязать поддерживаемую CSS-строку цвета без изменения структуры | | `data-style-image-fill-amount` | Привязать величину заполнения изображения | | `data-scroll-zoom` | Привязать полный масштаб содержимого на прокручиваемом вьюпорте | Атрибуты выражений привязки содержат прямые выражения, например `data-for-key="item.id"`, `data-style-opacity="item.opacity"` и `data-scroll-zoom="zoom"`. Не помещайте эти выражения внутрь `{{...}}`. Интерполяция Mustache ограничена текстом и изображением `src` значениями. `data-if` уже, чем другие атрибуты привязки, учитывающие списки: он ищет булево значение верхнего уровня и не разрешает повторяющийся псевдоним, такой как `item.visible`. Для неинтерактивного визуального состояния в повторяющемся поддереве привязывайте `item.opacity` или `item.color`. Непрозрачность не отключает проверку попадания, поэтому фильтруйте структурные или интерактивные строки при построении списка CSL, а не оставляйте на месте невидимую кнопку. ### Идентичность повторяющегося элемента управления и тесты `data-for-key` определяет ключ `event.key`повторного клика. Идентичность элемента управления во время выполнения отдельна: она начинается со статического `data-key` (затем HTML `id`, затем запасной безымянный тег) и добавляет `#key:index` для каждого охватывающего цикла. Здесь `key` — это значение, переданное в `UI.uidoc_list_item(...)`; обычно оно должно быть тем же стабильным ID, который разрешается `data-for-key`. Поэтому повторяющаяся кнопка может отображаться в `client_ui_tree` как: ``` UI/board.uidoc:seed-cell#seed-42:7/__widget ``` Используйте `client_ui_tree` чтобы скопировать точную живую идентичность. `Test.click_button` принимает полное имя или суффикс и рассматривает конечный `/__widget` как необязательный, так что `Test.click_button("seed-cell#seed-42:7")` выбирает этот экземпляр, когда суффикс уникален. Запрос только по роли может выбрать произвольный ближайший повторяющийся экземпляр. Вложенные списки добавляют несколько `#key:index` пар. Строки обработчиков и видимые метки не являются селекторами идентичности. Сырые `style` и `script` блоки в HTML — это ошибки компиляции. Помещайте авторский CSS в `index.css`; среды выполнения JavaScript нет. ## CSS селекторы и каскад Поддерживаются селекторы: * Имена элементов, `.class`, `#id` и `*`. * Потомок и непосредственный дочерний (`>`) комбинаторы. * Списки селекторов, разделенные запятыми. * `:hover`, `:focus`, `:active`, `:pressed`, `:mouse-down`, `:dragging`, `:scroll-state` и `:disabled`. UIDoc использует обычную специфичность id/class/type и порядок исходника как тай-брейк. Встроенный `style` применяется последним. Порядок отрисовки использует `z-index`, затем порядок документа. Объявления, влияющие на макет, внутри правил псевдосостояний взаимодействия игнорируются и диагностируются. Наведение на кнопку может безопасно менять ее цвет или непрозрачность, но не должно менять ее размер или окружающий макет. Неподдерживаемые формы селекторов включают соседние комбинаторы, атрибутные селекторы, псевдоэлементы, `:not()`, `:nth-*`, `:is()`, `:where()` и `:has()`. ## Макет CSS UIDoc поддерживает `display: block`, `display: flex` и `display: none`. Другие значения display диагностируются и откатываются к block. Его свойства макета: * `width`, `height`, `min-*`, `max-*`, `aspect-ratio` и `box-sizing`. * `margin`, `padding`, `gap`, `row-gap` и `column-gap`. * `flex`, `flex-direction`, `flex-wrap`, `flex-grow`, `flex-shrink` и `flex-basis`. * `align-items`, `align-self`, `align-content` и `justify-content`. * `position: static`, `relative`, `absolute` или `fixed`, с `inset`, `top`, `right`, `bottom` и `left`. * `overflow`, `overflow-x` и `overflow-y` используя `visible`, `hidden`, `auto` или `scroll`. Длины поддерживают соответствующие комбинации пикселей без единиц, `px`, `rem`, `em`, `%`, `vw`, `vh`, safe-area `env(...)`, а также сложение или вычитание `calc(...)` с числом до восьми слагаемых. Процентные padding и margin диагностируются и игнорируются. Процентные и viewport-единицы также недопустимы для gap, но поддерживаются размерами, flex basis и отдельными `top`/`right`/`bottom`/`left` смещениями. `padding`, `margin` и `inset` поддерживают стандартные формы с одним, двумя, тремя и четырьмя значениями. Процентные значения не поддерживаются в `inset` сокращенной записи; используйте отдельные свойства смещения, когда нужны проценты. Ключевые слова CSS и математика проверяются для каждого свойства отдельно, а не принимаются глобально только потому, что браузер где-то их принял бы. В частности: * `auto` допустимо только для строк свойств, где оно перечислено, таких как размеры, flex basis, смещения, `align-self`, и overflow. * `none` допустимо только там, где указано, например `display`, поддерживаемые сбросы paint/filter, `pointer-events` и `image-fill-direction`. * `calc(...)` доступен только в документированных полях длины. Он допускает сложение и вычитание не более восьми простых длинных терминов. Умножение, деление, вложенная математика, `min()`, `max()` и `clamp()` не поддерживаются, а процентные термины требуют определенного содержащего блока. Если сомневаетесь, проверьте точную строку свойства в `docs/uidoc_supported_css.md`; значения, принимаемые другим свойством, не доказывают, что тот же токен работает здесь. ## Текст, изображения и отрисовка Поддерживаемые возможности представления включают: * `color`, `background`, `background-color`, и один линейный, радиальный или конический `background-image` градиент. * `border`, `border-width`, `border-color`, и одно равномерное `border-radius` значение. Сторонозависимые границы, такие как `border-bottom`, радиусы по углам и процентные радиусы не поддерживаются. Используйте явный дочерний разделитель с фиксированной высотой/шириной и цветом фона, когда нужен только один край. * До восьми разделенных запятыми `box-shadow` или `text-shadow` слоев; тени блока могут быть inset. * Один `filter: blur(...)` или `filter: drop-shadow(X Y [blur] [color])`, плюс `backdrop-filter: blur(...)`. * `opacity`, `z-index` и `pointer-events`. * `font-family`, `font-size`, `font-style`, `font-weight`, `line-height`, `letter-spacing`, `text-align`, `white-space`, `overflow-wrap` и `word-break`. * Текст `outline-color` и `outline-width`. * `object-fit: cover`, `contain` или `fill` для изображений. * `image-tint`, `image-grayscale`, `image-fill-amount` и `image-fill-direction`. * `translate`, `масштаб`, а также `translate(...)`, `translateX(...)`, `translateY(...)` и `scale(...)` подмножество transform. Проценты translate вычисляются относительно собственной border box элемента; единицы translate, привязанные к viewport, по-прежнему не поддерживаются. Цвета поддерживают распространённые CSS-формы, включая hex, `rgb()`/`rgba()`, `hsl()`/`hsla()`, именованные цвета, `transparent` и `currentColor` где применимо. Градиенты поддерживают до восьми цветовых остановок, CSS-направления/углы и позиции, `currentColor` и `в oklab` или `в srgb`; Oklab используется по умолчанию. Несколько слоёв фона и CSS URL изображений не поддерживаются. Используйте `img` с путём к ресурсу движка для растровых фонов. `box-shadow` следует прямоугольной рамке границы элемента. `filter: drop-shadow(X Y [blur] [color])` следует отрисованной альфе отфильтрованного элемента, включая прозрачные углы изображения. Если цвет не указан, по умолчанию используется цвет элемента `currentColor`. Поместите это на сам `img` для нерегулярного или nine-sliced растрового изображения; при размещении на контейнере в силуэт тени также включаются отрисованные потомки контейнера. ### Заполнение прогресс-изображения Для непрерывной полосы прогресса поместите полноразмерное `img` внутрь трека фиксированного размера, привяжите нормализованное `0..1` значение с помощью `data-style-image-fill-amount`, и установите `image-fill-direction: right` плюс `object-fit: fill`. Используйте прямоугольную или градиентную текстуру без нежелательных прозрачных промежутков внутри полосы. Не используйте значок или другое декоративное прозрачное изображение для заливки. `image-tint` является мультипликативным и сохраняет исходную альфу; он не делает прозрачные пиксели непрозрачными. `object-fit: cover` также агрессивно обрезает квадратные изображения, когда трек тонкий. В совокупности эти решения могут создавать пустое начальное пространство или диагональные клинья, даже если обрезка заливки UIDoc работает правильно. Диагностика в настоящее время не проверяет альфу текстуры и не помечает `object-fit: cover` заливки прогресса. Проверяйте полосы прогресса визуально на `0`, `0.25`, `0.5` и `1`. Парные `fill_*.png` ресурсы специально созданы для соответствующих подложек, и `.kit-progress-fill` применяет нужное масштабирование. По умолчанию UIDoc использует встроенное семейство AllIn с реальными начертаниями 400, 700 и 900. `@font-face` может объявлять ресурсы шрифтов TTF или OTF проекта по ID ресурса. Начертание и насыщенность выбирают ближайшее объявленное начертание; отсутствующие жирный или наклонный варианты могут быть синтезированы. Шрифты загружаются асинхронно, поэтому UIDoc использует следующее семейство или AllIn, пока запрошенное начертание не будет готово, а затем пересчитывает разметку текста. Опустите `line-height` для высоты строки по умолчанию, которая масштабируется вместе с размером шрифта. Явное `line-height: normal` не принимается. Безразмерные значения — это множители; значения длины — фиксированные наследуемые длины. `letter-spacing` наследуется и принимает `normal`, безразмерные пиксели, `px`, `rem` или `em`. `normal` вычисляется как ноль. Подмножество transform не включает вращение, наклон, 3D-преобразования или много-токенные `масштаб` значения. Значение filter содержит один `blur(...)` или один `drop-shadow(...)`; цепочки фильтров и другие функции filter не поддерживаются. Области компоновщика filter и backdrop-filter могут вкладываться до четырёх уровней. ## Адаптивные стили и безопасные области Media-запросы поддерживаются, но только для этого явного списка разрешённых условий: * `(min-width: N)` и `(max-width: N)`. * Комбинированные запросы минимальной и максимальной ширины. * в стиле Tailwind `(width >= N)` и `(width <= N)`. * `(hover: hover)`. Значения ширины принимают безразмерные пиксели, `px` и `rem`. Неподдерживаемые медиаблоки отбрасываются с диагностическим сообщением. Используйте эти значения там, где принимаются длины safe-area: ```css env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left) ``` Верхний safe-area inset UIDoc также резервирует полосу верхней панели игры. ## Прокрутка и масштабирование `overflow-x` и `overflow-y` независимы, поэтому один viewport может прокручиваться по горизонтали, вертикали или по обеим осям. Двухосевой viewport перемещает обе оси при перетаскивании. Колёсико мыши прокручивает вертикально, когда включена вертикальная прокрутка; viewport только с горизонтальной прокруткой отображает колёсико в горизонтальную прокрутку. В настоящее время runtime рисует ползунок вертикальной полосы прокрутки. Горизонтальный контент по-прежнему доступен перетаскиванием, хотя горизонтальный ползунок не рисуется. `data-scroll-zoom="zoomBinding"` добавляет подобное браузеру масштабирование содержимого к интерактивному viewport с прокруткой. Оно масштабирует геометрию потомков, текст, изображения, преобразования, область попадания и диапазоны прокрутки, в то время как viewport и его соседние элементы остаются фиксированными. Когда binding изменяется, движок сохраняет видимую область вокруг центра viewport и повторно ограничивает позицию прокрутки. Безопасный диапазон движка составляет `0.05` до `20`; приложения обычно должны использовать более узкие пределы. ## Классы в стиле Tailwind Ресурсы UIDoc могут использовать поддерживаемые утилитарные классы в стиле Tailwind. Утилиты разрешаются и преобразуются в CSS UIDoc во время обработки ресурса; Tailwind в игре не выполняется. Охватываются display, position, flex, sizing, spacing, inset, alignment, text, color, border, radius, overflow, pointer events, opacity, z-index, aspect ratio, shadows, transforms и произвольные свойства эффектов изображения. Шаг преобразования поддерживает `hover:`, `focus:`, `active:`, `disabled:`, адаптивные `sm:`/`md:`/`lg:`/`xl:`/`2xl:`, значения в квадратных скобках, такие как `w-[320px]`, а также CSS `@apply`. Preflight/base reset Tailwind не включён. Вывод, который нельзя представить в UIDoc, приводит к ошибке сборки ресурса. ## Заметные функции браузера, которые не поддерживаются | Функция браузера | Подход UIDoc | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | JavaScript и DOM API | Управляйте состоянием с помощью привязок CSL, `data-if`, `data-for`, и callbacks событий. | | CSS Grid | Используйте flexbox, блочную раскладку или явное позиционирование. | | CSS-переменные и пользовательские свойства | Привязывайте значения из CSL или используйте обычные общие классы. | | Переходы, keyframes и CSS-анимации | Анимируйте привязки CSL, такие как opacity, translation, scale или scroll zoom. | | Псевдоэлементы и расширенные селекторы | Добавляйте в документ явные элементы и классы. | | Запросы контейнера и большинство media-возможностей | Используйте поддерживаемые запросы viewport-width и hover. | | CSS-фоновые URL и несколько слоёв фона | Используйте поддерживаемый градиент или `img` ресурс движка. | | Радиусы по углам и более восьми теней | Используйте поддерживаемые ограничения на один радиус/восемь теней или явные вложенные элементы. | | `min()`, `max()` и `clamp()` CSS-математические функции | Сочетайте `width`/`height` с поддерживаемыми `min-*` и `max-*` свойствами. | | Поворот, skew, 3D-преобразования, цепочки фильтров и другие функции filter | Подготовьте визуал как ресурс или используйте поддерживаемые эффекты translate/scale/blur/drop-shadow. | | Веб-формы, навигация, fetch, iframe, canvas, SVG DOM, audio и video | Используйте CSL и соответствующие системы движка. | | Семантика браузера и поведение доступности | Элементы UIDoc — это узлы игрового интерфейса; имена HTML-тегов не подразумевают поведение браузера. | UIDoc стремится упростить создание типового игрового интерфейса, а не воспроизводить каждую функцию HTML и CSS. Держите разметку в пределах этого подмножества, чтобы ресурсы собирались предсказуемо, а клиентская/серверная симуляция UI оставалась детерминированной.