設定文字樣式

Text 可組合函式有多個選用參數，可為內容設定樣式。 下方列出的參數涵蓋最常見的文字用途。 如需瞭解 Text 的所有參數，請參閱 Compose 文字 原始碼。

每當您設定其中一個參數，樣式就會套用至整個 文字值。如果您需要在同一行內套用多個樣式，或是 段落，請參閱「多行程式碼」一節 樣式。

常見的文字樣式

以下各節說明設定文字樣式的常見方式。

變更文字顏色

@Composable
fun BlueText() {
    Text("Hello World", color = Color.Blue)
}
TextSnippets.kt

調整文字大小

@Composable
fun BigText() {
    Text("Hello World", fontSize = 30.sp)
}
TextSnippets.kt

將文字設為斜體

使用 fontStyle 參數將文字設為斜體 (或設定其他文字) FontStyle)。

@Composable
fun ItalicText() {
    Text("Hello World", fontStyle = FontStyle.Italic)
}
TextSnippets.kt

將文字設為粗體

使用 fontWeight 參數將文字變為粗體 (或設定另一個 FontWeight)。

@Composable
fun BoldText() {
    Text("Hello World", fontWeight = FontWeight.Bold)
}
TextSnippets.kt

加上陰影

style 參數可讓您設定 TextStyle 類型的物件 並設定多個參數，例如陰影 「Shadow」收到顏色 陰影、偏移值或與 Text 的相對位置 也就是模糊半徑，也就是圖像的模糊程度

@Composable
fun TextShadow() {
    val offset = Offset(5.0f, 10.0f)
    Text(
        text = "Hello world!",
        style = TextStyle(
            fontSize = 24.sp,
            shadow = Shadow(
                color = Color.Blue, offset = offset, blurRadius = 3f
            )
        )
    )
}
TextSnippets.kt

在文字中新增多種樣式

在同一 Text 中設定不同樣式 可組合函式、使用 AnnotatedString、 能以任意註解樣式加註的字串。

AnnotatedString 是包含以下項目的資料類別：

• Text 值
• SpanStyleRange 的 List，相當於設有位置的內嵌樣式 文字值的範圍
• ParagraphStyleRange 的 List，用於指定文字對齊方式和文字 方向、行高和文字縮排樣式

TextStyle 可供使用 在 Text 可組合函式中，而 SpanStyle 和ParagraphStyle 用於 AnnotatedString。如要進一步瞭解 如需段落，請參閱「在段落中新增多種樣式」。

AnnotatedString 具有類型安全 建構工具 ，方便你建立：buildAnnotatedString。

@Composable
fun MultipleStylesInText() {
    Text(
        buildAnnotatedString {
            withStyle(style = SpanStyle(color = Color.Blue)) {
                append("H")
            }
            append("ello ")

            withStyle(style = SpanStyle(fontWeight = FontWeight.Bold, color = Color.Red)) {
                append("W")
            }
            append("orld")
        }
    )
}
TextSnippets.kt

啟用 Brush 進階樣式

如要啟用進階文字樣式，您可以將 Brush API 與以下項目搭配使用： TextStyle和SpanStyle。在您平常經常使用的位置 使用 TextStyle 或 SpanStyle，您現在也可以使用 Brush。

注意： 目前在 TextStyle 中使用 Brush API 的實驗功能。 實驗性 API 日後可能會變更。

使用筆刷打造文字樣式

在 TextStyle 中使用內建筆刷設定文字。舉例來說， 可依下列方式設定 linearGradient 筆刷：

val gradientColors = listOf(Cyan, LightBlue, Purple /*...*/)

Text(
    text = text,
    style = TextStyle(
        brush = Brush.linearGradient(
            colors = gradientColors
        )
    )
)
TextSnippets.kt

圖 2. 使用 Brush API 的 linearGradient 函式搭配已定義的顏色清單。

不過，系統能夠提供的色彩配置或著色樣式並非侷限於此特定的色彩配置或風格。雖然 這裡提供了簡單的範例 讓您使用其中一則內建提示 筆刷或 SolidColor 也能強化文字效果。

整合

由於 Brush 可以同時使用 TextStyle 和 SpanStyle， 與 TextField 和 buildAnnotatedString 完美整合。

如要進一步瞭解如何在 TextField 中使用筆刷 API，請參閱 使用 Brush API 輸入樣式輸入內容。

使用 SpanStyle 的其他樣式

將筆刷套用至一段文字

如果您只要為部分文字套用筆刷，請使用 buildAnnotatedString、SpanStyle API，以及筆刷 和選擇的漸層

Text(
    text = buildAnnotatedString {
        append("Do not allow people to dim your shine\n")
        withStyle(
            SpanStyle(
                brush = Brush.linearGradient(
                    colors = rainbowColors
                )
            )
        ) {
            append("because they are blinded.")
        }
        append("\nTell them to put some sunglasses on.")
    }
)
TextSnippets.kt

圖 4. 使用 linearGradient 的預設筆刷做為 Text 的樣式。

文字段內的不透明度

如要調整特定文字段的不透明度，請使用 SpanStyle 的 自選 alpha 參數使用相同的筆刷 這兩個部分，並變更對應 Span 中的 alpha 參數。 在程式碼範例中，第一段文字會以半透明度顯示 (alpha =.5f) 時，第二個則會以完全不透明度 (alpha = 1f) 顯示。

val brush = Brush.linearGradient(colors = rainbowColors)

buildAnnotatedString {
    withStyle(
        SpanStyle(
            brush = brush, alpha = .5f
        )
    ) {
        append("Text in ")
    }
    withStyle(
        SpanStyle(
            brush = brush, alpha = 1f
        )
    ) {
        append("Compose ❤️")
    }
}
TextSnippets.kt

圖 5. 使用 buildAnnotatedString 和 SpanStyle 的 Alpha 參數，以及 linearGradient，為文字段添加不透明度。

其他資源

如需其他自訂範例，請參閱在撰寫文字上刷新 顏色網誌文章。如想進一步瞭解 Brush 如何與 Animations API 整合，請參閱動畫筆刷文字顏色 。

將跑馬燈效果套用至文字

basicMarquee 修飾符可以套用至 就會產生動畫捲動效果如果內容正常 太寬，超出可用的限制。根據預設，basicMarquee 擁有 某些設定 (例如速率與初始延遲) 的特定設定，但您也可以 並修改這些參數來自訂效果

下列程式碼片段在 Text 可組合項中實作基本的跑馬燈效果：

@OptIn(ExperimentalFoundationApi::class)
@Composable
fun BasicMarqueeSample() {
    // Marquee only animates when the content doesn't fit in the max width.
    Column(Modifier.width(400.dp)) {
        Text(
            "Learn about why it's great to use Jetpack Compose",
            modifier = Modifier.basicMarquee(),
            fontSize = 50.sp
        )
    }
}
TextSnippets.kt

圖 6. basicMarquee 修飾符已套用至文字。