TextInput — 정의, 텍스트 입력 및 React Native

React Native에서 TextInput이란

TextInput은 사용자가 기기 키보드를 사용하여 텍스트를 입력할 수 있게 해주는 React Native 컴포넌트입니다. 이는 등록 폼, 검색창, 메시지 입력 필드 및 사용자 입력이 필요한 모든 시나리오의 기본 구성 요소입니다. 웹 개발에서는 별도의 input 유형(text, email, password, search)이 존재하지만, React Native에서는 이러한 모든 변형이 다양한 props와 함께 단일 TextInput 컴포넌트를 통해 구현됩니다.

TextInput은 두 가지 작동 모드를 지원합니다: 제어(React 상태를 통해 관리) 및 비제어(ref 사용). 제어 모드에서는 필드 값이 컴포넌트 상태에 저장되고 onChangeText 콜백을 통해 업데이트됩니다. 이 접근 방식은 단일 진실 공급원을 제공하고 유효성 검사를 단순화하므로 대부분의 애플리케이션에 권장됩니다.

React Native Handling Text Input, 2024에 따르면, TextInput은 플랫폼에 자동으로 적응합니다: iOS에서는 네이티브 UITextField를, Android에서는 EditText를 사용합니다. 이는 추가 구성 없이 자동 완성, 자동 수정 및 시스템 메뉴(잘라내기/복사/붙여넣기)의 적절한 작동을 보장합니다.

TextInput 속성 및 API

TextInput은 입력, 외관 및 동작을 제어하기 위한 광범위한 props 세트를 제공합니다. 모든 props는 값 관리, 키보드 유형, 스타일링, 이벤트 및 플랫폼별 기능의 여러 범주로 나뉩니다.

값 관리 속성

value — 필드의 현재 값(제어 모드용). onChangeText — 텍스트가 변경될 때마다 호출되는 콜백. placeholder — 필드가 비어 있을 때 표시되는 힌트 텍스트. defaultValue — 비제어 모드용 초기 값. maxLength는 사용자가 입력할 수 있는 최대 문자 수를 제한합니다.

TextInput 이벤트

컴포넌트는 onFocus(필드가 포커스를 받음), onBlur(필드가 포커스를 잃음), onSubmitEditing(사용자가 Enter/Return을 누름), onKeyPress(키 누름)을 지원합니다. onEndEditing 이벤트는 포커스를 잃을 때 편집이 완료된 후 호출됩니다. 이러한 콜백을 통해 복잡한 유효성 검사 및 폼 제출 로직을 구현할 수 있습니다.

플랫폼별 속성

iOS: clearButtonMode(지우기 버튼), keyboardAppearance(밝은/어두운 키보드), returnKeyType(Return 버튼 유형), enablesReturnKeyAutomatically. Android: textContentType(자동 입력), underlineColorAndroid, inlineImageLeft. secureTextEntry는 비밀번호 입력을 위해 두 플랫폼에서 모두 작동합니다.

제어 입력 및 비제어 입력

React Native에서 TextInput은 두 가지 모드로 작동할 수 있습니다. 제어 모드에서는 React가 필드 값을 관리합니다: 상태에서 값을 전달하고 onChangeText를 통해 업데이트합니다. 비제어 모드에서는 React가 필드를 초기화만 하며, DOM과 유사한 값은 네이티브 컴포넌트 내부에 저장됩니다.

제어되는 TextInput

제어 모드는 입력 데이터의 유효성 검사, 필터링 또는 형식 지정이 필요한 모든 폼에 권장됩니다. 필드 상태는 React 컴포넌트 상태와 동기화되어 값에 대한 완전한 제어를 제공합니다.

const LoginForm = () => {
    const [email, setEmail] = useState('');
    const [password, setPassword] = useState('');

    return (
        <View>
            <TextInput
                placeholder="Email"
                value={email}
                onChangeText={setEmail}
                keyboardType="email-address"
                autoCapitalize="none"
            />
            <TextInput
                placeholder="Password"
                value={password}
                onChangeText={setPassword}
                secureTextEntry
                maxLength={32}
            />
        </View>
    );
};

이 예제에서는 두 필드 모두 제어 모드를 사용합니다. 이메일 필드는 email-address 키보드 유형을 가지며 자동 대문자 사용이 비활성화되어 있습니다. 비밀번호 필드는 secureTextEntry를 사용하여 입력 문자를 숨기고 maxLength를 통해 32자로 제한됩니다.

비제어 TextInput

비제어 모드는 유효성 검사나 입력에 대한 즉각적인 반응이 필요하지 않은 간단한 필드에 적합합니다. 필드 값은 폼 제출 시 ref를 통해 검색됩니다.

const SimpleSearch = () => {
    const inputRef = useRef(null);

    const handleSearch = () => {
        console.log(inputRef.current.value());
    };

    return (
        <TextInput
            ref={inputRef}
            placeholder="Search..."
            onSubmitEditing={handleSearch}
        />
    );
};

비제어 모드에서는 텍스트가 변경될 때마다 상태 동기화가 필요하지 않으므로 컴포넌트가 더 빠르게 렌더링됩니다. 그러나 실시간으로 입력을 필터링, 형식 지정 또는 유효성 검사하는 기능은 상실됩니다.

키보드 유형 및 플랫폼 기능

TextInput은 예상 입력 형식에 따라 레이아웃을 조정하는 다양한 키보드 유형을 지원합니다. 올바른 키보드 유형을 선택하면 사용자 경험이 향상되고 모바일 기기에서 입력 오류가 줄어듭니다.

iOS에서는 추가 유형 사용 가능: numbers-and-punctuation, twitter, web-search(음성 검색 포함). Android에서는 visible-password도 사용 가능(비밀번호 표시). 올바른 keyboardType 선택은 모바일 애플리케이션 UX의 중요한 측면입니다.

플랫폼 기능에는 autoCapitalize(첫 단어 자동 대문자), autoCorrect(자동 수정), spellCheck(맞춤법 검사), textContentType(iOS의 자동 입력)도 포함됩니다. 이러한 props는 각 플랫폼에서 다르게 작동하며 테스트가 필요합니다.

TextInput 실용 예제

두 가지 실제 시나리오를 살펴보겠습니다: 메시지 입력을 위한 여러 줄 필드와 마스크된 전화번호 입력 필드입니다. 둘 다 원하는 동작을 달성하기 위해 다양한 props와 함께 TextInput을 사용합니다.

예제 1: 메시지용 여러 줄 필드

긴 텍스트(댓글, 설명)를 입력하기 위해 TextInput은 multiline prop을 통해 여러 줄 모드로 전환됩니다. 이 모드에서는 필드가 세로로 커지며 줄 바꿈을 지원합니다.

const MessageInput = ({ onSend }) => {
    const [text, setText] = useState('');

    return (
        <TextInput
            style={styles.input}
            multiline
            numberOfLines={4}
            placeholder="Write a message..."
            value={text}
            onChangeText={setText}
            textAlignVertical="top"
        />
    );
};

multiline prop은 여러 줄 모드를 활성화하고, numberOfLines는 줄 단위 초기 높이를 설정합니다. textAlignVertical: 'top'은 텍스트를 위쪽에 정렬합니다(기본적으로 Android 여러 줄 TextInput은 텍스트를 세로로 가운데 정렬합니다).

예제 2: 전화번호 형식 지정 필드

전화번호를 입력할 때는 실시간 형식 지정이 자주 필요합니다. onChangeText를 정규 표현식과 결합하여 입력 마스크를 구현할 수 있습니다.

const PhoneInput = () => {
    const [phone, setPhone] = useState('');

    const formatPhone = (text) => {
        const cleaned = text.replace(/\D/g, '');
        if (cleaned.length <= 11) {
            return cleaned.replace(
                /(\d{1})(\d{3})(\d{3})(\d{2})(\d{2})/,
                '+$1 ($2) $3 $4 $5'
            );
        }
        return cleaned;
    };

    return (
        <TextInput
            keyboardType="phone-pad"
            value={phone}
            onChangeText={(t) => setPhone(formatPhone(t))}
            placeholder="+7 (999) 123 45 67"
            maxLength={20}
        />
    );
};

formatPhone 함수는 모든 숫자가 아닌 문자를 제거하고 번호를 표준 국제 형식으로 지정합니다. keyboardType: 'phone-pad'는 전화 키보드를 표시합니다. 이 접근 방식은 전화번호 입력을 위한 UX를 개선하고 형식 지정 오류를 방지합니다.