Text

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

引入

import io.github.suqi8.coui.kmp.basic.Text

基本用法

最简单的文本展示：

Text("This is a basic text")

文本样式

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

Text(
    text = "Title Text",
    style = COUITheme.textStyles.headline1
)

Text(
    text = "Subtitle Text",
    style = COUITheme.textStyles.subtitle
)
Text(
    text = "Summary Text",
    style = COUITheme.textStyles.body2
)

Text(
    text = "Main Text",
    style = COUITheme.textStyles.main
)

文本颜色

Text(
    text = "Default Color Text",
    color = COUITheme.colorScheme.onBackground
)

Text(
    text = "Primary Color Text",
    color = COUITheme.colorScheme.primary
)

Text(
    text = "Secondary Text",
    color = COUITheme.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	文本样式	COUITheme.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	文本样式	COUITheme.textStyles.main	否

进阶用法

多行文本截断

Text(
    text = "This is a very long text that will be truncated and show ellipsis when there is not enough space. This is useful for displaying long content summaries.",
    maxLines = 2,
    overflow = TextOverflow.Ellipsis
)

文本装饰

Text(
    text = "Underlined Text",
    textDecoration = TextDecoration.Underline
)

Text(
    text = "Strikethrough Text",
    textDecoration = TextDecoration.LineThrough
)

富文本混排

Text(
    buildAnnotatedString {
        withStyle(style = SpanStyle(color = COUITheme.colorScheme.primary)) {
            append("COUI ")
        }
        withStyle(style = SpanStyle(fontWeight = FontWeight.Bold)) {
            append("UI Library")
        }
        append(", this is a piece of rich text")
    }
)

文本自动适配

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

Text(
    text = "Adaptive 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 = "Scroll-tinted text",
    color = {
        lerp(
            COUITheme.colorScheme.onSurface,
            COUITheme.colorScheme.primary,
            (scrollState.value / 500f).coerceIn(0f, 1f),
        )
    },
)

可点击链接

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

val annotated = buildAnnotatedString {
    append("Visit ")
    val start = length
    append("COUI Docs")
    addLink(
        LinkAnnotation.Url(
            url = "https://suqi8.github.io/coui/",
            styles = TextLinkStyles(
                SpanStyle(color = COUITheme.colorScheme.primary, fontWeight = FontWeight.Bold)
            )
        ),
        start = start,
        end = length
    )
}

Text(text = annotated)

变更日志

最后编辑于 9 天前

查看完整变更日志

429b622-docs: rebrand site to COUI and audit all component pages

9293915-docs: fix module names and dead dokka links after rename

9aba0de-chore: rename package from com.suqi8 to io.github.suqi8

7acb5ab-library: retheme to COUI 16 and rename Miuix to COUI

0f4e384-library: add ColorProducer overloads to Text

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

98eff29-docs: fix errors

2cf56f3-docs: Update theme docs

5df821a-library: Refactor Text from androidx-main

25d20ba-docs: Preview for components in documentation website (#80)

cc1634b-docs: Add English version through AI translation

7bd2bac-chore: Add documents (#63)