> 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 и неподдерживаемые медиазапросы — это ошибки компиляции. Парсер может продолжать собирать диагностику, но ресурс недействителен, пока ошибки не исправлены. Неподдерживаемые блочные @-правила CSS молча пропускаются; не полагайтесь на поведение браузерных @-правил. Для отладки во время выполнения, `uidoc_runtime_inspect` предоставляет живые узлы DOM, текущие привязки, вычисленные стили, обработчики событий/полезные нагрузки клавиш и прямоугольники. Пока запущен Start Game, его область по умолчанию — активный клиент; без запущенного клиента явно укажите `scope: "editor"` чтобы инспектировать среду выполнения редактора. Каждый ответ во время выполнения указывает свой `область`, поэтому editor-realm `live_instance_count` не описывает клиент. Его `screen_rect`, `client_ui_tree`, и `client_click` используют координаты области просмотра движка с началом в левом нижнем углу; пиксели скриншота используют начало в левом верхнем углу. Инструмент `compile` предварительно проверяет каждый текущий `.uidoc` исходный каталог под `res` перед компиляцией скриптов или разрешением запуска Start Game. Сбой предварительной проверки сообщает `фазу`, `файл`, `строку`, и `столбец`, а также полные структурированные диагностические сведения. `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"` | Подключить input к текстовому значению 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`. Время выполнения идентичности управления отдельно: она начинается со статического `значения статичны.` (затем 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` слоёв; box-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`, `межбуквенный интервал`, `выравнивание текста`, `пробелы и переносы`, `перенос длинных слов`, и `перенос слов`. * Текст `цвет обводки` и `толщина обводки`. * `object-fit: cover`, `contain`, или `заливка` для изображений. * `тонирование изображения`, `обесцвечивание изображения`, `степень заполнения изображения`, и `image-fill-direction`. * `translate`, `масштаб`, и `translate(...)`, `translateX(...)`, `translateY(...)`, и `scale(...)` поднабор transform. Проценты в translate вычисляются относительно собственной рамки элемента; единицы viewport для translate по-прежнему не поддерживаются. Цвета поддерживают распространённые 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`. Используйте прямоугольную или градиентную текстуру без непреднамеренных прозрачных промежутков внутри полосы. Не используйте повторно значок или другое декоративное прозрачное изображение для заливки. `тонирование изображения` является мультипликативным и сохраняет исходную альфу; он не делает прозрачные пиксели непрозрачными. `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` не принимается. Безразмерные значения — это множители; значимые значения — фиксированные унаследованные длины. `межбуквенный интервал` наследуется и принимает `normal`, безразмерные пиксели, `px`, `rem`, или `em`. `normal` сводится к нулю. Поднабор transform не включает вращение, наклон, 3D-преобразования или много-токенные `масштаб` значения. Значение filter содержит один `blur(...)` или один `drop-shadow(...)`; цепочки фильтров и другие функции фильтров не поддерживаются. Области компоновщика filter и backdrop-filter могут вкладываться до четырёх уровней. ## Адаптивные стили и безопасные области Медиа-запросы поддерживаются, но только для этого явного списка разрешённых условий: * `(min-width: N)` и `(max-width: N)`. * Комбинированные запросы минимальной и максимальной ширины. * в стиле Tailwind `(width >= N)` и `(width <= N)`. * `(hover: hover)`. Значения ширины принимают безразмерные пиксели, `px`, и `rem`. Неподдерживаемые медиа-блоки отбрасываются с диагностическим сообщением. Используйте эти значения там, где принимаются длины безопасной области: ```css env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left) ``` Верхний отступ safe-area в UIDoc также резервирует полосу верхней панели игры. ## Прокрутка и масштабирование `overflow-x` и `overflow-y` независимы, поэтому одно окно просмотра может прокручиваться по горизонтали, по вертикали или по обеим осям. Окно просмотра с двумя осями сдвигает обе оси при перетаскивании. Колесо мыши прокручивает по вертикали, когда включена вертикальная прокрутка; окно просмотра только с горизонтальной прокруткой переназначает колесо на горизонтальную прокрутку. Во время выполнения сейчас рисуется ползунок вертикальной полосы прокрутки. Горизонтальный контент по-прежнему доступен перетаскиванием, хотя горизонтальный ползунок не рисуется. `data-scroll-zoom="zoomBinding"` добавляет похожее на браузер масштабирование содержимого в интерактивное окно просмотра с прокруткой. Оно масштабирует геометрию потомков, текст, изображения, преобразования, область попадания и диапазоны прокрутки, в то время как окно просмотра и его соседние элементы остаются фиксированными. Когда привязка меняется, движок сохраняет просматриваемую область вокруг центра окна просмотра и повторно ограничивает позицию прокрутки. Безопасный диапазон движка — `0.05` до `20`; приложениям обычно следует использовать более узкие пределы. ## Классы в стиле Tailwind Ресурсы UIDoc могут использовать поддерживаемые утилитарные классы в стиле Tailwind. Утилиты разрешаются и преобразуются в CSS UIDoc во время обработки ресурсов; Tailwind в игре не запускается. Охваченные области включают display, position, flex, sizing, spacing, inset, выравнивание, текст, цвет, границу, радиус, overflow, pointer events, opacity, z-index, aspect ratio, тени, преобразования и произвольные свойства image-effect. Этап понижения поддерживает `hover:`, `focus:`, `active:`, `disabled:`, адаптивные `sm:`/`md:`/`lg:`/`xl:`/`2xl:`, значения в квадратных скобках, такие как `w-[320px]`, и CSS `@apply`. Сброс preflight/base Tailwind не включён. Вывод, который нельзя представить в UIDoc, приводит к ошибке выпечки ресурса. ## Заметные функции браузера, не поддерживаемые | Функция браузера | Подход UIDoc | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | JavaScript и API DOM | Управляйте состоянием с помощью привязок CSL, `data-if`, `data-for`, и обработчиков событий. | | CSS Grid | Используйте flexbox, блочную верстку или явное позиционирование. | | CSS-переменные и пользовательские свойства | Привязывайте значения из CSL или используйте обычные общие классы. | | Переходы, ключевые кадры и CSS-анимации | Анимируйте привязки CSL, такие как непрозрачность, смещение, масштаб или масштабирование прокрутки. | | Псевдоэлементы и расширенные селекторы | Добавляйте в документ явные элементы и классы. | | Запросы контейнера и большинство медиавозможностей | Используйте поддерживаемые запросы ширины области просмотра и hover. | | CSS-фоны по URL и несколько слоёв фона | Используйте поддерживаемый градиент или `img` ресурс движка. | | Радиусы по углам и более восьми теней | Используйте поддерживаемые ограничения на один радиус/восемь теней или явные вложенные элементы. | | `min()`, `max()`, и `clamp()` Математические функции CSS | Сочетайте `width`/`height` с поддерживаемыми `min-*` и `max-*` свойствами. | | Вращение, наклон, 3D-преобразования, цепочки фильтров и другие функции фильтров | Подготовьте визуал как ресурс или используйте поддерживаемые эффекты translate/scale/blur/drop-shadow. | | Веб-формы, навигация, fetch, iframe, canvas, SVG DOM, аудио и видео | Используйте CSL и соответствующие системы движка. | | Семантическое поведение браузера и доступность | Элементы UIDoc — это узлы игрового интерфейса; имена HTML-тегов не подразумевают поведение браузера. | UIDoc стремится сделать создание обычного игрового интерфейса простым, а не воспроизводить каждую функцию HTML и CSS. Держите разметку в пределах этого поднабора, чтобы ресурсы выпекались предсказуемо, а клиентская/серверная симуляция интерфейса оставалась детерминированной.