تنسيق رقم هاتف تلقائيًا في حقل نصي

يمكنك تنسيق رقم هاتف تلقائيًا في حقل نصي في تطبيقك، ما يوفّر وقت المستخدمين من خلال تنسيق رقم الهاتف أثناء إدخال الأرقام. اتّبِع الإرشادات التالية لتنسيق رقم الهاتف تلقائيًا:

  • أنشئ حقل النص.
  • تنسيق رقم تلقائيًا في حقل النص

التوافق مع الإصدارات

يتطلّب هذا التنفيذ ضبط minSDK في مشروعك على المستوى 21 من واجهة برمجة التطبيقات أو مستوى أعلى.

التبعيات

إنشاء حقل النص

أولاً، اضبط TextField. يوضّح هذا المثال رقم هاتف منسَّق وفقًا لخطة الترقيم في أمريكا الشمالية (NANP).NanpVisualTransformation ينسّق سلسلة أرقام أولية وفقًا لخطة NANP، مثلاً: ‫1234567890 إلى ‎ (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)
    )
}

نقاط أساسية حول الرمز

  • TextField عنصر قابل للإنشاء حيث يستخدم onValueChange تعبيرًا عاديًا لإزالة جميع الأحرف غير الرقمية ويحدّ من الطول إلى 10 أحرف كحد أقصى قبل تعديل حالة phoneNumber.
  • يحتوي TextField على مثيل VisualTransformation مخصّص تم ضبطه على السمة visualTransformation. يتم تعريف NanpVisualTransformation، وهو فئة مخصّصة تم إنشاء مثيل لها هنا، في القسم التالي.

تنسيق رقم تلقائيًا في حقل النص

لتنسيق سلسلة أرقام أولية، استخدِم تنفيذ الفئة custom NanpVisualTransformation:

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

نقاط أساسية حول الرمز

  • تُدرِج الدالة filter() أحرف التنسيق غير الرقمية في المواضع المناسبة.
  • يحتوي العنصر phoneNumberOffsetTranslator على طريقتَين. يحدد أحدهما الإزاحات بين السلسلة الأصلية والسلسلة المنسَّقة، بينما يحدد الآخر الإزاحات في الاتجاه المعاكس. تتيح عمليات الربط هذه تخطّي أحرف التنسيق عندما يغيّر المستخدم موقع المؤشر في حقل النص.
  • يتم استخدام السلسلة المنسَّقة وphoneNumberOffsetTranslator كمعلَمات لمثيل TransformedText الذي يتم عرضه واستخدامه بواسطة TextField لإجراء عملية التنسيق.

النتائج

رقم هاتف منسَّق تلقائيًا في حقل النص
الشكل 1. رقم هاتف منسَّق تلقائيًا في حقل النص

المجموعات التي تتضمّن هذا الدليل

يشكّل هذا الدليل جزءًا من مجموعات "الدليل السريع" المنسّقة التي تغطي أهدافًا أوسع لتطوير تطبيقات Android:

يشكّل النص جزءًا أساسيًا من أي واجهة مستخدم. تعرَّف على الطرق المختلفة التي يمكنك من خلالها عرض النص في تطبيقك لتقديم تجربة مستخدم ممتعة.
تعرَّف على كيفية تنفيذ طرق تتيح للمستخدمين التفاعل مع تطبيقك من خلال إدخال نص واستخدام وسائل إدخال أخرى.

هل لديك أسئلة أو ملاحظات؟

يمكنك الانتقال إلى صفحة الأسئلة الشائعة والاطّلاع على الأدلة السريعة أو التواصل معنا وإعلامنا بأفكارك.