Text

Text 组件是 Miuix 中的基础文本组件，用于显示文字内容。支持自定义各种文本样式、对齐方式和装饰效果。

引入

import top.yukonga.miuix.kmp.basic.Text

基本用法

最简单的文本展示：

Text("这是一段基本文本")

文本样式

Miuix 提供了多种预定义的文本样式：

Text(
    text = "标题文本",
    style = MiuixTheme.textStyles.headline1
)

Text(
    text = "小标题文本",
    style = MiuixTheme.textStyles.subtitle
)
Text(
    text = "摘要文本",
    style = MiuixTheme.textStyles.body2
)

Text(
    text = "正文文本",
    style = MiuixTheme.textStyles.main
)

文本颜色

Text(
    text = "默认颜色文本",
    color = MiuixTheme.colorScheme.onBackground
)

Text(
    text = "主题色文本",
    color = MiuixTheme.colorScheme.primary
)

Text(
    text = "次要文本",
    color = MiuixTheme.colorScheme.onSurfaceContainerVariant
)

属性

Text（String）属性

属性名	类型	说明	默认值	是否必须
text	String	要显示的文本内容	-	是
modifier	Modifier	应用于文本的修饰符	Modifier	否
color	Color	文本颜色	Color.Unspecified	否
autoSize	TextAutoSize?	文本自动调整大小行为	null	否
fontSize	TextUnit	文本字号	TextUnit.Unspecified	否
fontStyle	FontStyle?	文本字体风格（如斜体）	null	否
fontWeight	FontWeight?	文本字重	null	否
fontFamily	FontFamily?	文本字体族	null	否
letterSpacing	TextUnit	字母间距	TextUnit.Unspecified	否
textDecoration	TextDecoration?	文本装饰（如下划线）	null	否
textAlign	TextAlign?	文本对齐方式	null	否
lineHeight	TextUnit	行高	TextUnit.Unspecified	否
overflow	TextOverflow	文本溢出处理方式	TextOverflow.Clip	否
softWrap	Boolean	是否自动换行	true	否
maxLines	Int	最大行数	Int.MAX_VALUE	否
minLines	Int	最小行数	1	否
onTextLayout	((TextLayoutResult) -> Unit)?	文本布局完成后的回调	null	否
style	TextStyle	文本样式	MiuixTheme.textStyles.main	否

Text（AnnotatedString）属性

属性名	类型	说明	默认值	是否必须
text	AnnotatedString	带注解的富文本	-	是
modifier	Modifier	应用于文本的修饰符	Modifier	否
color	Color	文本颜色	Color.Unspecified	否
autoSize	TextAutoSize?	文本自动调整大小行为	null	否
fontSize	TextUnit	文本字号	TextUnit.Unspecified	否
fontStyle	FontStyle?	文本字体风格	null	否
fontWeight	FontWeight?	文本字重	null	否
fontFamily	FontFamily?	文本字体族	null	否
letterSpacing	TextUnit	字母间距	TextUnit.Unspecified	否
textDecoration	TextDecoration?	文本装饰	null	否
textAlign	TextAlign?	文本对齐方式	null	否
lineHeight	TextUnit	行高	TextUnit.Unspecified	否
overflow	TextOverflow	文本溢出处理方式	TextOverflow.Clip	否
softWrap	Boolean	是否自动换行	true	否
maxLines	Int	最大行数	Int.MAX_VALUE	否
minLines	Int	最小行数	1	否
inlineContent	Map<String, InlineTextContent>	内联可组合项的映射	mapOf()	否
onTextLayout	(TextLayoutResult) -> Unit	文本布局完成后的回调	{}	否
style	TextStyle	文本样式	MiuixTheme.textStyles.main	否

进阶用法

多行文本截断

Text(
    text = "这是一段很长很长的文本，当空间不足时会被截断并显示省略号，这在显示长内容摘要时很有用。",
    maxLines = 2,
    overflow = TextOverflow.Ellipsis
)

文本装饰

Text(
    text = "带下划线的文本",
    textDecoration = TextDecoration.Underline
)

Text(
    text = "带删除线的文本",
    textDecoration = TextDecoration.LineThrough
)

富文本混排

Text(
    buildAnnotatedString {
        withStyle(style = SpanStyle(color = MiuixTheme.colorScheme.primary)) {
            append("Miuix ")
        }
        withStyle(style = SpanStyle(fontWeight = FontWeight.Bold)) {
            append("UI 库")
        }
        append("，这是一段富文本")
    }
)

文本自动适配

使用 TextAutoSize 让文本在可用空间内自动调整字号：

Text(
    text = "自适应文本",
    autoSize = TextAutoSize.StepBased(
        minFontSize = 12.sp,
        maxFontSize = 17.sp,
        stepSize = 0.3.sp
    )
)

高频变化的文本颜色

Text(String, ...) 与 Text(AnnotatedString, ...) 各自还提供一个以 ColorProducer 替换 Color 的重载：

fun Text(text: String, color: ColorProducer, modifier: Modifier = Modifier, ...)
fun Text(text: AnnotatedString, color: ColorProducer, modifier: Modifier = Modifier, ...)

其余参数均与上方表格一致。回调会在绘制阶段直接读取最新值，因此当文本颜色每帧都在变化（动画、滚动联动、手势驱动等）时，Text 自身可以跳过重组：

val scrollState = rememberScrollState()
Text(
    text = "随滚动渐变的文本",
    color = {
        lerp(
            MiuixTheme.colorScheme.onSurface,
            MiuixTheme.colorScheme.primary,
            (scrollState.value / 500f).coerceIn(0f, 1f),
        )
    },
)

可点击链接

通过 AnnotatedString 和 LinkAnnotation 创建可点击链接：

val annotated = buildAnnotatedString {
    append("访问 ")
    val start = length
    append("Miuix 文档站")
    addLink(
        LinkAnnotation.Url(
            url = "https://compose-miuix-ui.github.io/miuix/",
            styles = TextLinkStyles(
                SpanStyle(color = MiuixTheme.colorScheme.primary, fontWeight = FontWeight.Bold)
            )
        ),
        start = start,
        end = length
    )
}

Text(text = annotated)

变更日志

最后编辑于 4 个月前

查看完整变更日志

94f1ff9-library: add ColorProducer overloads to Text

0b7ec07-library: refactor: unify dropdown and spinner components (#315)

4007f40-docs: fix errors

1871e58-docs: Update theme docs

24a5db6-library: Refactor Text from androidx-main

752f3df-docs: Preview for components in documentation website (#80)

7b99e64-docs: Add English version through AI translation

ab6bb69-chore: Add documents (#63)