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

SecureField

一个用于密码输入的 SwiftUI SecureField 组件。

iOS

tvOS

Included in Expo Go

GitHub

npm

更新日志

Expo UI SecureField 与官方 SwiftUI SecureField API 保持一致，并提供一个可对密码及其他敏感文本的用户输入进行掩码处理的文本字段。

安装

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.

用法

基本安全字段

BasicSecureFieldExample.tsx

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

export default function BasicSecureFieldExample() {
  const [password, setPassword] = useState('');

  return (
    <Host matchContents>
      <SecureField placeholder="密码" onValueChange={setPassword} />
    </Host>
  );
}

提交处理

使用 submitLabel 和 onSubmit 修饰符来处理来自键盘的表单提交。

SecureFieldSubmitExample.tsx

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

export default function SecureFieldSubmitExample() {
  const [password, setPassword] = useState('');

  return (
    <Host matchContents>
      <SecureField
        placeholder="密码"
        onValueChange={setPassword}
        modifiers={[submitLabel('done'), onSubmit(() => console.log('登录已提交'))]}
      />
    </Host>
  );
}

命令式 ref

使用 ref 以命令式方式设置安全字段的文本、聚焦或失焦。

ImperativeSecureFieldExample.tsx

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

export default function ImperativeSecureFieldExample() {
  const ref = useRef<SecureFieldRef>(null);

  return (
    <Host matchContents>
      <VStack>
        <SecureField ref={ref} 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('secret123')}
            label="设置文本"
          />
        </HStack>
      </VStack>
    </Host>
  );
}

API

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

Component

`SecureField`

iOS

tvOS

Type: React.Element<SecureFieldProps>

Renders a SwiftUI SecureField for password input.

SecureFieldProps

`autoFocus`

iOS

tvOS

Optional • Type: boolean • Default: false

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

`children`

iOS

tvOS

Optional • Type: React.ReactNode

Slot children - supports <SecureField.Placeholder> with a <Text> child

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

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

`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

`SecureFieldRef`

iOS

tvOS

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

Property	Type	Description
blur	`() => Promise<void>`	-
clear	`() => Promise<void>`	Clear the current text.
focus	`() => Promise<void>`	-
setText	`(newText: string) => Promise<void>`	-