本頁面說明如何在 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
資料夾中定義的:
本範例說明如何根據這些字型定義 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) )
您可以將此 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 應用程式中使用可下載的 Font API 下載 Google 並在應用程式中使用這種字型
目前不支援自訂提供者提供的可下載字型。
透過程式輔助方式使用可下載字型
如要在應用程式中以程式輔助方式下載字型,請按照下列步驟操作:
- 新增依附元件:
Groovy
dependencies { ... implementation "androidx.compose.ui:ui-text-google-fonts:1.6.8" }
Kotlin
dependencies { ... implementation("androidx.compose.ui:ui-text-google-fonts:1.6.8") }
- 將
GoogleFont.Provider
敬上 擁有 Google Fonts 的憑證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 的字型提供者授權。
- 用於驗證供應者身分的字型提供者套件。
- 憑證的雜湊組合清單,用於驗證憑證的身分
。您可以找到 Google Fonts 供應商所需的雜湊。
的
font_certs.xml
檔案裡,位於 Jetchat 範例應用程式。
- 定義
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 可組合函式中的應用程式:
Text( fontFamily = fontFamily, text = "Hello World!" )
![](https://developer.android.com/static/develop/ui/compose/images/text-dl-fontfamily.png?authuser=9&hl=zh-tw)
您也可以製定
字體排版
您的 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 以及這類網址
可下載 Font API (在 View 系統或 Compose 中)。新上榜
在應用程式中載入的字型和文字
IllegalStateException
。
為協助開發人員辨識這項錯誤,而非其他類型的字型載入錯誤,
我們針對 Compose 的例外狀況新增了描述性訊息
此處。
如果發現任何問題,請使用
追蹤器。
使用可變字型
可變字型是一種字型格式,能讓一個字型檔案包含 。透過可變字型,您可以修改軸 (或參數) 以產生 您偏好的風格這些軸可以是標準值,例如重量、寬度、斜體 以及文字,這會因變數字型而異
![具有相同可變字型、不同軸值的五項設定。](https://developer.android.com/static/develop/ui/compose/images/text/vf-configs.png?authuser=9&hl=zh-tw)
使用可變字型而非一般字型檔案 設定成多個字型檔案
如需更多可變字型的背景資訊,請參閱 Google Fonts 知識:涵蓋的完整目錄 可變字型,以及每種詞彙支援的軸表 ,
本文件說明如何在 Compose 應用程式中實作可變字型。
載入變數字型
下載您想使用的變數字型 (例如 Roboto Flex),並 然後放在應用程式的
app/res/font
資料夾中。請確認 .ttf
您要新增的就是字型的變數字型版本,以及 字型檔案全部為小寫,不含任何特殊字元。如果要載入變數字型,請使用
FontFamily
res/font/
目錄:// 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 和 slant。這些是標準的軸 所有可變字型都能使用您也能針對 Cloud Build 根據該字型使用的位置決定合適的字型變數字型僅適用於 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 Design 主題的樣式設定, 則含有不同的字型設定。別擔心!您可以使用MaterialTheme.typography
:擷取提供給 M3 的字體排版MaterialTheme
可組合函式。
![三種文字,分別顯示不同的字型設定。](https://developer.android.com/static/develop/ui/compose/images/text/vf-standard-axes.png?authuser=9&hl=zh-tw)
使用自訂軸
字型也可以有自訂軸。這些定義位於字型檔案本身中。
舉例來說,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()) }
這些函式可執行以下作業:
- 定義防護機制可以接受的值。如同
變數字型目錄,
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 }
請注意,小寫遞增器的高度現在會增加 其他文字較寬:
![三則不同的文字分別顯示不同設定,且已設定自訂軸。](https://developer.android.com/static/develop/ui/compose/images/text/vf-custom-axes.png?authuser=9&hl=zh-tw)
其他資源
如需詳細資訊,請參閱下列有關可變字型的網誌文章:
為您推薦
- 注意:系統會在 JavaScript 關閉時顯示連結文字
- Compose 中的資源
- 設定文字樣式
- Compose 中的質感設計 2