Поддержка HTML и CSS в UIDoc

Функции HTML, CSS, адаптивной компоновки, взаимодействия, прокрутки и привязок, поддерживаемые UIDoc, а также важные возможности браузера, которых в нем нет.

---

UIDoc намеренно реализует практический подмножество, похожее на браузер, для игрового UI. Он заранее компилирует ресурсы и отображает их через движок; он не запускает браузер, JavaScript или живой DOM.

Для рабочего первого экрана начните с UIDoc: Быстрый старт.

Сгенерированная ссылка на репозиторий, 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:

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 оставалась детерминированной.