Jetpack Compose 中的文字

文字对任何界面都属于核心内容，而利用 Jetpack Compose 可以更轻松地显示或写入文字。Compose 可以充分利用其构建块的组合，这意味着您无需覆盖各种属性和方法，也无需扩展大型类，即可拥有特定的可组合项设计以及按您期望的方式运行的逻辑。

Compose 提供了基础的 BasicText 和 BasicTextField，它们是用于显示文字以及处理用户输入的主要函数。Compose 还提供了更高级的 Text 和 TextField，它们是遵循 Material Design 准则的可组合项。建议在 Android 平台上使用这些构建块，因为它们的外观和样式非常适合 Android 用户，而且还包括可用以简化用户自定义设置的其他选项，无需编写大量代码。

显示文字

显示文字的最基本方法是使用以 String 作为参数的 Text 可组合项：

@Composable
fun SimpleText() {
  Text("Hello World")
}

显示resource中的文字

我们建议您使用字符串资源，而不是对 Text 值进行硬编码，因为使用字符串资源时您可以与 Android 视图共享相同的字符串，并为您的应用国际化做好准备：

@Composable
fun StringResourceText() {
  Text(stringResource(R.string.hello_world))
}

设置文字样式

Text 可组合项有多个用于为其内容设置样式的可选参数。 以下列出了适用于最常见文字用例的参数。如需查看 Text 的所有参数，建议您查阅 Compose Text 源代码。

每当您设置其中任何一个参数，都会将样式应用于整个文字值。如果您需要在同一行或段落中应用多种样式，请参阅有关多种内嵌样式的部分。

更改文字颜色

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

更改字号

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

将文字设为斜体

使用 fontStyle 参数可以将文字设为斜体（或设置其他 FontStyle）。

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

将文字设为粗体

使用 fontWeight 参数将文字设为粗体（或设置其他 FontWeight）。

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

文字对齐

通过 textAlign 参数，您可以在 Text 可组合项的 Surface 区域内设置文字的对齐方式。

默认情况下，Text 会根据其内容值选择自然的文字对齐方式：

• 对于从左到右书写的文字，如拉丁语、西里尔文或朝鲜文，向 Text 容器的左边缘对齐
• 对于从右到左书写的文字，如阿拉伯语或希伯来语，向 Text 容器的右边缘对齐

@Preview(showBackground = true)
@Composable
fun CenterText() {
    Text("Hello World", textAlign = TextAlign.Center,
                modifier = Modifier.width(150.dp))
}

如果您想手动设置 Text 可组合项的文字对齐方式，最好分别使用 TextAlign.Start 和 TextAlign.End（而不要使用 TextAlign.Left 和 TextAlign.Right），这样系统就可以根据具体语言的首选文字方向，将您的设置解析为向 Text 的右边缘对齐。例如，TextAlign.End 对于法语文字将向右侧对齐，而对于阿拉伯语文字则将向左侧对齐，但无论对于哪种文字，TextAlign.Right 都将向右侧对齐。

注意：文字对齐与布局对齐不同，后者指的是容器（例如 Row 或 Column）中的可组合项定位。如需了解详情，请查看 Compose 布局基础知识文档。

处理字体

Text 有一个 fontFamily 参数，用于设置可组合项中使用的字体。默认情况下，系统会添加 Serif、Sans Serif、等宽和 Cursive 字体系列：

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

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

此示例展示了如何根据这些字体文件以及使用 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(..., fontFamily = firaSansFamily, fontWeight = FontWeight.Light)
    Text(..., fontFamily = firaSansFamily, fontWeight = FontWeight.Normal)
    Text(
        ..., fontFamily = firaSansFamily, fontWeight = FontWeight.Normal,
        fontStyle = FontStyle.Italic
    )
    Text(..., fontFamily = firaSansFamily, fontWeight = FontWeight.Medium)
    Text(..., fontFamily = firaSansFamily, fontWeight = FontWeight.Bold)
}

如需了解如何在整个应用中设置排版，请参阅主题文档。

文字中包含多种样式

如需在同一 Text 可组合项中设置不同的样式，必须使用 AnnotatedString，该字符串可使用任意注解样式加以注解。

AnnotatedString 是一个数据类，其中包含：

• 一个 Text 值
• 一个 SpanStyleRange 的 List，等同于位置范围在文字值内的内嵌样式
• 一个 ParagraphStyleRange 的 List，用于指定文字对齐、文字方向、行高和文字缩进样式

TextStyle 用于 Text 可组合项，而 SpanStyle 和 ParagraphStyle 用于 AnnotatedString。

SpanStyle 和 ParagraphStyle 之间的区别在于，ParagraphStyle 可应用于整个段落，而 SpanStyle 可以在字符级别应用。一旦用 ParagraphStyle 标记了一部分文字，该部分就会与其余部分隔开，就像在开头和末尾有换行符一样。

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")
        }
    )
}

我们可以用相同的方式设置 ParagraphStyle：

@Composable
fun ParagraphStyle() {
    Text(
        buildAnnotatedString {
            withStyle(style = ParagraphStyle(lineHeight = 30.sp)) {
                withStyle(style = SpanStyle(color = Color.Blue)) {
                    append("Hello\n")
                }
                withStyle(
                    style = SpanStyle(
                        fontWeight = FontWeight.Bold,
                        color = Color.Red
                    )
                ) {
                    append("World\n")
                }
                append("Compose")
            }
        }
    )
}

行数上限

如需限制 Text 可组合项中的可见行数，请如如下方式设置 maxLines 参数：

@Composable
fun LongText() {
    Text("hello ".repeat(50), maxLines = 2)
}

文字溢出

在限制长文字时，您可能需要指定 TextOverflow，这些内容只有在显示的文字被截断时才会显示。如需指定文字溢出，请按如下方式设置 textOverflow 参数：

@Composable
fun OverflowedText() {
    Text("Hello Compose ".repeat(50), maxLines = 2, overflow = TextOverflow.Ellipsis)
}

主题

如需使用应用主题进行文字样式设置，请参阅主题文档。

用户互动

Jetpack Compose 支持 Text 中的精细互动。文字选择现在更加灵活，并且可以跨各种可组合项布局进行选择。文字中的用户互动与其他可组合项布局不同，因为您无法为 Text 可组合项的某一部分添加修饰符。本部分将重点介绍支持用户互动的不同 API。

选择文字

默认情况下，可组合项不可选择，这意味着在默认情况下用户无法从您的应用中选择和复制文字。要启用文字选择，需要使用 SelectionContainer 可组合项封装文字元素：

@Composable
fun SelectableText() {
    SelectionContainer {
        Text("This text is selectable")
    }
}

您可能想为可选择区域的特定部分停用选择功能。如果要执行此操作，您需要使用 DisableSelection 可组合项来封装不可选择的部分：

@Composable
fun PartiallySelectableText() {
    SelectionContainer {
        Column {
            Text("This text is selectable")
            Text("This one too")
            Text("This one as well")
            DisableSelection {
                Text("But not this one")
                Text("Neither this one")
            }
            Text("But again, you can select this one")
            Text("And this one too")
        }
    }
}

获取点击文字的位置

如需监听 Text 的点击次数，您可以添加 clickable 修饰符。不过，如果您想在 Text 可组合项内获取点击位置，在对文字的不同部分执行不同操作的情况下，您需要改用 ClickableText。

@Composable
fun SimpleClickableText() {
    ClickableText(
        text = AnnotatedString("Click Me"),
        onClick = { offset ->
            Log.d("ClickableText", "$offset -th character is clicked.")
        }
    )
}

点击注解

当用户点击 Text 可组合项时，您可能想向 Text 值的某一部分附加额外信息，例如向特定字词附加可在浏览器中打开的网址。如果要执行此操作，您需要附加一个注解，用于获取一个标记 (String)、一个项 (String) 和一个文字范围作为参数。在 AnnotatedString 中，这些注解可以按照其标记或文字范围进行过滤。示例如下：

@Composable
fun AnnotatedClickableText() {
    val annotatedText = buildAnnotatedString {
        append("Click ")

        // We attach this *URL* annotation to the following content
        // until `pop()` is called
        pushStringAnnotation(tag = "URL",
                             annotation = "https://developer.android.com")
        withStyle(style = SpanStyle(color = Color.Blue,
                                    fontWeight = FontWeight.Bold)) {
            append("here")
        }

        pop()
    }

    ClickableText(
        text = annotatedText,
        onClick = { offset ->
            // We check if there is an *URL* annotation attached to the text
            // at the clicked position
            annotatedText.getStringAnnotations(tag = "URL", start = offset,
                                                    end = offset)
                .firstOrNull()?.let { annotation ->
                    // If yes, we log its value
                    Log.d("Clicked URL", annotation.item)
                }
        }
    )
}

输入和修改文字

TextField 允许用户输入和修改文字。TextField 实现分为两个级别：

1. TextField 是 Material Design 实现。我们建议您选择此实现，因为它遵循的是 Material Design 指南：

   • 默认样式为填充
   • OutlinedTextField 是轮廓样式版本

2. BasicTextField 允许用户通过硬件或软件键盘编辑文字，但没有提供提示或占位符等装饰。

@Composable
fun SimpleFilledTextFieldSample() {
    var text by remember { mutableStateOf("Hello") }

    TextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}

@Composable
fun SimpleOutlinedTextFieldSample() {
    var text by remember { mutableStateOf("") }

    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}

设置 TextField 样式

TextField 和 BasicTextField 共用许多可对它们进行自定义的常用参数。如需查看 TextField 的完整列表，请参阅 TextField 源代码。以下列出了部分有用的参数，但并非详尽无遗：

• singleLine
• maxLines
• textStyle

@Composable
fun StyledTextField() {
    var value by remember { mutableStateOf("Hello\nWorld\nInvisible") }

    TextField(
        value = value,
        onValueChange = { value = it },
        label = { Text("Enter text") },
        maxLines = 2,
        textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
        modifier = Modifier.padding(20.dp)
    )
}

如果您的设计调用 Material TextField 或 OutlineTextField，建议您使用 TextField 而不是 BasicTextField。但是，在构建无需 Material 规范中的装饰的设计时，应使用 BasicTextField。

键盘选项

借助 TextField，您可以设置键盘配置选项（例如键盘布局），或启用自动更正（如果键盘支持的话）。如果软件键盘不符合此处提供的选项，则无法保证某些选项的可用性。下面列出了支持的键盘选项：

• capitalization
• autoCorrect
• keyboardType
• imeAction

格式设置

TextField 允许您为输入值设置 VisualTransformation，例如将密码中的字符替换为 *，或在信用卡号码中每 4 位插入一个连字符：

@Composable
fun PasswordTextField() {
    var password by rememberSaveable { mutableStateOf("") }

    TextField(
        value = password,
        onValueChange = { password = it },
        label = { Text("Enter password") },
        visualTransformation = PasswordVisualTransformation(),
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password)
    )
}

如需查看更多示例，请参阅 VisualTransformSamples 源代码。

清理输入

在修改文本时，一项常见的任务是删除前导字符，或者在每次发生更改时转换输入字符串。

因此，您应假设键盘可以对每个 onValueChange 随意进行大量修改。例如，如果用户使用自动更正功能，将某个字词替换为表情符号或使用其他智能编辑功能，就可能会发生这种情况。为了正确处理这种情况，请在编写任何转换逻辑时假设传递到 onValueChange 的当前文本与将传递给 onValueChange 的上一个或下一个值无关。

如需实现不允许使用前导零的文本字段，您可以通过在每次更改值时去除所有前导零来实现此目的。

@Composable
fun NoLeadingZeroes() {
  val input by rememberSavable { mutableStateOf("") }
  TextField(
      value = input
      onValueChange = { newText ->
          input = newText.trimStart { it == '0' }
      }
  )
}

如需在清理文本时控制光标位置，请使用 TextField 的 TextFieldValue 重载，而不是传递常规 String。此重载允许您将光标位置作为状态的一部分来更改。