TextField

用于原生 Material3 文本输入的 Jetpack Compose TextField 组件。

Android
Bundled version:
~55.0.15

For the complete documentation index, see llms.txt. Use this file to discover all available pages.

Expo UI 提供了两个与官方 Jetpack Compose TextField API 匹配的文本字段组件:TextField(填充型)和 OutlinedTextField(带边框型)。两种变体共享相同的属性,并支持可组合插槽子组件,用于标签、占位符、图标、前缀、后缀和辅助文本。

🌐 Expo UI provides two text field components that match the official Jetpack Compose TextField API: TextField (filled) and OutlinedTextField (outlined border). Both variants share the same props and support composable slot children for label, placeholder, icons, prefix, suffix, and supporting text.

类型外观目的
填充型带底部指示线的实心背景。默认文本输入样式,遵循 Material3 设计。适用于大多数表单和输入字段。
描边型透明背景带边框轮廓。提供明显视觉边界的替代样式。当填充字段与背景融为一体时使用。

安装

🌐 Installation

Terminal
npx expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

🌐 Usage

基本文本字段

🌐 Basic text field

填充文本字段是默认的 Material3 文本输入样式。

🌐 A filled text field is the default Material3 text input style.

BasicTextFieldExample.tsx
import { useState } from 'react'; import { Host, TextField, Text } from '@expo/ui/jetpack-compose'; export default function BasicTextFieldExample() { const [value, setValue] = useState(''); return ( <Host matchContents> <TextField onValueChange={setValue}> <TextField.Label> <Text>Username</Text> </TextField.Label> </TextField> </Host> ); }

轮廓文本字段

🌐 Outlined text field

对于有边框轮廓而非填充背景的文本字段,请使用 OutlinedTextField

🌐 Use OutlinedTextField for a text field with a border outline instead of a filled background.

OutlinedTextFieldExample.tsx
import { useState } from 'react'; import { Host, OutlinedTextField, Text } from '@expo/ui/jetpack-compose'; export default function OutlinedTextFieldExample() { const [value, setValue] = useState(''); return ( <Host matchContents> <OutlinedTextField onValueChange={setValue}> <OutlinedTextField.Label> <Text>Email</Text> </OutlinedTextField.Label> <OutlinedTextField.Placeholder> <Text>you@example.com</Text> </OutlinedTextField.Placeholder> </OutlinedTextField> </Host> ); }

插槽

🌐 Slots

TextFieldOutlinedTextField 都支持 7 个可组合的插槽,这些插槽与 Compose API 匹配:LabelPlaceholderLeadingIconTrailingIconPrefixSuffixSupportingText

🌐 Both TextField and OutlinedTextField support 7 composable slots that match the Compose API: Label, Placeholder, LeadingIcon, TrailingIcon, Prefix, Suffix, and SupportingText.

TextFieldSlotsExample.tsx
import { useState } from 'react'; import { Host, TextField, Text } from '@expo/ui/jetpack-compose'; export default function TextFieldSlotsExample() { const [value, setValue] = useState(''); return ( <Host matchContents> <TextField onValueChange={setValue}> <TextField.Label> <Text>Price</Text> </TextField.Label> <TextField.Placeholder> <Text>0.00</Text> </TextField.Placeholder> <TextField.LeadingIcon> <Text>💰</Text> </TextField.LeadingIcon> <TextField.Prefix> <Text>$</Text> </TextField.Prefix> <TextField.Suffix> <Text>USD</Text> </TextField.Suffix> <TextField.SupportingText> <Text>Enter the amount</Text> </TextField.SupportingText> </TextField> </Host> ); }

键盘选项

🌐 Keyboard options

使用 keyboardOptions 属性来配置键盘类型、大写、自动纠正和输入法操作。

🌐 Use the keyboardOptions prop to configure the keyboard type, capitalization, auto-correct, and IME action.

KeyboardOptionsExample.tsx
import { useState } from 'react'; import { Host, TextField, Text } from '@expo/ui/jetpack-compose'; export default function KeyboardOptionsExample() { const [value, setValue] = useState(''); return ( <Host matchContents> <TextField onValueChange={setValue} singleLine keyboardOptions={{ keyboardType: 'email', capitalization: 'none', autoCorrectEnabled: false, imeAction: 'done', }}> <TextField.Label> <Text>Email</Text> </TextField.Label> </TextField> </Host> ); }

键盘操作

🌐 Keyboard actions

使用 keyboardActions 属性来处理 IME 操作按钮的按下事件。触发的回调取决于在 keyboardOptions 中设置的 imeAction。每个回调都会接收当前的文本值。

🌐 Use the keyboardActions prop to handle IME action button presses. The triggered callback depends on the imeAction set in keyboardOptions. Each callback receives the current text value.

KeyboardActionsExample.tsx
import { useState } from 'react'; import { Host, TextField, Text } from '@expo/ui/jetpack-compose'; export default function KeyboardActionsExample() { const [value, setValue] = useState(''); const [submitted, setSubmitted] = useState(''); return ( <Host matchContents> <TextField onValueChange={setValue} singleLine keyboardOptions={{ imeAction: 'search' }} keyboardActions={{ onSearch: text => setSubmitted(text), }}> <TextField.Label> <Text>Search</Text> </TextField.Label> </TextField> </Host> ); }

错误状态

🌐 Error state

isError 设置为在错误状态下显示文本字段。与 SupportingText 结合使用以显示错误消息。

🌐 Set isError to display the text field in an error state. Combine with SupportingText to show an error message.

ErrorStateExample.tsx
import { useState } from 'react'; import { Host, OutlinedTextField, Text } from '@expo/ui/jetpack-compose'; export default function ErrorStateExample() { const [value, setValue] = useState(''); const hasError = value.length > 0 && !value.includes('@'); return ( <Host matchContents> <OutlinedTextField onValueChange={setValue} isError={hasError} singleLine> <OutlinedTextField.Label> <Text>Email</Text> </OutlinedTextField.Label> <OutlinedTextField.SupportingText> <Text>{hasError ? 'Please enter a valid email' : 'Required'}</Text> </OutlinedTextField.SupportingText> </OutlinedTextField> </Host> ); }

命令参考

🌐 Imperative ref

使用引用以命令式地设置文本、聚焦或失焦文本字段。

🌐 Use a ref to imperatively set text, focus, or blur the text field.

ImperativeRefExample.tsx
import { useRef, useState } from 'react'; import { Host, TextField, TextFieldRef, Button, Row, Text, Column } from '@expo/ui/jetpack-compose'; import { padding } from '@expo/ui/jetpack-compose/modifiers'; export default function ImperativeRefExample() { const ref = useRef<TextFieldRef>(null); const [value, setValue] = useState(''); return ( <Host matchContents> <Column> <TextField ref={ref} onValueChange={setValue} singleLine> <TextField.Label> <Text>Name</Text> </TextField.Label> </TextField> <Row horizontalArrangement={{ spacedBy: 8 }} modifiers={[padding(8, 0, 0, 0)]}> <Button onClick={() => ref.current?.setText('Hello!')}> <Text>Set text</Text> </Button> <Button onClick={() => ref.current?.focus()}> <Text>Focus</Text> </Button> <Button onClick={() => ref.current?.blur()}> <Text>Blur</Text> </Button> </Row> </Column> </Host> ); }

应用接口

🌐 API

import { TextField, OutlinedTextField } from '@expo/ui/jetpack-compose';

Components

OutlinedTextField

Android

Type: React.Element<OutlinedTextFieldProps>

A Material3 OutlinedTextField with a transparent background and border outline.

OutlinedTextFieldProps

colors

Android
Optional • Type: TextFieldColors

Inherited Props

TextField

Android

Type: React.Element<TextFieldProps>

A Material3 TextField.

TextFieldProps

colors

Android
Optional • Type: TextFieldColors

Inherited Props

Types

TextFieldCapitalization

Android

Literal Type: string

Acceptable values are: 'none' | 'characters' | 'words' | 'sentences'

TextFieldColors

Android

Colors for TextField and OutlinedTextField. Maps to TextFieldColors in Compose, shared by both variants.

PropertyTypeDescription
cursorColor(optional)ColorValue
-
disabledContainerColor(optional)ColorValue
-
disabledIndicatorColor(optional)ColorValue
-
disabledLabelColor(optional)ColorValue
-
disabledLeadingIconColor(optional)ColorValue
-
disabledPlaceholderColor(optional)ColorValue
-
disabledPrefixColor(optional)ColorValue
-
disabledSuffixColor(optional)ColorValue
-
disabledSupportingTextColor(optional)ColorValue
-
disabledTextColor(optional)ColorValue
-
disabledTrailingIconColor(optional)ColorValue
-
errorContainerColor(optional)ColorValue
-
errorCursorColor(optional)ColorValue
-
errorIndicatorColor(optional)ColorValue
-
errorLabelColor(optional)ColorValue
-
errorLeadingIconColor(optional)ColorValue
-
errorPlaceholderColor(optional)ColorValue
-
errorPrefixColor(optional)ColorValue
-
errorSuffixColor(optional)ColorValue
-
errorSupportingTextColor(optional)ColorValue
-
errorTextColor(optional)ColorValue
-
errorTrailingIconColor(optional)ColorValue
-
focusedContainerColor(optional)ColorValue
-
focusedIndicatorColor(optional)ColorValue
-
focusedLabelColor(optional)ColorValue
-
focusedLeadingIconColor(optional)ColorValue
-
focusedPlaceholderColor(optional)ColorValue
-
focusedPrefixColor(optional)ColorValue
-
focusedSuffixColor(optional)ColorValue
-
focusedSupportingTextColor(optional)ColorValue
-
focusedTextColor(optional)ColorValue
-
focusedTrailingIconColor(optional)ColorValue
-
unfocusedContainerColor(optional)ColorValue
-
unfocusedIndicatorColor(optional)ColorValue
-
unfocusedLabelColor(optional)ColorValue
-
unfocusedLeadingIconColor(optional)ColorValue
-
unfocusedPlaceholderColor(optional)ColorValue
-
unfocusedPrefixColor(optional)ColorValue
-
unfocusedSuffixColor(optional)ColorValue
-
unfocusedSupportingTextColor(optional)ColorValue
-
unfocusedTextColor(optional)ColorValue
-
unfocusedTrailingIconColor(optional)ColorValue
-

TextFieldImeAction

Android

Literal Type: string

Acceptable values are: 'default' | 'none' | 'go' | 'search' | 'send' | 'previous' | 'next' | 'done'

TextFieldKeyboardActions

Android

Keyboard actions matching Compose KeyboardActions. The triggered callback depends on the imeAction in keyboardOptions.

PropertyTypeDescription
onDone(optional)(value: string) => void
-
onGo(optional)(value: string) => void
-
onNext(optional)(value: string) => void
-
onPrevious(optional)(value: string) => void
-
onSearch(optional)(value: string) => void
-
onSend(optional)(value: string) => void
-

TextFieldKeyboardOptions

Android

Keyboard options matching Compose KeyboardOptions.

PropertyTypeDescription
autoCorrectEnabled(optional)boolean
Default:true
capitalization(optional)TextFieldCapitalization
Default:'none'
imeAction(optional)TextFieldImeAction
Default:'default'
keyboardType(optional)TextFieldKeyboardType
Default:'text'

TextFieldKeyboardType

Android

Literal Type: string

Acceptable values are: 'text' | 'number' | 'email' | 'phone' | 'decimal' | 'password' | 'ascii' | 'uri' | 'numberPassword'

TextFieldRef

Android

Can be used for imperatively setting text and focus on the TextField component.

PropertyTypeDescription
blur() => Promise<void>
-
focus() => Promise<void>
-
setText(newText: string) => Promise<void>
-