TextField

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

iOS

tvOS

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~58.0.1

如需跨平台使用，请参阅通用的 TextInput ——它会根据平台渲染相应的原生组件。

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

安装

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

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

用法

非受控文本字段

将 useNativeState observable 绑定到 text。字段会自行跟踪用户输入，你可以从 textState.value 读取当前值。

BasicTextFieldExample.tsx

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

export default function BasicTextFieldExample() {
  const textState = useNativeState('');

  // 文本字段会扩展到分配给它的宽度，因此请为 host 指定尺寸。
  return (
    <Host style={{ flex: 1 }}>
      <TextField placeholder="Username" text={textState} />
    </Host>
  );
}

受控文本字段

传入一个 onTextChange worklet 来转换或验证输入，并将结果写回 useNativeState observable 状态。下面的示例会在输入时将文本转换为大写。

注意： Worklet 需要安装 react-native-worklets。

ControlledTextFieldExample.tsx

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

export default function ControlledTextFieldExample() {
  const text = useNativeState('');

  const handleTextChange = useCallback(
    (value: string) => {
      'worklet';
      text.value = value.toUpperCase();
    },
    [text]
  );

  return (
    <Host style={{ flex: 1 }}>
      <TextField
        placeholder="Name"
        text={text}
        onTextChange={handleTextChange}
      />
    </Host>
  );
}

多行文本字段

设置 axis="vertical" 以允许文本字段纵向扩展。使用 lineLimit 修饰符控制可见行数。为 Host 指定明确的尺寸，以便字段在其中按需扩展宽度。

MultilineTextFieldExample.tsx

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

export default function MultilineTextFieldExample() {
  const textState = useNativeState('');

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

键盘类型

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

KeyboardTypeExample.tsx

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

export default function KeyboardTypeExample() {
  const textState = useNativeState('');

  return (
    <Host style={{ flex: 1 }}>
      <TextField
        placeholder="Email"
        text={textState}
        modifiers={[
          keyboardType('email-address'),
          autocorrectionDisabled(),
        ]}
      />
    </Host>
  );
}

提交处理

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

SubmitHandlingExample.tsx

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

export default function SubmitHandlingExample() {
  const textState = useNativeState('');

  return (
    <Host style={{ flex: 1 }}>
      <TextField
        placeholder="Search..."
        text={textState}
        modifiers={[
          submitLabel('search'),
          onSubmit(() =>
            console.log('Submitted:', textState.value)
          ),
        ]}
      />
    </Host>
  );
}

命令式 ref

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

注意： setSelection 需要 iOS 18.0+ / tvOS 18.0+。其他 ref 方法在所有受支持的版本上均可使用。

ImperativeRefExample.tsx

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

export default function ImperativeRefExample() {
  const ref = useRef<TextFieldRef>(null);
  const textState = useNativeState('Select me!');

  return (
    <Host style={{ flex: 1 }}>
      <VStack spacing={12}>
        <TextField
          ref={ref}
          text={textState}
          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"
          />
        </HStack>
        <HStack spacing={12}>
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.setText('SwiftUI rocks!')}
            label="Set text"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.clear()}
            label="Clear"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.setSelection(0, 7)}
            label="Select"
          />
        </HStack>
      </VStack>
    </Host>
  );
}

Worklet 文本遮罩

当 onTextChange 标记了 'worklet' 指令时，它会在 UI 线程上同步运行，因此回调中对 useNativeState observable 的写入会在下一帧之前生效。输入文本和遮罩后的文本之间不会出现闪烁。下面的示例会在用户输入时对电话号码进行遮罩，并从 worklet 写入 text 和 selection，使光标停留在格式化后文本的末尾。

注意： Worklet 需要安装 react-native-worklets。selection 属性需要 iOS 18.0+ / tvOS 18.0+。在较旧版本上，worklet 仍可更新文本，但无法定位光标。

WorkletPhoneMaskExample.tsx

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

export default function WorkletPhoneMaskExample() {
  const phone = useNativeState('');
  const selection = useNativeState({ start: 0, end: 0 });

  const handleTextChange = useCallback(
    (v: string) => {
      'worklet';
      const digits = v.replace(/\D/g, '').slice(0, 10);
      let formatted = digits;
      if (digits.length > 6) {
        formatted = `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
      } else if (digits.length > 3) {
        formatted = `(${digits.slice(0, 3)}) ${digits.slice(3)}`;
      }
      if (formatted !== v) {
        phone.value = formatted;
        // 示例中将光标移至末尾。实际遮罩需要更智能的光标处理。
        selection.value = {
          start: formatted.length,
          end: formatted.length,
        };
      }
    },
    [phone, selection]
  );

  return (
    <Host style={{ flex: 1 }}>
      <TextField
        text={phone}
        selection={selection}
        placeholder="(555) 123-4567"
        modifiers={[keyboardType('phone-pad')]}
        onTextChange={handleTextChange}
      />
    </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'

`children`

iOS

tvOS

Optional • Type: ReactNode

Slot children — supports <TextField.Placeholder> with a <Text> child (any text-styling modifiers on that Text are preserved as the placeholder's styling).

`maxLength`

iOS

tvOS

Optional • Type: number

Maximum number of characters allowed. Truncates natively as the user types.

`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:

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

A callback triggered when the text selection range changes.

`onTextChange`

iOS

tvOS

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

A callback triggered when the text value changes.

If the callback is marked with the 'worklet' directive, it runs synchronously on the UI thread; otherwise it is delivered asynchronously as a regular JS event.

`placeholder`

iOS

tvOS

Optional • Type: string

A text that is displayed when the field is empty.

`ref`

iOS

tvOS

Optional • Type: Ref<TextFieldRef>

`selection`

iOS 18.0+ tvos 18.0+

Optional • Type: ObservableState<TextFieldSelection>

Observable state the field writes the current selection to. Create with useNativeState<TextFieldSelection>({ start: 0, end: 0 }). Use ref.setSelection(start, end) to set programmatically.

`text`

iOS

tvOS

Optional • Type: ObservableState<string>

An observable state that holds the current text. Create one with useNativeState('') or useNativeState('initial value'). If omitted, the field manages its own internal state.

Inherited props

CommonViewModifierProps

Types

`ObservableState`

iOS

tvOS

Observable state shared between JavaScript and native views (Jetpack Compose on Android and SwiftUI on iOS).

Type: SharedObject extended by:

Property	Type	Description
onChange	`[listener] \| null`	A single listener invoked on the native UI runtime whenever the value changes (after iOS `didSet` and Android's setter). Assigning replaces the previous listener; assign `null` to clear. The initial value does not fire `onChange`. The callback must be a worklet so it can run synchronously on the UI thread. Attach it inside `useEffect` and clear it in the cleanup so the listener lifecycle matches the component lifecycle. Example `const state = useNativeState(0); useEffect(() => { state.onChange = (value) => { 'worklet'; console.log('changed to', value); }; }, []);`
value	`T`	The current value. Writes from a UI worklet are synchronous and immediately readable. Writes from the JS thread are scheduled to the UI thread asynchronously, the new value is not readable until the update has been applied. Prefer writing from a worklet when you need synchronous updates
get	`() => T`	Reads the current value. A React Compiler compliant alternative to reading `.value`
set	`(value: T) => void`	Writes a new value. A React Compiler-compliant alternative to assigning `.value`

`TextFieldRef`

iOS

tvOS

Can be used for imperatively focusing and setting text/selection on the TextField component.

Property	Type	Description
blur	`() => Promise<void>`	-
clear	`() => Promise<void>`	Clear the current text.
focus	`() => Promise<void>`	-
setSelection	`(start: number, end: number) => Promise<void>`	Only for: iOS 18.0+ tvos 18.0+ Programmatically set the selection range.
setText	`(newText: string) => Promise<void>`	-

`TextFieldSelection`

iOS

tvOS

Selection range — start and end are character offsets into the field's text.

Property	Type	Description
end	`number`	-
start	`number`	-