TextField

TextField 是 Miuix 中的基础输入组件，用于接收用户的文本输入。组件提供了丰富的自定义选项，支持标签动画、前置和后置图标等功能。

引入

import top.yukonga.miuix.kmp.basic.TextField

基本用法

TextField 组件可以用于获取用户输入：

var text by remember { mutableStateOf("") }

TextField(
    value = text,
    onValueChange = { text = it },
    label = "用户名"
)

信息

此 TextFiled 组件现在也支持最新基于状态的版本，具体请参考 State-based 文档。

输入框类型

带标签输入框

标签会在输入框获得焦点或有内容时自动移动到顶部：

var text by remember { mutableStateOf("") }

TextField(
    value = text,
    onValueChange = { text = it },
    label = "邮箱地址"
)

使用标签作为占位符

var text by remember { mutableStateOf("") }

TextField(
    value = text,
    onValueChange = { text = it },
    label = "请输入内容",
    useLabelAsPlaceholder = true
)

组件状态

禁用状态

var text by remember { mutableStateOf("") }
TextField(
    value = text,
    onValueChange = { text = it },
    label = "禁用输入框",
    enabled = false
)

只读状态

var text by remember { mutableStateOf("这是只读内容") }

TextField(
    value = text,
    onValueChange = { text = it },
    label = "只读输入框",
    readOnly = true
)

属性

TextField 属性

属性名	类型	说明	默认值	是否必须
value	String 或 TextFieldValue	输入框的文本值	-	是
onValueChange	(String) -> Unit 或 (TextFieldValue) -> Unit	文本变化时的回调函数	-	是
modifier	Modifier	应用于输入框的修饰符	Modifier	否
insideMargin	DpSize	输入框内部边距	TextFieldDefaults.InsideMargin	否
colors	TextFieldColors	输入框使用的颜色	TextFieldDefaults.textFieldColors()	否
cornerRadius	Dp	输入框圆角半径	TextFieldDefaults.CornerRadius	否
label	String	输入框标签文本	""	否
useLabelAsPlaceholder	Boolean	是否使用标签作为占位符	false	否
enabled	Boolean	输入框是否可用	true	否
readOnly	Boolean	输入框是否只读	false	否
textStyle	TextStyle	输入文本样式	MiuixTheme.textStyles.main	否
keyboardOptions	KeyboardOptions	键盘选项配置	KeyboardOptions.Default	否
keyboardActions	KeyboardActions	键盘操作配置	KeyboardActions.Default	否
leadingIcon	@Composable (() -> Unit)?	前置图标	null	否
trailingIcon	@Composable (() -> Unit)?	后置图标	null	否
singleLine	Boolean	是否为单行输入	false	否
maxLines	Int	最大行数	如果 singleLine 为 true 则为 1，否则为 Int.MAX_VALUE	否
minLines	Int	最小行数	1	否
visualTransformation	VisualTransformation	视觉转换器	VisualTransformation.None	否
onTextLayout	(TextLayoutResult) -> Unit	文本布局变化回调	{}	否
interactionSource	MutableInteractionSource?	交互源	null	否
cursorBrush	Brush	光标画刷	SolidColor(colors.borderColor)	否

TextField（state-based）属性

属性名	类型	说明	默认值	是否必须
state	TextFieldState	保存文本与选择的状态对象	-	是
modifier	Modifier	应用于输入框的修饰符	Modifier	否
insideMargin	DpSize	输入框内部边距	TextFieldDefaults.InsideMargin	否
colors	TextFieldColors	输入框使用的颜色	TextFieldDefaults.textFieldColors()	否
cornerRadius	Dp	输入框圆角半径	TextFieldDefaults.CornerRadius	否
label	String	输入框标签文本	""	否
useLabelAsPlaceholder	Boolean	是否使用标签作为占位符	false	否
enabled	Boolean	输入框是否可用	true	否
readOnly	Boolean	输入框是否只读	false	否
inputTransformation	InputTransformation?	输入变换器	null	否
textStyle	TextStyle	输入文本样式	MiuixTheme.textStyles.main	否
keyboardOptions	KeyboardOptions	键盘选项配置	KeyboardOptions.Default	否
onKeyboardAction	KeyboardActionHandler?	键盘动作处理器	null	否
lineLimits	TextFieldLineLimits	行数限制	TextFieldLineLimits.Default	否
leadingIcon	@Composable (() -> Unit)?	前置图标	null	否
trailingIcon	@Composable (() -> Unit)?	后置图标	null	否
onTextLayout	Density.(getResult: () -> TextLayoutResult?) -> Unit	文本布局回调（带 Density 接收）	null	否
interactionSource	MutableInteractionSource?	交互源	null	否
cursorBrush	Brush	光标画刷	SolidColor(colors.borderColor)	否
outputTransformation	OutputTransformation?	输出变换器	null	否
scrollState	ScrollState	滚动状态	rememberScrollState()	否

TextFieldDefaults 对象

TextFieldDefaults 对象提供了 TextField 组件的默认值。

常量

常量名	类型	说明	默认值
CornerRadius	Dp	输入框圆角半径	16.dp
InsideMargin	DpSize	输入框内部边距	DpSize(16.dp, 16.dp)

textFieldColors() 工厂

构造 [TextFieldColors] 实例。按需覆盖任意子集，未指定的参数回退到 Miuix 主题默认值。

参数	类型	默认值
backgroundColor	Color	MiuixTheme.colorScheme.secondaryContainer
labelColor	Color	MiuixTheme.colorScheme.onSecondaryContainer
borderColor	Color	MiuixTheme.colorScheme.primary

进阶用法

带图标输入框

var text by remember { mutableStateOf("") }

TextField(
    value = text,
    onValueChange = { text = it },
    label = "搜索",
    leadingIcon = {
        Icon(
            imageVector = MiuixIcons.Search,
            contentDescription = "搜索图标",
            modifier = Modifier.padding(horizontal = 12.dp)
        )
    }
)

密码输入框

var password by remember { mutableStateOf("") }
var passwordVisible by remember { mutableStateOf(false) }

TextField(
    value = password,
    onValueChange = { password = it },
    label = "密码",
    visualTransformation = if (passwordVisible) VisualTransformation.None else PasswordVisualTransformation(),
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
    trailingIcon = {
        IconButton(
            onClick = { passwordVisible = !passwordVisible },
            modifier = Modifier.padding(end = 12.dp)
        ) {
            Icon(
                imageVector = MiuixIcons.Rename,
                tint = if (passwordVisible) MiuixTheme.colorScheme.primary else MiuixTheme.colorScheme.onSecondaryContainer,
                contentDescription = if (passwordVisible) "隐藏密码" else "显示密码"
            )
        }
    }
)

带验证的输入框

var email by remember { mutableStateOf("") }
var isError by remember { mutableStateOf(false) }
val errorColor = Color.Red.copy(0.3f)
val emailPattern = remember { Regex("[a-zA-Z0-9._-]+@[a-z]+\\.+[a-z]+") }

Column {
    TextField(
        value = email,
        onValueChange = {
            email = it
            isError = email.isNotEmpty() && !emailPattern.matches(email)
        },
        label = "电子邮箱",
        colors = TextFieldDefaults.textFieldColors(
            labelColor = if (isError) errorColor else MiuixTheme.colorScheme.onSecondaryContainer,
        ),
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Email)
    )
    if (isError) {
        Text(
            text = "请输入有效的邮箱地址",
            color = errorColor,
            style = MiuixTheme.textStyles.body2,
            modifier = Modifier.padding(start = 16.dp, top = 4.dp)
        )
    }
}

自定义样式

var text by remember { mutableStateOf("") }

TextField(
    value = text,
    onValueChange = { text = it },
    label = "自定义输入框",
    cornerRadius = 8.dp,
    colors = TextFieldDefaults.textFieldColors(
        backgroundColor = MiuixTheme.colorScheme.primary.copy(alpha = 0.1f),
    ),
    textStyle = TextStyle(
        fontWeight = FontWeight.Medium,
        fontSize = 16.sp,
        color = MiuixTheme.colorScheme.primary
    )
)

使用 TextFieldValue

当需要更细致地控制文本选择和光标位置时：

var textFieldValue by remember { mutableStateOf(TextFieldValue("")) }

TextField(
    value = textFieldValue,
    onValueChange = { textFieldValue = it },
    label = "高级输入控制",
    // TextFieldValue 提供了对文本、选择范围和光标位置的控制
)

变更日志

最后编辑于 4 个月前

查看完整变更日志

a033aee-library: consolidate TextField colors and decoration

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

80e2357-library: refactor component defaults into dedicated Defaults objects

1769fbb-refactor: Move extended icon to a separate library

4007f40-docs: fix errors

aec2c52-library: Add state-based TextFiled support

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

b3fb31c-library: TextField: Add borderColor & cursorBrush param

7b99e64-docs: Add English version through AI translation

ab6bb69-chore: Add documents (#63)