This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 55).

TextField

一个用于文本输入的 SwiftUI TextField 组件。

iOS

tvOS

GitHub

npm

更新日志

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

安装

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.

用法

基本文本框

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="用户名" onValueChange={setValue} />
    </Host>
  );
}

多行文本框

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

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="请告诉我们关于你自己的信息..."
        onValueChange={setValue}
        modifiers={[lineLimit(5), fixedSize({ horizontal: false, vertical: true })]}
      />
    </Host>
  );
}

键盘类型

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

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="邮箱"
        onValueChange={setValue}
        modifiers={[keyboardType('email-address'), autocorrectionDisabled()]}
      />
    </Host>
  );
}

提交处理

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

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="搜索..."
        onValueChange={setValue}
        modifiers={[submitLabel('search'), onSubmit(() => console.log('已提交:', value))]}
      />
    </Host>
  );
}

命令式 ref

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

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="选中我！" placeholder="命令式字段" />
        <HStack spacing={12}>
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.focus()}
            label="聚焦"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.blur()}
            label="失焦"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.setText('SwiftUI 很棒！')}
            label="设置文本"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.setSelection(0, 7)}
            label="选择"
          />
        </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>`	-