Compose Multiplatform 中 FontVariation 在 Web 平台的字体渲染问题解析

问题现象

在 Compose Multiplatform 项目中，开发者使用 FontVariation 时发现了一个平台相关的渲染差异：在 WasmJS/JS 平台（Web 端）上，字体的默认权重会异常变为最细（thin）状态，而同样的代码在 Desktop JVM 平台则表现正常。此外，Web 端首次加载字体时会出现短暂的"方块"占位现象，之后才能正确显示调整后的字体样式。

技术背景

FontVariation 是 Compose 中用于支持可变字体（Variable Fonts）的 API。可变字体是 OpenType 1.8 引入的特性，允许通过轴（Axis）参数动态调整字体的多个视觉属性（如字重、宽度、斜度等），而无需加载多个字体文件。

在跨平台场景下，由于各平台对字体渲染的实现差异，特别是 Web 平台基于浏览器引擎的字体处理机制与桌面端存在显著不同，容易导致此类平台特异性问题。

问题分析

1. 默认字重异常问题

根本原因在于 Web 平台的字体加载机制：

• Web 字体通常需要异步加载，在 CSS 中未显式指定 font-weight 时，浏览器可能使用默认值（通常为 400/normal）
• Compose 的 Wasm/JS 实现可能在字体加载完成前就应用了样式，导致初始状态异常
• 开发者确认其代码中存在未正确初始化字重参数的情况，这在不同平台表现出不同行为

2. 首次加载的方块现象

这是典型的 FOUT（Flash of Unstyled Text）问题：

• 浏览器在下载可变字体文件前，会先用系统默认字体渲染
• 当指定的可变字体参数（如特定字重）在备用字体中不存在时，就会出现样式不匹配
• 字体下载完成后触发的重排（reflow）导致短暂显示异常

解决方案

对于默认字重问题

1. 显式初始化字体参数：

FontVariation(
    settings = fontSettings,
    // 明确设置初始字重
    weight = FontWeight.Normal
)

2. 实现平台特定的字体加载回调：

expect fun registerFontLoadCallback(listener: () -> Unit)

// 在Web端实现
actual fun registerFontLoadCallback(listener: () -> Unit) {
    js("document.fonts.ready.then(() => listener())")
}

对于FOUT问题

1. 使用字体加载优化策略：

/* 在资源中预加载字体 */
@font-face {
    font-family: 'MyVariableFont';
    src: url('font.woff2') format('woff2-variations');
    font-display: optional; /* 或 swap */
}

2. 添加加载状态UI：

var isFontReady by remember { mutableStateOf(false) }

LaunchedEffect(Unit) {
    registerFontLoadCallback { isFontReady = true }
}

if (isFontReady) {
    Text("正常显示内容")
} else {
    CircularProgressIndicator()
}

最佳实践建议

1. 跨平台字体处理原则：

• 始终显式设置字体相关属性（字重、样式等）
• 为可变字体设置合理的默认值和有效范围
• 针对Web平台实现字体加载状态检测

2. 性能优化方向：

• 使用 woff2 格式的字体文件，支持更好的压缩和变体
• 考虑使用 fonttools 等工具对可变字体进行子集化处理
• 实现渐进式字体加载策略

3. 调试技巧：

• 使用 Chrome DevTools 的 Font 面板检查加载状态
• 通过 document.fonts API 直接检查字体加载情况
• 在 Compose 中设置调试边界观察布局过程

总结

Compose Multiplatform 的跨平台特性虽然强大，但在涉及平台深度集成的功能（如字体渲染）时仍需注意实现差异。通过理解浏览器字体渲染机制、合理设置初始状态、实现加载状态管理，可以确保可变字体在各平台获得一致的展示效果。未来随着 Compose Web 功能的不断完善，这类平台差异问题有望得到进一步简化。