TextInput — o que é, entrada de texto e React Native

O que é TextInput no React Native

TextInput é um componente React Native que permite aos usuários inserir texto usando o teclado do dispositivo. É o principal bloco de construção para formulários de registro, barras de pesquisa, campos de entrada de mensagens e qualquer outro cenário que exija entrada do usuário. Ao contrário do desenvolvimento web, onde existem tipos de input separados (text, email, password, search), no React Native todas essas variantes são implementadas através de um único componente TextInput com diferentes props.

O TextInput suporta dois modos de operação: controlado (gerenciado através do estado React) e não controlado (usando uma ref). No modo controlado, o valor do campo é armazenado no estado do componente e atualizado através do callback onChangeText. Esta abordagem é recomendada para a maioria das aplicações, pois fornece uma única fonte de verdade e simplifica a validação.

De acordo com React Native Handling Text Input, 2024, o TextInput se adapta automaticamente à plataforma: no iOS usa UITextField nativo, no Android — EditText. Isso garante o funcionamento adequado do preenchimento automático, autocorreção e menus do sistema (recortar/copiar/colar) sem configuração adicional.

Propriedades e API do TextInput

TextInput fornece um conjunto extenso de props para controlar a entrada, aparência e comportamento. Todas as props são divididas em várias categorias: gerenciamento de valor, tipo de teclado, estilo, eventos e recursos específicos da plataforma.

Props de gerenciamento de valor

value — o valor atual do campo (para modo controlado). onChangeText — callback invocado a cada alteração de texto. placeholder — texto de dica exibido quando o campo está vazio. defaultValue — valor inicial para modo não controlado. maxLength limita o número máximo de caracteres que o usuário pode inserir.

Eventos do TextInput

O componente suporta onFocus (campo recebeu foco), onBlur (campo perdeu foco), onSubmitEditing (usuário pressionou Enter/Return), onKeyPress (pressionamento de tecla). O evento onEndEditing é chamado após a conclusão da edição ao perder o foco. Esses callbacks permitem implementar lógica complexa de validação e envio de formulários.

Props específicos da plataforma

No iOS: clearButtonMode (botão de limpar), keyboardAppearance (teclado claro/escuro), returnKeyType (tipo do botão Return), enablesReturnKeyAutomatically. No Android: textContentType (preenchimento automático), underlineColorAndroid, inlineImageLeft. secureTextEntry funciona em ambas as plataformas para entrada de senhas.

Entrada controlada e não controlada

No React Native, o TextInput pode funcionar em dois modos. No modo controlado, o React gerencia o valor do campo: você passa o valor do estado e o atualiza através do onChangeText. No modo não controlado, o React apenas inicializa o campo, e o valor semelhante ao DOM é armazenado dentro do componente nativo.

TextInput controlado

O modo controlado é recomendado para todos os formulários que exigem validação, filtragem ou formatação dos dados de entrada. O estado do campo é sincronizado com o estado do componente React, dando controle total sobre o valor.

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>
    );
};

Neste exemplo, ambos os campos usam o modo controlado. O campo de email tem o tipo de teclado email-address e a capitalização automática desativada. O campo de senha usa secureTextEntry para ocultar os caracteres de entrada e está limitado a 32 caracteres através de maxLength.

TextInput não controlado

O modo não controlado é adequado para campos simples que não exigem validação ou reação imediata à entrada. O valor do campo é obtido através de uma ref no momento do envio do formulário.

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

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

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

No modo não controlado, o componente renderiza mais rápido, pois não requer sincronização de estado a cada alteração de texto. No entanto, você perde a capacidade de filtrar, formatar ou validar a entrada em tempo real.

Tipos de teclado e recursos da plataforma

TextInput suporta vários tipos de teclado que adaptam o layout ao formato de entrada esperado. Escolher o tipo de teclado correto melhora a experiência do usuário e reduz erros de entrada em dispositivos móveis.

No iOS, tipos adicionais estão disponíveis: numbers-and-punctuation, twitter, web-search (com pesquisa por voz). No Android, também está disponível visible-password (mostra a senha). Escolher o keyboardType correto é um aspecto importante da UX de aplicativos móveis.

Os recursos da plataforma também incluem autoCapitalize (capitalização automática da primeira palavra), autoCorrect (autocorreção), spellCheck (verificação ortográfica), textContentType (preenchimento automático no iOS). Esses props funcionam de maneira diferente em cada plataforma e exigem teste.

Exemplos práticos com TextInput

Vamos considerar dois cenários reais: um campo multilinha para entrada de mensagens e um campo com máscara para número de telefone. Ambos usam TextInput com diferentes props para alcançar o comportamento desejado.

Exemplo 1: Campo multilinha para mensagem

Para inserir texto longo (comentários, descrições), o TextInput muda para o modo multilinha através da prop multiline. Neste modo, o campo cresce verticalmente e suporta quebras de linha.

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"
        />
    );
};

A prop multiline ativa o modo multilinha, numberOfLines define a altura inicial em linhas. textAlignVertical: 'top' alinha o texto ao topo (por padrão, no Android o TextInput multilinha centraliza o texto verticalmente).

Exemplo 2: Campo com formatação de número de telefone

Para inserir um número de telefone, a formatação em tempo real é frequentemente necessária. Combinando onChangeText com expressões regulares, você pode implementar uma máscara de entrada.

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}
        />
    );
};

A função formatPhone remove todos os caracteres não numéricos e formata o número em um formato internacional padrão. keyboardType: 'phone-pad' exibe o teclado telefônico. Esta abordagem melhora a UX para inserção de números de telefone e previne erros de formatação.