文本输入

本篇说明 Compose DSL 下的文本渲染与输入组件：BasicText、BasicTextField、TextFieldState、KeyboardOptions。

与 material3 Text/TextField 的区别

BasicText、BasicTextField 属于 foundation 层，不消费主题样式；Text、TextField 属于 material3 层，默认读取 LocalTextStyle / LocalContentColor（当前 MaterialTheme() 不注入文本样式）。需要主题能力时优先使用后者（见核心组件）。

BasicText

纯文本渲染组件。

参数	描述	类型
text 必需	文本内容	String / AnnotatedString
modifier 非必需	修饰符	Modifier
style 非必需	文本样式	TextStyle
onTextLayout 非必需	文本布局完成回调	((TextLayoutResult) -> Unit)?
overflow 非必需	溢出处理方式	TextOverflow
softWrap 非必需	是否自动换行	Boolean
maxLines 非必需	最大行数	Int
minLines 非必需	最小行数	Int
color 非必需	覆盖 style 中的颜色	ColorProducer?

AnnotatedString 重载额外支持 inlineContent 参数，用于在文本中插入行内组合内容。

示例

BasicText(
    text = "基础文本",
    style = TextStyle(fontSize = 16.sp, color = Color.Black),
    maxLines = 2,
    overflow = TextOverflow.Ellipsis
)

BasicTextField

基于 TextFieldState 的基础输入框。

参数	描述	类型
state 必需	输入框状态	TextFieldState
modifier 非必需	修饰符	Modifier
enabled 非必需	是否可编辑	Boolean
readOnly 非必需	是否只读	Boolean
textStyle 非必需	文本样式	TextStyle
keyboardOptions 非必需	键盘配置	KeyboardOptions
keyboardActions 非必需	IME 动作回调	KeyboardActions
singleLine 非必需	是否单行	Boolean
maxLines 非必需	最大行数，singleLine 为 true 时固定为 1	Int
inputTransformation 非必需	输入内容的转换与校验	InputTransformation?
outputTransformation 非必需	传入 TextPostProcessorOutputTransformation 以声明文本后置处理器	OutputTransformation?
onTextLayout 非必需	文本布局完成回调	(TextLayoutResult) -> Unit
interactionSource 非必需	交互源	MutableInteractionSource?
cursorBrush 非必需	光标画刷	Brush
decorationBox 非必需	装饰容器，包裹内部输入框	@Composable (innerTextField: @Composable () -> Unit) -> Unit

示例

val state = rememberTextFieldState()

BasicTextField(
    state = state,
    modifier = Modifier.fillMaxWidth().padding(16.dp),
    singleLine = true,
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search)
)

TextFieldState

输入框状态，承载文本、选区与组合态。

成员	说明
text / selection / composition	当前文本、选区和组合态
edit { }	推荐的写入入口，在 TextFieldBuffer 中修改内容
clearText()	清空文本
setTextAndPlaceCursorAtEnd(text)	设置文本并将光标置于末尾
setTextAndSelect(text, selection, composition)	整体写入文本与选区

创建方式：

val state = rememberTextFieldState(initialText = "", initialSelection = TextRange(0))

写入收敛约定

TextFieldState 的所有变更最终都收敛到 setTextAndSelect，它会将 selection 与 composition 约束到文本长度范围内。业务侧写入应走 edit { }，setTextAndSelect 仅在受控场景下调用。

KeyboardOptions

键盘与 IME 配置。

参数	描述	类型
capitalization 非必需	首字母大写策略	KeyboardCapitalization
autoCorrectEnabled 非必需	是否启用自动纠错	Boolean?
keyboardType 非必需	键盘类型	KeyboardType
imeAction 非必需	回车键动作	ImeAction
platformImeOptions 非必需	平台特定的 IME 配置	PlatformImeOptions?
showKeyboardOnFocus 非必需	获焦时是否弹出键盘，null 表示弹出	Boolean?
hintLocales 非必需	期望切换到的语言提示	LocaleList?

KeyboardOptions(keyboardType = KeyboardType.Number, imeAction = ImeAction.Done)

废弃构造

不带 autoCorrectEnabled 参数的旧构造已标记废弃，请使用新构造。

相关 Modifier

文本输入相关的能力通过 Modifier 提供，详见核心组件 - TextField 组件扩展：

Modifier	说明
Modifier.maxLength / onLimitChange	输入长度限制与超限回调
Modifier.placeHolder / placeholderColor	占位文案与颜色
Modifier.autoHideKeyboardOnImeAction	触发 IME 动作后自动收起键盘
Modifier.keyboardHeightChange	键盘高度变化回调