Работа с веб-ресурсами

Здесь вы найдете информацию о предварительной загрузке ресурсов с помощью возможностей браузера и API preload, кэшировании веб-ресурсов и автоматическом резервном шрифте.

Предварительная загрузка ресурсов для веб-целей

Веб-ресурсы, такие как шрифты и изображения, загружаются асинхронно с помощью Fetch API. При первоначальной загрузке или медленном сетевом соединении загрузка ресурсов может вызывать визуальные артефакты, такие как FOUT или отображение заполнителей вместо изображений.

Типичный пример такой проблемы — компонент Text() содержит текст нестандартным шрифтом, но шрифт с нужными глифами еще загружается. В этом случае пользователи могут временно видеть текст шрифтом по умолчанию или даже пустые прямоугольники и вопросительные знаки вместо символов. Аналогично, вместо изображений или графических объектов пользователи могут видеть заполнитель — пустой или черный прямоугольник, пока ресурс не будет полностью загружен.

Чтобы избежать визуальных артефактов, можно использовать встроенные возможности браузера для предварительной загрузки ресурсов, API предварительной загрузки Compose Multiplatform или сочетание обоих способов.

Предварительная загрузка ресурсов с помощью возможностей браузера

В современных браузерах можно предварительно загружать ресурсы с помощью тега <link> с атрибутом rel="preload". Этот атрибут указывает браузеру в первую очередь загружать и кэшировать такие ресурсы, как шрифты и изображения, до запуска приложения, обеспечивая их раннюю доступность.

Например, чтобы включить предварительную загрузку шрифта в браузере:

Соберите веб-дистрибутив приложения:
```
   ./gradlew :shared:wasmJsBrowserDistribution
```
Найдите нужный ресурс в созданном каталоге dist и сохраните путь к нему.
Откройте файл wasmJsMain/resources/index.html и добавьте тег <link> внутрь элемента <head>.
Укажите путь к ресурсу в атрибуте href:

<link rel="preload" href="./composeResources/username.shared.generated.resources/font/FiraMono-Regular.ttf" as="fetch" type="font/ttf" crossorigin/>

Предварительная загрузка ресурсов с помощью API предварительной загрузки Compose Multiplatform

Даже если предварительно загрузить ресурсы в браузере, они кэшируются в виде необработанных байтов, которые еще нужно преобразовать в формат, подходящий для отрисовки, например FontResource и DrawableResource. При первом запросе ресурса приложением преобразование выполняется асинхронно, что может снова привести к мерцанию. Для дальнейшей оптимизации Compose Multiplatform использует собственный внутренний кэш представлений ресурсов более высокого уровня, которые также можно предварительно загрузить.

В Compose Multiplatform 1.8.0 появился экспериментальный API для предварительной загрузки ресурсов шрифтов и изображений в веб-целях: preloadFont(), preloadImageBitmap() и preloadImageVector().

Если при отрисовке встречаются неразрешенные символы, резервный шрифт с недостающими символами загружается автоматически, поэтому специальные символы, например эмодзи, поддерживаются из коробки.

Если вы хотите самостоятельно указать резервный шрифт вместо использования автоматически выбранного, задайте его с помощью метода FontFamily.Resolver.preload(). Веб-цели поддерживают форматы шрифтов TTF, OTF, TTC, variable и WOFF/WOFF2.

В следующем примере показано, как предварительно загрузить векторное изображение:

@OptIn(ExperimentalComposeUiApi::class, ExperimentalResourceApi::class) @Composable fun App() { val icon by preloadImageVector(Res.drawable.heavy_vector_icon) if (icon != null) { MainScreen() } else { Box(modifier = Modifier.fillMaxSize()) { CircularProgressIndicator(modifier = Modifier.align(Alignment.Center)) } } } @Composable fun MainScreen() { // The icon is loaded from the cache Image(painter = painterResource(Res.drawable.heavy_vector_icon), contentDescription = null) }

Автоматический резервный шрифт

По умолчанию символы, отсутствующие в загруженных шрифтах приложения, отображаются в виде глифов-заменителей (□, известных как «тофу»).

Начиная с версии 1.12.0, Compose Multiplatform отслеживает неразрешенные символы при отрисовке и по запросу загружает необходимые подмножества шрифтов Noto. Название Noto — сокращение от «no tofu» («без тофу»): эти шрифты созданы для устранения глифов тофу.

Когда шрифты станут доступны, затронутый текст будет перерисован. Обратите внимание, что во время загрузки тофу может ненадолго появиться.

Для символов CJK (китайского, японского и корейского языков) подходящий вариант шрифта выбирается автоматически на основе языковых настроек браузера.

Кэширование веб-ресурсов

Compose Multiplatform использует Web Cache API для кэширования успешных ответов и предотвращения повторных HTTP-проверок актуальности, которые обычно выполняются механизмом кэширования браузера по умолчанию.

Кэш полностью очищается при каждом запуске приложения и обновлении страницы. Сброс кэша на этом этапе обеспечивает согласованность ресурсов: повторное использование кэша в нескольких сеансах может привести к использованию устаревших или несовместимых ресурсов, что, в свою очередь, способно вызвать сбои приложения или логические несоответствия.

Чтобы предотвратить одновременную повторную загрузку одного и того же ресурса, реализация использует блокировки для отдельных ресурсов. Каждый запрос защищен мьютексом, привязанным к конкретному ресурсу: это позволяет параллельно выполнять запросы разных ресурсов и сериализует дублирующие запросы одного и того же пути. Такая схема сводит к минимуму ненужный сетевой трафик и исключает состояния гонки при заполнении кэша.

Что дальше?

Подробнее о настройке ресурсов и их использовании в приложении.
Узнайте, как управлять средой ресурсов приложения, например темой и языком внутри приложения.

25 августа 2026 г.

© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/multiplatform/compose-web-resources.html