Formatar automaticamente um número de telefone em um campo de texto

Você pode formatar automaticamente um número de telefone em um campo de texto no app, economizando o tempo dos usuários ao formatar o número de telefone conforme eles digitam os dígitos. Siga estas orientações para formatar automaticamente um número de telefone:

  • Crie o campo de texto.
  • Formatar automaticamente um número no campo de texto.

Compatibilidade de versões

Essa implementação exige que o minSDK do projeto seja definido como nível 21 da API ou mais recente.

Dependências

Criar o campo de texto

Primeiro, configure o TextField. Este exemplo mostra um número de telefone formatado de acordo com o plano de numeração da América do Norte (NANP).NanpVisualTransformation formata uma string bruta de números para NANP, por exemplo. 1234567890 para (123) 456-7890.

@Composable
fun PhoneNumber() {
    var phoneNumber by rememberSaveable { mutableStateOf("") }
    val numericRegex = Regex("[^0-9]")
    TextField(
        value = phoneNumber,
        onValueChange = {
            // Remove non-numeric characters.
            val stripped = numericRegex.replace(it, "")
            phoneNumber = if (stripped.length >= 10) {
                stripped.substring(0..9)
            } else {
                stripped
            }
        },
        label = { Text("Enter Phone Number") },
        visualTransformation = NanpVisualTransformation(),
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number)
    )
}

Pontos principais sobre o código

  • Um elemento combinável TextField em que o onValueChange usa uma expressão regular para remover todos os caracteres não numéricos e limita o comprimento a um máximo de 10 caracteres antes de atualizar o estado phoneNumber.
  • O TextField tem uma instância VisualTransformation personalizada definida no atributo visualTransformation. NanpVisualTransformation, a classe personalizada instanciada aqui, é definida na próxima seção.

Formatar automaticamente um número no campo de texto

Para formatar uma string bruta de números, use a implementação da classe NanpVisualTransformation personalizada:

class NanpVisualTransformation : VisualTransformation {

    override fun filter(text: AnnotatedString): TransformedText {
        val trimmed = if (text.text.length >= 10) text.text.substring(0..9) else text.text

        var out = if (trimmed.isNotEmpty()) "(" else ""

        for (i in trimmed.indices) {
            if (i == 3) out += ") "
            if (i == 6) out += "-"
            out += trimmed[i]
        }
        return TransformedText(AnnotatedString(out), phoneNumberOffsetTranslator)
    }

    private val phoneNumberOffsetTranslator = object : OffsetMapping {

        override fun originalToTransformed(offset: Int): Int =
            when (offset) {
                0 -> offset
                // Add 1 for opening parenthesis.
                in 1..3 -> offset + 1
                // Add 3 for both parentheses and a space.
                in 4..6 -> offset + 3
                // Add 4 for both parentheses, space, and hyphen.
                else -> offset + 4
            }

        override fun transformedToOriginal(offset: Int): Int =
            when (offset) {
                0 -> offset
                // Subtract 1 for opening parenthesis.
                in 1..5 -> offset - 1
                // Subtract 3 for both parentheses and a space.
                in 6..10 -> offset - 3
                // Subtract 4 for both parentheses, space, and hyphen.
                else -> offset - 4
            }
    }
}

Pontos principais sobre o código

  • A função filter() insere os caracteres de formatação não numéricos nos lugares apropriados.
  • O objeto phoneNumberOffsetTranslator contém dois métodos. Um mapeia os deslocamentos entre a string original e a formatada, e o outro faz o mapeamento reverso. Esses mapeamentos permitem pular os caracteres de formatação quando o usuário muda a posição do cursor no campo de texto.
  • A string formatada e o phoneNumberOffsetTranslator são usados como argumentos para uma instância TransformedText que é retornada e usada pelo TextField para realizar a formatação.

Resultados

Um número de telefone formatado automaticamente no campo de texto
Figura 1. Um número de telefone formatado automaticamente no campo de texto.

Coleções que contêm este guia

Este guia faz parte destas coleções selecionadas de guias rápidos que abrangem metas mais amplas de desenvolvimento para Android:

O texto é uma peça central de qualquer interface. Descubra maneiras diferentes de apresentar texto no app para oferecer uma experiência agradável ao usuário.
Aprenda a implementar maneiras de os usuários interagirem com seu app inserindo texto e usando outras formas de entrada.

Tem dúvidas ou feedback?

Acesse a página de perguntas frequentes e saiba mais sobre os guias rápidos ou entre em contato e conte o que você pensa.