> 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 Функции 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, неподдерживаемые media-запросы и неподдерживаемые атрибуты привязки являются ошибками компиляции. Парсер может продолжить сбор диагностики, но ресурс считается недействительным, пока ошибки не исправлены. Неподдерживаемые @-правила CSS-блоков пропускаются молча; не полагайтесь на поведение browser @-правил. Для отладки во время выполнения, `uidoc_runtime_inspect` сообщает каждый отрисованный документ как дерево размещённых узлов с разрешённым текстом, экран `прямоугольник`, обработчиком клика и ключом, ключами строк для списков, отправленными привязками и проблемами, которые время выполнения может доказать (непривязанным `data-if`, списком, который никогда не был отправлен); ветви, скрытые `data-if` или `display:none` сворачиваются в одну запись. Пока Start Game запущен, его область по умолчанию — активный клиент; без запущенного клиента укажите `scope: "editor"` явно, чтобы проверить среду выполнения редактора. Каждый ответ среды выполнения указывает свой `realm`, поэтому результат из realm редактора не описывает клиент. Его `прямоугольник`, `client_ui_tree`, и `client_input` `click_at` все используют координаты области просмотра движка с началом в левом нижнем углу; пиксели скриншота используют начало в левом верхнем углу. Инструмент `compile` предварительно проверяет каждый текущий `.uidoc` каталог исходников под `res` перед компиляцией скриптов или разрешением запуска Start Game. Сбой предварительной проверки сообщает `этап`, `файл`, `строка`, и `столбец`, а также полную структурированную диагностику. `uidoc_diagnostics` сообщает результаты авторинга из текущих файлов проекта в realm редактора; предупреждения по отдельным узлам включают `index.html` `строка` и `элемент` селектор. Для сведений о живом DOM используйте отдельный `uidoc_runtime_inspect` инструмент. С `viewportMatrix: true`, каждый ресурс сообщает `viewport_matrix.entries` (случаи профиля/масштаба); `ошибки`, `предупреждение`, и сгруппированные `проблемы` появляются только когда что-то найдено. Он проверяет только объявления, а не обрезку, наложение или границы вне экрана. Ресурсы без диагностики перечисляются вместе под `чистые`. Только ошибки делают профиль неуспешным; предупреждения остаются лишь рекомендациями. Подробный вывод помещает профили с ошибками в `failing_entries` warning\_entries `.`Сжатые группы проблем сообщают только `profiles_affected`; установите `viewportMatrixVerbose: true` когда полезны именованные записи области просмотра/масштаба. Различные исходные узлы не объединяются даже если они делят селектор или строку исходника CSS, поэтому проблема с общим правилом всё равно может появиться как несколько групп; исправьте правило один раз и запустите диагностику снова. Два распространённых предупреждения авторинга требуют контекста: * `dynamic_text_intrinsic_layout` означает, что часто меняющийся текст может изменить внутренне размеряемый блок и сделать недействительным кэшированный макет. Добавьте `data-text-reserve` с самым широким ожидаемым локализованным примером или задайте элементу определённую ширину и высоту. Это не ошибка дублированного текста или отрисовки. * `image_aspect_drift` означает, что изображение имеет независимые ширину и высоту с `object-fit: fill`. Используйте `contain`, `cover`или `aspect-ratio` для обычной графики. Линейные `image-fill-direction` заливки исключены. ## 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-style-`, `data-on-`, `data-bind-`, `data-for-`, `data-scroll-`или `data-text-`, а вариант регистра поддерживаемого имени, например `data-style-Color`, — это `unknown_binding_attribute` ошибка компиляции. Другие `data-*` атрибуты создают предупреждение: UIDoc не запускает скрипты и не имеет селекторов атрибутов, поэтому они не влияют ни на что. Нет `data-style-background-color`. Для фона, зависящего от состояния, задайте дочернему элементу слоя фона `background-color: currentColor` и привяжите у этого дочернего элемента `data-style-color`. На самом элементе `data-style-color` также перекрасит его текст. Атрибуты выражений привязки содержат прямые выражения, например `data-for-key="item.id"`, `data-style-opacity="item.opacity"`, и `data-scroll-zoom="zoom"`. Не помещайте эти выражения внутрь `{{...}}`. Mustache-интерполяция ограничена текстом и значениями изображения. `src` значений. `data-if` является уже, чем другие атрибуты привязки, учитывающие списки: он ищет верхнеуровневый boolean и не разрешает повторный псевдоним, такой как `item.visible`. Для неинтерактивного визуального состояния во вложенном повторяющемся поддереве привяжите `item.opacity` или `item.color`. Непрозрачность не отключает проверку попадания, поэтому отфильтровывайте структурные или интерактивные строки при построении списка CSL, а не оставляйте на месте невидимую кнопку. ### Идентичность повторяющихся элементов управления и тесты `data-for-key` определяет `event.key`повторного клика. `значения являются статическими.` Идентичность элемента управления во время выполнения отделена: она начинается со статического `id`(затем HTML `#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`, поэтому результат вроде `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`, затем порядок документа. Объявления, влияющие на макет, внутри правил псевдосостояний взаимодействия являются ошибками компиляции. Наведение на кнопку может безопасно изменить её цвет или непрозрачность, но не должно менять её размер или окружающий макет. Составные селекторы, такие как `.row.upper`, `#panel.open`, и `button.primary` не поддерживаются; вместо этого добавьте отдельный класс. Неподдерживаемые селекторы вызывают ошибки компиляции, включая соседние комбинаторы, селекторы атрибутов, псевдоэлементы, `: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`, и переполнение. * `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` слоёв; тени блока могут быть внутренними. * Один `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`, `scale`, а также `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` соответствует прямоугольной border box элемента. `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`. По умолчанию 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 не включает вращение, skew, 3D-преобразования или значения из нескольких токенов `scale` значения. Значение filter содержит один `blur(...)` или один `drop-shadow(...)`; цепочки фильтров и другие функции фильтра не поддерживаются. Области компоновки filter и backdrop-filter могут вкладываться до четырёх уровней. ## Адаптивные стили и безопасные области Медиа-запросы поддерживаются, но только для этого явного списка допустимых условий: * `(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 в UIDoc также резервирует полосу верхней панели игры. ## Прокрутка и масштабирование `overflow-x` и `overflow-y` независимы, поэтому один viewport может прокручиваться по горизонтали, вертикали или по обеим осям. Двухосевой viewport сдвигается по обеим осям при перетаскивании. Колёсико мыши прокручивает вертикально, когда вертикальная прокрутка включена; viewport только по горизонтали переназначает колесо на горизонтальную прокрутку. Во время выполнения сейчас рисуется ползунок вертикальной полосы прокрутки. Горизонтальный контент всё ещё доступен при перетаскивании, хотя горизонтальный ползунок не рисуется. `data-scroll-zoom="zoomBinding"` добавляет масштабирование содержимого, похожее на браузерное, к интерактивному viewport прокрутки. Оно масштабирует геометрию потомков, текст, изображения, преобразования, hit-testing и пределы прокрутки, пока viewport и его соседи остаются неподвижными. Когда привязка меняется, движок сохраняет просматриваемую область вокруг центра 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 и произвольные свойства image-effect. Этап преобразования поддерживает `hover:`, `focus:`, `active:`, `disabled:`, адаптивные `sm:`/`md:`/`lg:`/`xl:`/`2xl:`, значения в квадратных скобках, такие как `w-[320px]`, и CSS `@apply`. Сброс preflight/base Tailwind не включён. Вывод, который нельзя представить в UIDoc, не проходит сборку ресурса. ## Заметные возможности браузера, которые не поддерживаются | Возможность браузера | Подход UIDoc | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | JavaScript and DOM APIs | Управляйте состоянием с помощью привязок CSL, `data-if`, `data-for`, и коллбэков событий. | | CSS Grid | Используйте flexbox, блочную раскладку или явное позиционирование. | | Переменные CSS и пользовательские свойства | Привязывайте значения из CSL или используйте обычные общие классы. | | Переходы, keyframes и CSS-анимации | Анимируйте привязки CSL, такие как opacity, translation, scale или scroll zoom. | | Псевдоэлементы и продвинутые селекторы | Добавляйте в документ явные элементы и классы. | | Container queries и большинство медиа-функций | Используйте поддерживаемые запросы viewport-width и hover. | | Фоны CSS URL и несколько слоёв фона | Используйте поддерживаемый градиент или `img` ресурс движка. | | Радиусы для каждого угла и более чем восемь теней | Используйте поддерживаемые ограничения: один радиус/восемь теней или явные вложенные элементы. | | `min()`, `max()`, и `clamp()` Математические функции CSS | Сочетайте `width`/`height` с поддерживаемыми `min-*` и `max-*` свойствами. | | Вращение, skew, 3D-преобразования, цепочки фильтров и другие функции фильтра | Подготовьте визуал как ресурс или используйте поддерживаемые эффекты translate/scale/blur/drop-shadow. | | Веб-формы, навигация, fetch, iframes, canvas, SVG DOM, audio и video | Используйте CSL и соответствующие системы движка. | | Семантическое поведение браузера и поведение доступности | Элементы UIDoc — это узлы игрового интерфейса; имена HTML-тегов не подразумевают поведение браузера. | UIDoc стремится упростить создание типового игрового интерфейса, а не воспроизвести каждую возможность HTML и CSS. Держите раскладку в рамках этого подмножества, чтобы ресурсы собирались предсказуемо, а клиент/серверная симуляция UI оставалась детерминированной.