This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 55).
TextField
用于原生 Material3 文本输入的 Jetpack Compose TextField 组件。
For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.
Expo UI 提供两个文本字段组件,与官方 Jetpack Compose TextField API 保持一致:TextField(填充式)和 OutlinedTextField(描边式边框)。这两个变体共享相同的 props,并支持用于 label、placeholder、图标、前缀、后缀和辅助文本的可组合 slot 子组件。
| 类型 | 外观 | 目的 |
|---|---|---|
| 填充式 | 实心背景,底部有一条指示线。 | 遵循 Material3 设计的默认文本输入样式。适用于大多数表单和输入字段。 |
| 描边式 | 透明背景,带边框轮廓。 | 提供明显视觉边界的替代样式。当填充式字段与背景融为一体时使用。 |
安装
- npx expo install @expo/uiIf you are installing this in an existing React Native app, make sure to install expo in your project.
使用
基本文本字段
填充式文本字段是默认的 Material3 文本输入样式。
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>用户名</Text> </TextField.Label> </TextField> </Host> ); }
描边文本字段
当你想要带边框轮廓而不是填充背景的文本字段时,请使用 OutlinedTextField。
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>邮箱</Text> </OutlinedTextField.Label> <OutlinedTextField.Placeholder> <Text>you@example.com</Text> </OutlinedTextField.Placeholder> </OutlinedTextField> </Host> ); }
插槽
TextField 和 OutlinedTextField 都支持 7 个与 Compose API 对应的可组合插槽:Label、Placeholder、LeadingIcon、TrailingIcon、Prefix、Suffix 和 SupportingText。
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>价格</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>输入金额</Text> </TextField.SupportingText> </TextField> </Host> ); }
键盘选项
使用 keyboardOptions 属性来配置键盘类型、首字母大写、自动更正和 IME 操作。
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>邮箱</Text> </TextField.Label> </TextField> </Host> ); }
键盘操作
使用 keyboardActions 属性来处理 IME 操作按钮的按下。触发的回调取决于 keyboardOptions 中设置的 imeAction。每个回调都会接收当前文本值。
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>搜索</Text> </TextField.Label> </TextField> </Host> ); }
错误状态
设置 isError 以将文本字段显示为错误状态。结合 SupportingText 可显示错误消息。
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>邮箱</Text> </OutlinedTextField.Label> <OutlinedTextField.SupportingText> <Text>{hasError ? '请输入有效的邮箱地址' : '必填'}</Text> </OutlinedTextField.SupportingText> </OutlinedTextField> </Host> ); }
命令式 ref
使用 ref 以命令式方式设置文本、聚焦或取消聚焦文本字段。
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>姓名</Text> </TextField.Label> </TextField> <Row horizontalArrangement={{ spacedBy: 8 }} modifiers={[padding(8, 0, 0, 0)]}> <Button onClick={() => ref.current?.setText('你好!')}> <Text>设置文本</Text> </Button> <Button onClick={() => ref.current?.focus()}> <Text>聚焦</Text> </Button> <Button onClick={() => ref.current?.blur()}> <Text>失焦</Text> </Button> </Row> </Column> </Host> ); }
API
import { TextField, OutlinedTextField } from '@expo/ui/jetpack-compose';
Components
Type: React.Element<OutlinedTextFieldProps>
A Material3 OutlinedTextField with a transparent background and border outline.
TextFieldColorsType: React.Element<TextFieldProps>
A Material3 TextField.
TextFieldColorsTypes
Literal Type: string
Acceptable values are: 'none' | 'characters' | 'words' | 'sentences'
Colors for TextField and OutlinedTextField.
Maps to TextFieldColors in Compose, shared by both variants.
| Property | Type | Description |
|---|---|---|
| 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 | - |
Literal Type: string
Acceptable values are: 'default' | 'none' | 'go' | 'search' | 'send' | 'previous' | 'next' | 'done'
Keyboard actions matching Compose KeyboardActions.
The triggered callback depends on the imeAction in keyboardOptions.
| Property | Type | Description |
|---|---|---|
| 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 | - |
Keyboard options matching Compose KeyboardOptions.
| Property | Type | Description |
|---|---|---|
| autoCorrectEnabled(optional) | boolean | Default: true |
| capitalization(optional) | TextFieldCapitalization | Default: 'none' |
| imeAction(optional) | TextFieldImeAction | Default: 'default' |
| keyboardType(optional) | TextFieldKeyboardType | Default: 'text' |
Literal Type: string
Acceptable values are: 'text' | 'number' | 'email' | 'phone' | 'decimal' | 'password' | 'ascii' | 'uri' | 'numberPassword'