Web'de geç gelen yazı tipi

Compose Multiplatform'un web hedefinde bir uygulamanın kendi yazı tipinin neden bir an geç geldiği, bunu nasıl ölçtüğümüz ve nasıl giderdiğimiz. Sorun Pantrix'e özgü değildir: web hedefi olan ve kendi font dosyasını kullanan her Compose Multiplatform projesinde aynı şekilde görülür.

1. Sorun

Belirti

• Sayfa tarayıcıda ilk açıldığında ya da yenilendiğinde metin önce başka bir yazı tipiyle çizilir. Bir saniyeden kısa bir süre sonra bütün harfler değişir, metinler yeniden yerleşir ve satırlar kayar.

• Uygulama çalışırken yazı tipi değiştirildiğinde (bizde "Ayarlar"daki "Yazı tipi") aynısı bir kez daha olur.

• Android'de, iOS'ta ve masaüstünde hiç görülmez.

Web sayfalarında bunun adı FOUT'tur (flash of unstyled text).

Neden

Compose Multiplatform'da bir font dosyası Font(Res.font.…) ile okunur. Bu fonksiyon platforma göre iki ayrı şey yapar (Compose Multiplatform 1.12.1, components-resources):

Web'de Font(…), dosya gelene dek bir yedek döndürür: Skiko'nun içinde taşıdığı Roboto (FontResources.skiko.kt, defaultFont). Dosya gelince döndürdüğü değer değişir, onu okuyan her şey yeniden kurulur ve her metin yeniden yerleşir. Üç ayrıntı sorunu büyütür:

1. Okuma geç başlar. Font(…) bir composable'dır: indirme ancak uygulama ilk kez kurulurken, yani Wasm indirilip derlendikten sonra başlar.

2. Her ağırlık ayrı bir fonttur. Önbelleğin anahtarı dosyanın yolu, ağırlığı, stili ve eksen ayarıdır. Yedi ağırlıkta kaydedilen tek bir değişken font yedi kez okunur ve yedi ayrı anda gelebilir: tema birkaç kez baştan kurulur.

3. Her yüklemede yeniden istenir. Kaynakların tarayıcıdaki önbelleği (Cache API) her sayfa yüklemesinde sıfırlanır (ResourceWebCache.web.kt); dosyayı tarayıcının kendi HTTP önbelleği verir.

Ölçüm

Üretim paketi (wasmJsBrowserDistribution) yerel bir sunucudan açıldı; zamanlar sayfaya eklenen bir ölçüm betiğiyle okundu (bkz. 6. bölüm). Sayılar sayfa açıldıktan sonraki milisaniyelerdir.

Yerelde ağ gecikmesi yoktur ve fark yüz milisaniyedir; gerçek bir ağda yazı tipi geç geldiği kadar uzun sürer. İlk karenin kendisi iki ölçümde de 175 ile 240 ms arasında sürdü: yazı tipini beklemek açılışı geciktirmedi, çünkü dosyalar o kare kurulmadan çok önce inmişti.

2. Çözüm: dört parça

İkinci parça işin özüdür ve Compose'un bir özelliğine dayanır: okunan font bellekte kalır ve onu sonradan isteyen ilk kurulumda hemen bulur. Yani yazı tipini önce bir yerde sorup (preloadFont) uygulamayı ondan sonra kurmak yeter; uygulamanın kendisinde hiçbir şey değişmez.

3. Pantrix ile

Kütüphane dört parçanın Kotlin tarafını verir (com.pantrixui.foundation.token.typography):

Android'de, iOS'ta ve masaüstünde hepsi hemen cevap verir: aynı kod her platformda yazılır, yalnızca web'de bekler.

3.1. Yazı tipini bir kez söyle

// commonMain
val Brand = PantrixTypeface(
    PantrixFont(Res.font.brand_regular),
    PantrixFont(Res.font.brand_medium, FontWeight.Medium),
    PantrixFont(Res.font.brand_bold, FontWeight.Bold)
)

@Composable
fun App() {
    PantrixTheme(typography = rememberPantrixTypography(Brand)) {
        // …
    }
}

Fontlar tek bir yerde sayılır; aile de, tarayıcıda okunup okunmadıkları da o listeden sorulur. İkisi ayrı yerlerde sayılırsa bir gün birbirini tutmaz (bkz. 5. bölüm, "Aynı anahtar").

Yalnızca kütüphanenin kendi yazı tipini kullanan bir uygulamanın bir şey söylemesi gerekmez: PantrixTheme { … } yeter.

3.2. Web girişi

// webMain
@OptIn(ExperimentalComposeUiApi::class)
fun main() {
    // Kutusu olmayan bir sayfada (tarayıcının sakladığı eski bir index.html) gövdeye kurulur.
    val box = "app".takeIf { document.getElementById(it) != null }
    ComposeViewport(viewportContainerId = box) {
        PantrixTypefaceGate(
            loaded = areTypefacesLoaded(Brand),
            onShown = { document.getElementById("loading")?.remove() }
        ) {
            App()
        }
    }
}

Kütüphanenin kendi yazı tipi için loaded verilmez: PantrixTypefaceGate(onShown = …) { App() }.

3.3. Sayfa

<head>
    <!-- Yazı tipi, uygulamanın kodu inerken indirilir. `crossorigin` olmadan tarayıcı bu indirmeyi
         uygulamanın kendi isteğine saymaz ve dosya iki kez iner. -->
    <link rel="preload" as="fetch" type="font/ttf" crossorigin
          href="composeResources/<paket>.generated.resources/font/brand_regular.ttf">
</head>
<body>
    <!-- Yükleme işareti: uygulamanın ilk karesi çizilene dek üstünde durur. -->
    <div id="loading">…</div>
    <!-- Uygulamanın kurulduğu kutu. -->
    <div id="app"></div>
    <script type="application/javascript" src="webApp.js"></script>
</body>

html, body { width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden; }

#app { width: 100%; height: 100%; }

#loading {
    position: fixed;
    inset: 0;
    z-index: 1;
    display: flex;
    align-items: center;
    justify-content: center;
    pointer-events: none;
}

Adresteki <paket>, kaynakları taşıyan modülün üretilen Res sınıfının paketidir. Kütüphanenin kendi yazı tipinin adresi composeResources/com.pantrixui.foundation.generated.resources/font/plus_jakarta_sans.ttf'dir. Emin olmak için paketi bir kez derleyip build/dist/…/composeResources klasörüne bakın.

3.4. Çalışırken değişen yazı tipi

rememberPantrixTypography(typeface) bunu kendisi çözer: typeface değiştiğinde, yenisi okunana dek eski tipografiyi vermeyi sürdürür ve yenisini bir kez, tamamı geldiğinde verir.

val typeface = if (settings.brand) Brand else PantrixTypeface.Default
PantrixTheme(typography = rememberPantrixTypography(typeface)) { /* … */ }

Seçim ile değişim arasında dosyaların inmesi kadar bir süre geçer. O da istenmiyorsa yazı tipleri önden okunur: kapıya hepsi birlikte verilir ve sayfa hepsini önden indirir. Bu depodaki örnek uygulama öyle yapar, çünkü üç yazı tipini yan yana gösteren bir sayfası vardır:

PantrixTypefaceGate(loaded = areTypefacesLoaded(PantrixTypeface.Default, PlusJakartaSans, Poppins)) { App() }

Bedeli indirilen bayttır: örnek uygulamada on beş dosya, 2,0 MB. Bir ürün için doğru olan çoğunlukla yalnızca ilk ekranın yazı tipini önden okumak, ötekileri değişime bırakmaktır.

4. Pantrix olmadan

Aynı çözüm, yalnızca Compose Multiplatform'un kendi API'siyle. Aşağıdaki kod herhangi bir projeye kopyalanabilir; kütüphanedeki karşılıklarının sadeleştirilmiş hâlidir.

4.1. Ortak kod (commonMain)

/** Bir font: kaynaklardaki dosya ve ailenin onu kaydettiği ağırlık ile stil. */
data class AppFont(
    val resource: FontResource,
    val weight: FontWeight = FontWeight.Normal,
    val style: FontStyle = FontStyle.Normal
)

/** Fontların ailesi. Tarayıcıda henüz gelmemiş bir font, ailede yedek yazı tipidir. */
@Composable
fun rememberFontFamily(fonts: List<AppFont>): FontFamily {
    val read = key(fonts) { fonts.map { Font(it.resource, it.weight, it.style) } }
    return remember(read) { FontFamily(read) }
}

/** Fontların hepsi okundu mu. Sormak okumayı başlatır; web dışında her zaman doğrudur. */
@Composable
expect fun areFontsLoaded(fonts: List<AppFont>): Boolean

/** [value] okunmuşsa kendisi; okunmamışsa en son okunmuş olan. Hiçbiri okunmamışsa yine [value]. */
@Composable
fun <T> lastLoaded(value: T, loaded: Boolean): T {
    var last by remember { mutableStateOf<T?>(null) }
    if (!loaded) return last ?: value
    SideEffect { last = value }
    return value
}

/** [content]'i yazı tipi okunduktan sonra çizer; en çok [timeoutMillis] kadar bekler. */
@Composable
fun FontGate(
    loaded: Boolean,
    timeoutMillis: Long = 3000,
    onShown: () -> Unit = {},
    content: @Composable () -> Unit
) {
    var waiting by remember { mutableStateOf(true) }
    LaunchedEffect(Unit) {
        delay(timeoutMillis)
        waiting = false
    }
    // Bir kez açılan kapı açık kalır: çizilmiş bir uygulama yeniden kurulmaz.
    var opened by remember { mutableStateOf(false) }
    if (opened || loaded || !waiting) {
        SideEffect { opened = true }
        content()
        val shown by rememberUpdatedState(onShown)
        LaunchedEffect(Unit) {
            // İçeriği taşıyan kareden sonraki ilk kare: o kare çizilmiştir.
            withFrameNanos { }
            shown()
        }
    }
}

4.2. Platform karşılıkları

// webMain
@OptIn(ExperimentalResourceApi::class)
@Composable
actual fun areFontsLoaded(fonts: List<AppFont>): Boolean {
    // Önce hepsi istenir, sonra bakılır: fontlar art arda değil, yan yana okunur.
    val read = key(fonts) { fonts.map { preloadFont(it.resource, it.weight, it.style).value } }
    return read.none { it == null }
}

// androidMain, iosMain, jvmMain
@Composable
actual fun areFontsLoaded(fonts: List<AppFont>): Boolean = true

preloadFont yalnızca web kaynak kümelerinde vardır ve @ExperimentalResourceApi taşır; ortak koddan çağrılamaz. expect/actual bu yüzden gerekir. webMain, js ve wasmJs hedeflerinin ikisi de tanımlıysa Kotlin'in kendiliğinden kurduğu kaynak kümesidir.

4.3. Kullanım

// commonMain
val Brand = listOf(
    AppFont(Res.font.brand_regular),
    AppFont(Res.font.brand_bold, FontWeight.Bold)
)

@Composable
fun App() {
    val family = rememberFontFamily(Brand)
    // Çalışırken değişen bir yazı tipi için: yenisi okunana dek eskisinde kalır.
    val shown = lastLoaded(family, loaded = areFontsLoaded(Brand))
    // typographyIn: tipografinizi verilen aileyle kuran kendi fonksiyonunuz.
    MaterialTheme(typography = typographyIn(shown)) { /* … */ }
}

// webMain
@OptIn(ExperimentalComposeUiApi::class)
fun main() {
    val box = "app".takeIf { document.getElementById(it) != null }
    ComposeViewport(viewportContainerId = box) {
        FontGate(
            loaded = areFontsLoaded(Brand),
            onShown = { document.getElementById("loading")?.remove() }
        ) {
            App()
        }
    }
}

Sayfa ve stil 3.3'tekilerle aynıdır.

5. Tuzaklar

6. Doğrulama

Ölçüm betiği

Tarayıcıda bir karenin tam olarak ne zaman çizildiği dışarıdan görülmez; olayların sırası görülür. Üretim paketinin bir kopyasına, index.html'de uygulamanın betiğinden önce yüklenen küçük bir betik eklenir:

(function () {
  const log = (m) => console.log('[font-probe] ' + Math.round(performance.now()) + 'ms ' + m);
  const isFont = (s) => s.indexOf('/font/') >= 0;
  const origFetch = window.fetch;
  window.fetch = function (u) {
    const s = String((u && u.url) || u);
    if (isFont(s)) log('fetch ' + s.split('/').pop());
    return origFetch.apply(this, arguments);
  };
  // Bir kareden uzun süren kareler: baştan kurulan bir sayfa burada görünür.
  let last = performance.now();
  const tick = (now) => {
    if (now - last > 24) log('long frame ' + Math.round(now - last) + 'ms');
    last = now;
    if (now < 6000) requestAnimationFrame(tick);
  };
  requestAnimationFrame(tick);
})();

Beklenen sıra: fontlar uygulamanın ilk uzun karesinden önce okunmuştur, ve o kareden sonra font için yeni bir istek görülmez. performance.getEntriesByType('resource') dosyayı kimin istediğini söyler: ön yükleme çalışıyorsa initiatorType "link"tir ve dosya bir kez iner.

Testler

7. Bu depoda nerede

8. Açık kalanlar

Bu işte görülen ve dokunulmayan maddeler docs/OPEN_ITEMS.md'dedir. Başlıcaları:

• Kütüphanenin yazı tipi tek dosyadır ama tarayıcıda yedi kez okunur; yazı tipini beklemeyen bir uygulamada ağırlıklar ayrı ayrı gelir.

• preloadFont deneyseldir (@ExperimentalResourceApi); Compose Multiplatform'un sonraki bir sürümünde değişebilir.

• Yalnızca yerleşik tarayıcıda ve Wasm hedefinde görüldü; gerçek tarayıcılarda ve yavaş bir ağda bakılmadı.

• Yükleme işareti Wasm derlenirken takılır ve koyu temalı bir cihazda da beyaz zeminde açılır.