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

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

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

النتائج

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

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

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

الطلبات التابعة

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

أولاً، اضبط TextField. يعرض هذا المثال رقم هاتف منسَّقًا وفقًا لخطة الترقيم في أمريكا الشمالية (NANP). وتنسِّق السمة NanpVisualTransformation سلسلة أرقام أولية وفقًا لخطة الترقيم في أمريكا الشمالية، مثلاً: من 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، وهي الفئة المخصّصة التي تم إنشاء مثيل لها هنا، في القسم التالي.

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

لتنسيق سلسلة أرقام أولية، استخدِم تنفيذ الفئة المخصّصة 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 لإجراء التنسيق.

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

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

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

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

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