本頁面說明如何在 Compose 應用程式中設定字型。
設定字型
Text
有 fontFamily
參數,可設定在組件中使用的字型。系統預設包含 Serif、Sans Serif、等寬和草寫字型系列:
@Composable fun DifferentFonts() { Column { Text("Hello World", fontFamily = FontFamily.Serif) Text("Hello World", fontFamily = FontFamily.SansSerif) } }
您可以使用 fontFamily
屬性搭配 res/font
資料夾中定義的自訂字型和字體:
以下範例說明如何根據這些字型檔案以及使用 Font
函式定義 fontFamily
:
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) )
您可以將此 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) }
如要瞭解如何在整個應用程式中設定字體排版,請參閱「Compose 中的自訂設計系統」。
可下載的字型
從 Compose 1.2.0 開始,您可以使用 Compose 應用程式中的可下載字型 API,以非同步方式下載 Google 字型,然後在應用程式中使用。
目前不支援自訂提供者提供的可下載字型。
透過程式輔助方式使用可下載字型
如要透過程式輔助方式下載字型,請按照下列步驟操作:
- 新增依附元件:
Groovy
dependencies { ... implementation "androidx.compose.ui:ui-text-google-fonts:1.6.1" }
Kotlin
dependencies { ... implementation("androidx.compose.ui:ui-text-google-fonts:1.6.1") }
- 使用 Google Fonts 的憑證初始化
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 )
供應器收到的參數包括:- Google Fonts 的字型提供者授權。
- 用於驗證供應者身分的字型供應者套件。
- 憑證的雜湊組合,用於驗證供應者的身分。您可以在 Jetchat 範例應用程式的
font_certs.xml
檔案中找到 Google Fonts 供應者所需的雜湊。
- 定義
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) )
您可以個別使用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 ) )
- 設定要在文字可組合函式中使用的
FontFamily
:
Text( fontFamily = fontFamily, text = "Hello World!" )
您也可以定義字體排版,以便使用 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/*...*/ ), /*...*/ )
接下來,請將字型設為應用程式的主題:
MyAppTheme( typography = MyTypography )/*...*/
如需在 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) )
您可以同時定義兩種粗細的字型預設值,如下所示:
// ... 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) )
確認您新增的是正確的匯入項目。
定義這種 FontFamily
會建立一個 FontFamily
,其中包含兩個鏈結,每種粗細一個。載入機制會嘗試先解析線上字型,然後再處理本機 R.font
資源資料夾中的字型。
偵錯實作
為協助您確認字型下載是否正確,您可以定義偵錯協同程式處理常式。您的控點可提供字型無法以非同步方式載入時的處理方式。
首先,請建立 CoroutineExceptionHandler
:
val handler = CoroutineExceptionHandler { _, throwable -> // process the Throwable Log.e(TAG, "There has been an issue: ", throwable) }
將處理常式傳遞至 createFontFamilyResolver
方法,讓解析器使用新的處理常式:
CompositionLocalProvider( LocalFontFamilyResolver provides createFontFamilyResolver(LocalContext.current, handler) ) { Column { Text( text = "Hello World!", style = MaterialTheme.typography.bodyMedium ) } }
您也可以使用提供者的 isAvailableOnDevice
API 來測試提供者是否可用,以及憑證設定是否正確無誤。若要執行此操作,您可以呼叫 isAvailableOnDevice
方法,若提供者設定錯誤,則會傳回 false。
val context = LocalContext.current LaunchedEffect(Unit) { if (provider.isAvailableOnDevice(context)) { Log.d(TAG, "Success!") } }
注意事項
Google Fonts 需要數個月的時間才能在 Android 上提供新字型。從 fonts.google.com 新增字型到可透過可下載的字型 API (在 View 系統或 Compose 中) 取得後會有間隔一段時間。使用 IllegalStateException
載入的新字型可能無法在應用程式中載入。為了協助開發人員判斷該錯誤,並與其他類型的字型載入錯誤進行比較,我們已針對 Compose 的例外狀況新增描述性訊息。如果發現任何問題,請使用 Issue Tracker 回報問題。
使用可變字型
可變字型是一種字型格式,可讓一個字型檔案包含不同樣式。使用可變字型時,您可以修改軸 (或參數) 以產生偏好的樣式。這些軸可以是標準軸 (例如粗細、寬度、斜體和斜體),也可能是自訂 (因可變的字型而異)。
使用可變字型而非一般字型檔案時,您只能使用一個字型檔案,而非多個字型檔案。
如要進一步瞭解變數字型,請參閱「Google Fonts 知識」、「可用變數字型」完整目錄,以及每個字型支援的軸表格。
本文件說明如何在 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), ) ) )
FontVariation
API 可讓您設定標準字型軸,例如「weight」、「width」和「sslant」。這些標準軸適用於所有可變字型。您可以根據使用字型的位置,建立不同的字型設定。可變字型僅適用於 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 }
將設定擷取至一組常數,以便重複使用,並以這些常數取代字型設定:
// 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 }
設定 Material Design 3 字體排版以使用
FontFamily
:// Type.kt val Typography = Typography( displayLarge = TextStyle( fontFamily = displayLargeFontFamily, fontSize = 50.sp, lineHeight = 64.sp, letterSpacing = 0.sp, /***/ ) )
此範例使用
displayLarge
Material 3 字體排版,其預設字型設定和建議用途不同。舉例來說,displayLarge
應用於簡短且重要的文字,因為這是畫面上最大的文字。使用 Material 3 時,您可以變更
TextStyle
和fontFamily
的預設值,以自訂字體排版。在上面的程式碼片段中,您將設定TextStyle
的例項,以便為每個字型系列自訂字型設定。定義字體排版後,請將其傳遞至 M3
MaterialTheme
:MaterialTheme( colorScheme = MaterialTheme.colorScheme, typography = Typography, content = content )
最後,使用
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 ) } } } }
每個
Text
可組合項都是透過 Material 主題的樣式進行設定,且包含不同的變數字型設定。您可以使用MaterialTheme.typography
擷取提供給 M3MaterialTheme
可組合項的字體排版。
使用自訂軸線
字型也可以有自訂軸。這些定義會在字型檔案本身中定義。舉例來說,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()) }
這些函式會執行以下作業:
- 為這些可以接受的值定義防護機制。如同「Variable 字型目錄」所示,
ascenderHeight (YTAS)
的最小值為649f
,最大值為854f
。 - 傳回字型設定,可將設定新增至字型。在
FontVariation.Setting()
方法中,軸名稱 (YTAS, XTRA
) 採用硬式編碼,且會採用值做為參數。
- 為這些可以接受的值定義防護機制。如同「Variable 字型目錄」所示,
使用含有字型設定的軸,將其他參數傳遞至每個載入的
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 }
請注意,小寫遞增器的高度已增加,其他文字則較寬:
其他資源
詳情請參閱下列有關可變字型的網誌文章:
為您推薦
- 注意:系統會在 JavaScript 關閉時顯示連結文字
- Compose 中的資源
- 設定文字樣式
- Compose 中的質感設計 2