TextField

用于文本输入的 SwiftUI 文本字段组件。

iOS

tvOS

Bundled version:

~55.0.15

Expo UI TextField 与官方 SwiftUI TextField API 相匹配，支持单行和多行输入、键盘配置、提交处理，以及用于编程控制的命令式 ref。

🌐 Expo UI TextField matches the official SwiftUI TextField API and supports single-line and multiline input, keyboard configuration, submit handling, and an imperative ref for programmatic control.

安装

🌐 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

BasicTextFieldExample.tsx

import { useState } from 'react';
import { Host, TextField } from '@expo/ui/swift-ui';

export default function BasicTextFieldExample() {
  const [value, setValue] = useState('');

  return (
    <Host matchContents>
      <TextField placeholder="Username" onValueChange={setValue} />
    </Host>
  );
}

多行文本字段

🌐 Multiline text field

将 axis="vertical" 设置为允许文本字段垂直扩展。使用 lineLimit 修饰符来控制可见行数。在使用 Host matchContents 时，添加 fixedSize({ horizontal: false, vertical: true }) 以便文本字段在使用其理想高度的同时接受父容器的宽度。

🌐 Set axis="vertical" to allow the text field to expand vertically. Use the lineLimit modifier to control the visible line count. When using Host matchContents, add fixedSize({ horizontal: false, vertical: true }) so the text field accepts the parent's width while using its ideal height.

MultilineTextFieldExample.tsx

import { useState } from 'react';
import { Host, TextField } from '@expo/ui/swift-ui';
import { lineLimit, fixedSize } from '@expo/ui/swift-ui/modifiers';

export default function MultilineTextFieldExample() {
  const [value, setValue] = useState('');

  return (
    <Host matchContents>
      <TextField
        axis="vertical"
        placeholder="Tell us about yourself..."
        onValueChange={setValue}
        modifiers={[lineLimit(5), fixedSize({ horizontal: false, vertical: true })]}
      />
    </Host>
  );
}

键盘类型

🌐 Keyboard type

使用 keyboardType 修饰符来显示特定的键盘布局。

🌐 Use the keyboardType modifier to display a specific keyboard layout.

KeyboardTypeExample.tsx

import { useState } from 'react';
import { Host, TextField } from '@expo/ui/swift-ui';
import { keyboardType, autocorrectionDisabled } from '@expo/ui/swift-ui/modifiers';

export default function KeyboardTypeExample() {
  const [value, setValue] = useState('');

  return (
    <Host matchContents>
      <TextField
        placeholder="Email"
        onValueChange={setValue}
        modifiers={[keyboardType('email-address'), autocorrectionDisabled()]}
      />
    </Host>
  );
}

提交处理

🌐 Submit handling

使用 submitLabel 修饰符来自定义回车键，使用 onSubmit 来处理提交操作。

🌐 Use the submitLabel modifier to customize the return key and onSubmit to handle the submit action.

SubmitHandlingExample.tsx

import { useState } from 'react';
import { Host, TextField } from '@expo/ui/swift-ui';
import { submitLabel, onSubmit } from '@expo/ui/swift-ui/modifiers';

export default function SubmitHandlingExample() {
  const [value, setValue] = useState('');

  return (
    <Host matchContents>
      <TextField
        placeholder="Search..."
        onValueChange={setValue}
        modifiers={[submitLabel('search'), onSubmit(() => console.log('Submitted:', value))]}
      />
    </Host>
  );
}

命令参考

🌐 Imperative ref

使用 ref 以命令式方式设置文本、聚焦、失焦或选择文本。

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

ImperativeRefExample.tsx

import { useRef } from 'react';
import { Host, TextField, TextFieldRef, Button, HStack, VStack } from '@expo/ui/swift-ui';
import { buttonStyle } from '@expo/ui/swift-ui/modifiers';

export default function ImperativeRefExample() {
  const ref = useRef<TextFieldRef>(null);

  return (
    <Host matchContents>
      <VStack>
        <TextField ref={ref} defaultValue="Select me!" placeholder="Imperative field" />
        <HStack spacing={12}>
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.focus()}
            label="Focus"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.blur()}
            label="Blur"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.setText('SwiftUI rocks!')}
            label="Set Text"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.setSelection(0, 7)}
            label="Select"
          />
        </HStack>
      </VStack>
    </Host>
  );
}

应用接口

🌐 API

import { TextField } from '@expo/ui/swift-ui';

Component

`TextField`

iOS

tvOS

Type: React.Element<TextFieldProps>

Renders a SwiftUI TextField.

TextFieldProps

`autoFocus`

iOS

tvOS

Optional • Type: boolean • Default: false

If true, the text field will be focused automatically when mounted.

`axis`

iOS

tvOS

Optional • Literal type: string • Default: 'horizontal'

The axis along which the text field grows when content exceeds a single line.

'horizontal' — single line (default).
'vertical' — expands vertically for multiline content. Use lineLimit modifier to cap visible lines.

Acceptable values are: 'horizontal' | 'vertical'

`defaultValue`

iOS

tvOS

Optional • Type: string

Initial value displayed when mounted. Uncontrolled — change key to reset.

`onFocusChange`

iOS

tvOS

Optional • Type: (focused: boolean) => void

A callback triggered when the field gains or loses focus.

`onSelectionChange`

iOS 18.0+ tvos 18.0+

Optional • Type:

({ start, end }: {
  end: number, 
  start: number
}) => void

A callback triggered when user selects text in the TextField.

`onValueChange`

iOS

tvOS

Optional • Type: (value: string) => void

A callback triggered when the text value changes.

`placeholder`

iOS

tvOS

Optional • Type: string

A text that is displayed when the field is empty.

`ref`

iOS

tvOS

Optional • Type: Ref<TextFieldRef>

Inherited Props

CommonViewModifierProps

Types

`TextFieldRef`

iOS

tvOS

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

Property	Type	Description
blur	`() => Promise<void>`	-
focus	`() => Promise<void>`	-
setSelection	`(start: number, end: number) => Promise<void>`	Only for: iOS 18.0+ tvos 18.0+ Programmatically select text using start and end indices.
setText	`(newText: string) => Promise<void>`	-