使用字体

本页面介绍如何在 Compose 应用中设置字体。

设置字体

Text 具有 fontFamily 参数，允许设置可组合项中使用的字体。默认情况下，衬线、无衬线、等宽和草书字体系列已包含

@Composable
fun DifferentFonts() {
    Column {
        Text("Hello World", fontFamily = FontFamily.Serif)
        Text("Hello World", fontFamily = FontFamily.SansSerif)
    }
}TextSnippets.kt

The words

您可以使用 fontFamily 属性来处理在 res/font 文件夹中定义的自定义字体和字体。

Graphical depiction of the res > font folder in the development environment

此示例显示了如何根据这些字体文件定义 fontFamily，并使用 Font 函数

val firaSansFamily = FontFamily(
    Font(R.font.firasans_light, FontWeight.Light),
    Font(R.font.firasans_regular, FontWeight.Normal),
    Font(R.font.firasans_italic, FontWeight.Normal, FontStyle.Italic),
    Font(R.font.firasans_medium, FontWeight.Medium),
    Font(R.font.firasans_bold, FontWeight.Bold)
)TextSnippets.kt

您可以将此 fontFamily 传递给您的 Text 可组合项。因为 fontFamily 可以包含不同的粗细，所以您可以手动设置 fontWeight 来选择文本的正确粗细。

Column {
    Text(text = "text", fontFamily = firaSansFamily, fontWeight = FontWeight.Light)
    Text(text = "text", fontFamily = firaSansFamily, fontWeight = FontWeight.Normal)
    Text(
        text = "text",
        fontFamily = firaSansFamily,
        fontWeight = FontWeight.Normal,
        fontStyle = FontStyle.Italic
    )
    Text(text = "text", fontFamily = firaSansFamily, fontWeight = FontWeight.Medium)
    Text(text = "text", fontFamily = firaSansFamily, fontWeight = FontWeight.Bold)
}TextSnippets.kt

The words

要了解如何在整个应用中设置排版，请参阅Compose 中的自定义设计系统。

可下载字体

从Compose 1.2.0开始，您可以在 Compose 应用中使用可下载字体 API 异步下载Google 字体并在应用中使用它们。

目前尚不支持自定义提供程序提供的可下载字体。

以编程方式使用可下载字体

要在应用中以编程方式下载字体，请按照以下步骤操作

添加依赖项

Groovy

dependencies {
    ...
    implementation "androidx.compose.ui:ui-text-google-fonts:1.7.0"
}

Kotlin

dependencies {
    ...
    implementation("androidx.compose.ui:ui-text-google-fonts:1.7.0")
}

使用 Google 字体的凭据初始化GoogleFont.Provider
```
val provider = GoogleFont.Provider(
    providerAuthority = "com.google.android.gms.fonts",
    providerPackage = "com.google.android.gms",
    certificates = R.array.com_google_android_gms_fonts_certs
)TextDownloadableFontsSnippets.kt
```
提供程序接收的参数为
- Google 字体的字体提供程序权限。
- 字体提供程序包，用于验证提供程序的身份。
- 用于验证提供程序身份的证书散列集列表。您可以在 Jetchat 示例应用的font_certs.xml 文件中找到 Google 字体提供程序所需的散列。

定义一个FontFamily

// ...
 import androidx.compose.ui.text.googlefonts.GoogleFont
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.googlefonts.Font
 // ...

val fontName = GoogleFont("Lobster Two")

val fontFamily = FontFamily(
    Font(googleFont = fontName, fontProvider = provider)
)TextDownloadableFontsSnippets.kt

您可以分别使用FontWeight和FontStyle查询字体的其他参数，例如粗细和样式。

// ...
 import androidx.compose.ui.text.googlefonts.GoogleFont
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.googlefonts.Font
 // ...

val fontName = GoogleFont("Lobster Two")

val fontFamily = FontFamily(
    Font(
        googleFont = fontName,
        fontProvider = provider,
        weight = FontWeight.Bold,
        style = FontStyle.Italic
    )
)TextDownloadableFontsSnippets.kt

配置要在 Text 可组合函数中使用的 FontFamily

Text(
    fontFamily = fontFamily, text = "Hello World!"
)TextDownloadableFontsSnippets.kt

您还可以定义Typography以使用您的 FontFamily

val MyTypography = Typography(
    labelMedium = TextStyle(
        fontFamily = fontFamily, fontWeight = FontWeight.Normal, fontSize = 12.sp/*...*/
    ),
    labelLarge = TextStyle(
        fontFamily = fontFamily,
        fontWeight = FontWeight.Bold,
        letterSpacing = 2.sp,
        /*...*/
    ),
    displayMedium = TextStyle(
        fontFamily = fontFamily, fontWeight = FontWeight.SemiBold/*...*/
    ),
    /*...*/
)TextDownloadableFontsSnippets.kt

接下来，将排版设置为应用的主题

MyAppTheme(
    typography = MyTypography
)/*...*/TextDownloadableFontsSnippets.kt

有关同时在 Compose 中实现可下载字体和Material3的应用示例，请参阅Jetchat示例应用。

添加备用字体

如果字体下载失败，您可以确定字体的一系列回退。例如，如果您这样定义可下载字体

// ...
 import androidx.compose.ui.text.googlefonts.Font
 // ...

val fontName = GoogleFont("Lobster Two")

val fontFamily = FontFamily(
    Font(googleFont = fontName, fontProvider = provider),
    Font(googleFont = fontName, fontProvider = provider, weight = FontWeight.Bold)
)TextDownloadableFontsSnippets.kt

您可以像这样定义字体的默认粗细：

// ...
 import androidx.compose.ui.text.font.Font
 import androidx.compose.ui.text.googlefonts.Font
 // ...

val fontName = GoogleFont("Lobster Two")

val fontFamily = FontFamily(
    Font(googleFont = fontName, fontProvider = provider),
    Font(resId = R.font.my_font_regular),
    Font(googleFont = fontName, fontProvider = provider, weight = FontWeight.Bold),
    Font(resId = R.font.my_font_regular_bold, weight = FontWeight.Bold)
)TextDownloadableFontsSnippets.kt

确保您添加了正确的导入。

这样定义 FontFamily 会创建一个包含两个链的 FontFamily，每个粗细一个。加载机制将首先尝试解析在线字体，然后解析位于本地 R.font 资源文件夹中的字体。

调试您的实现

为了帮助您验证字体是否已正确下载，您可以定义一个调试协程处理程序。您的处理程序提供字体异步加载失败时要执行的操作的行为。

首先创建一个CoroutineExceptionHandler

val handler = CoroutineExceptionHandler { _, throwable ->
    // process the Throwable
    Log.e(TAG, "There has been an issue: ", throwable)
}TextDownloadableFontsSnippets.kt

将其传递给createFontFamilyResolver方法，使解析器使用新的处理程序。

CompositionLocalProvider(
    LocalFontFamilyResolver provides createFontFamilyResolver(LocalContext.current, handler)
) {
    Column {
        Text(
            text = "Hello World!", style = MaterialTheme.typography.bodyMedium
        )
    }
}TextDownloadableFontsSnippets.kt

您还可以使用提供程序的isAvailableOnDevice API 测试提供程序是否可用以及证书是否配置正确。为此，您可以调用返回 false 的 isAvailableOnDevice 方法（如果提供程序配置不正确）。

val context = LocalContext.current
LaunchedEffect(Unit) {
    if (provider.isAvailableOnDevice(context)) {
        Log.d(TAG, "Success!")
    }
}TextDownloadableFontsSnippets.kt

注意事项

Google 字体需要几个月的时间才能在 Android 上提供新字体。在字体添加到fonts.google.com和通过可下载字体 API（在 View 系统或 Compose 中）可用之间存在时间差。新添加的字体可能无法在您的应用中加载，并出现IllegalStateException。为了帮助开发者将此错误与其他类型的字体加载错误区分开来，我们在 Compose 中通过此处所做的更改添加了异常的描述性消息。如果您发现任何问题，请使用问题跟踪器报告。

使用可变字体

可变字体是一种字体格式，允许一个字体文件包含不同的样式。使用可变字体，您可以修改轴（或参数）以生成您首选的样式。这些轴可以是标准的，例如粗细、宽度、倾斜和斜体，也可以是自定义的，它们在不同的可变字体之间有所不同。

Five configurations of the same variable font with different axis values. — **图 1.** 使用相同可变字体，并使用不同的轴值进行自定义的文本。

使用可变字体而不是常规字体文件，可以让您只使用一个字体文件，而不是多个字体文件。

有关可变字体的更多背景信息，请参阅Google 字体知识、可用可变字体的完整目录以及每种字体的支持轴的表格。

本文档向您展示如何在 Compose 应用中实现可变字体。

加载可变字体

下载您要使用的可变字体（例如Roboto Flex），并将其放置在应用的 app/res/font 文件夹中。确保您添加的 .ttf 文件是字体的可变字体版本，并且字体文件名全部小写，不包含任何特殊字符。

注意：目前不支持通过可下载字体使用可变字体。请参阅此错误中的最新更新。

要加载可变字体，请使用放置在 res/font/ 目录中的字体定义 FontFamily

// In Typography.kt
@OptIn(ExperimentalTextApi::class)
val displayLargeFontFamily =
    FontFamily(
        Font(
            R.font.robotoflex_variable,
            variationSettings = FontVariation.Settings(
                FontVariation.weight(950),
                FontVariation.width(30f),
                FontVariation.slant(-6f),
            )
        )
    )VariableFontsSnippets.kt

FontVariation API 允许您配置标准字体轴，例如粗细、宽度和倾斜。这些是任何可变字体都可用的标准轴。您可以根据字体的使用位置创建不同的字体配置。

可变字体仅适用于 Android O 及更高版本，因此请添加防护栏并配置适当的回退。

// In Typography.kt
val default = FontFamily(
    /*
    * This can be any font that makes sense
    */
    Font(
        R.font.robotoflex_static_regular
    )
)
@OptIn(ExperimentalTextApi::class)
val displayLargeFontFamily = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    FontFamily(
        Font(
            R.font.robotoflex_variable,
            variationSettings = FontVariation.Settings(
                FontVariation.weight(950),
                FontVariation.width(30f),
                FontVariation.slant(-6f),
            )
        )
    )
} else {
    default
}VariableFontsSnippets.kt

将设置提取到一组常量中，以便于重用，并用这些常量替换字体设置。

// VariableFontDimension.kt
object DisplayLargeVFConfig {
    const val WEIGHT = 950
    const val WIDTH = 30f
    const val SLANT = -6f
    const val ASCENDER_HEIGHT = 800f
    const val COUNTER_WIDTH = 500
}

@OptIn(ExperimentalTextApi::class)
val displayLargeFontFamily = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    FontFamily(
        Font(
            R.font.robotoflex_variable,
            variationSettings = FontVariation.Settings(
                FontVariation.weight(DisplayLargeVFConfig.WEIGHT),
                FontVariation.width(DisplayLargeVFConfig.WIDTH),
                FontVariation.slant(DisplayLargeVFConfig.SLANT),
            )
        )
    )
} else {
    default
}VariableFontsSnippets.kt

配置 Material Design 3排版以使用 FontFamily
```
// Type.kt
val Typography = Typography(
    displayLarge = TextStyle(
        fontFamily = displayLargeFontFamily,
        fontSize = 50.sp,
        lineHeight = 64.sp,
        letterSpacing = 0.sp,
        /***/
    )
)VariableFontsSnippets.kt
```
此示例使用 displayLargeMaterial 3 排版，它具有不同的默认字体设置和推荐用法。例如，您应该将 displayLarge 用于简短的关键文本，因为它是在屏幕上最大的文本。

使用 Material 3，您可以更改 TextStyle 和 fontFamily 的默认值以自定义您的排版。在上面的代码片段中，您配置 TextStyle 的实例以自定义每个字体系列的字体设置。

现在您已定义了排版，将其传递给 M3 MaterialTheme

MaterialTheme(
    colorScheme = MaterialTheme.colorScheme,
    typography = Typography,
    content = content
)VariableFontsSnippets.kt

最后，使用 Text 可组合项并将样式指定为已定义的排版样式之一，MaterialTheme.typography.displayLarge

@Composable
@Preview
fun CardDetails() {
    MyCustomTheme {
        Card(
            shape = RoundedCornerShape(8.dp),
            elevation = CardDefaults.cardElevation(defaultElevation = 4.dp),
            modifier = Modifier
                .fillMaxWidth()
                .padding(16.dp)
        ) {
            Column(
                modifier = Modifier.padding(16.dp)
            ) {
                Text(
                    text = "Compose",
                    style = MaterialTheme.typography.displayLarge,
                    modifier = Modifier.padding(bottom = 8.dp),
                    maxLines = 1
                )
                Text(
                    text = "Beautiful UIs on Android",
                    style = MaterialTheme.typography.headlineMedium,
                    modifier = Modifier.padding(bottom = 8.dp),
                    maxLines = 2
                )
                Text(
                    text = "Jetpack Compose is Android’s recommended modern toolkit for building native UI. It simplifies and accelerates UI development on Android. Quickly bring your app to life with less code, powerful tools, and intuitive Kotlin APIs.",
                    style = MaterialTheme.typography.bodyLarge,
                    modifier = Modifier.padding(bottom = 8.dp),
                    maxLines = 3
                )
            }
        }
    }
}VariableFontsSnippets.kt

每个 Text 可组合项都通过其 Material 主题的样式进行配置，并包含不同的可变字体配置。您可以使用 MaterialTheme.typography 检索提供给 M3 MaterialTheme 可组合项的排版。

Three different texts, all showcasing different font configurations. — **图 2.** 在三种不同配置中应用的可变字体。

使用自定义轴

字体也可以具有自定义轴。这些在字体文件本身中定义。例如，Roboto Flex 字体具有上标高度（"YTAS"）轴，它调整小写上标的高度，而计数器宽度（"XTRA"）调整每个字母的宽度。

您可以使用 FontVariation 设置更改这些轴的值。

有关您可以为字体配置的自定义轴的更多信息，请参阅每种字体的支持轴的表格。

要使用自定义轴，请为自定义 ascenderHeight 和 counterWidth 轴定义函数。

fun ascenderHeight(ascenderHeight: Float): FontVariation.Setting {
    require(ascenderHeight in 649f..854f) { "'Ascender Height' must be in 649f..854f" }
    return FontVariation.Setting("YTAS", ascenderHeight)
}

fun counterWidth(counterWidth: Int): FontVariation.Setting {
    require(counterWidth in 323..603) { "'Counter width' must be in 323..603" }
    return FontVariation.Setting("XTRA", counterWidth.toFloat())
}VariableFontsSnippets.kt

这些函数执行以下操作

定义它们可以接受的值的防护栏。如您在可变字体目录中所见，ascenderHeight (YTAS) 的最小值为 649f，最大值为 854f。
返回字体设置，以便配置准备好添加到字体中。在 FontVariation.Setting() 方法中，轴名称（YTAS, XTRA）是硬编码的，它将值作为参数。

使用带有字体配置的轴，将其他参数传递给加载的每个 Font

@OptIn(ExperimentalTextApi::class)
val displayLargeFontFamily = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    FontFamily(
        Font(
            R.font.robotoflex_variable,
            variationSettings = FontVariation.Settings(
                FontVariation.weight(DisplayLargeVFConfig.WEIGHT),
                FontVariation.width(DisplayLargeVFConfig.WIDTH),
                FontVariation.slant(DisplayLargeVFConfig.SLANT),
                ascenderHeight(DisplayLargeVFConfig.ASCENDER_HEIGHT),
                counterWidth(DisplayLargeVFConfig.COUNTER_WIDTH)
            )
        )
    )
} else {
    default
}VariableFontsSnippets.kt

请注意，小写上标的高度现在已增加，其他文本也更宽。

Three different texts showing different configurations for variable fonts, with custom axes set— some have higher lowercase ascenders and are wider than before. — **图 3.** 显示在可变字体上设置的自定义轴的文本。

其他资源

有关更多信息，请参阅以下有关可变字体的博文

您的字体：Compose 中的可变字体

为您推荐

注意：当 JavaScript 关闭时显示链接文本。
Compose 中的资源
设置文本样式
Compose 中的 Material Design 2