تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يمكنك تنسيق رقم هاتف تلقائيًا في حقل نصي في تطبيقك، ما يوفر للمستخدمين
الوقت من خلال تنسيق رقم الهاتف أثناء إدخال الأرقام. اتّبِع هذه الإرشادات
لتنسيق رقم هاتف تلقائيًا:
أنشئ حقل النص.
تنسيق رقم تلقائيًا في حقل النص
توافق الإصدار
يتطلّب هذا التنفيذ ضبط الحد الأدنى من إصدار حزمة SDK لمشروعك على المستوى 21 من واجهة برمجة التطبيقات أو
إصدار أحدث.
التبعيات
أنشئ الحقل النصي.
أولاً، عليك ضبط TextField. يعرض هذا المثال رقم هاتف
منسَّقًا وفقًا لخطة الترقيم في أمريكا الشمالية
(NANP).NanpVisualTransformation تنسيق سلسلة أرقام أولية إلى NANP، على سبيل المثال:
1234567890 إلى (123) 456-7890
TextField قابلة للتجميع حيث يستخدم onValueChange تعبيرًا عاديًا
لإزالة جميع الأحرف غير الرقمية وحصر الطول بحد أقصى
10 أحرف قبل تعديل حالة phoneNumber.
يحتوي العنصر TextField على مثيل مخصّص من VisualTransformation تم ضبطه على السمة
visualTransformation. تم تحديد NanpVisualTransformation، وهو
الفئة المخصّصة التي تمّ إنشاؤها هنا، في القسم التالي.
تنسيق رقم تلقائيًا في حقل النص
لتنسيق سلسلة أرقام أولية، استخدِم تنفيذ فئة
NanpVisualTransformation المخصّصة:
classNanpVisualTransformation:VisualTransformation{overridefunfilter(text:AnnotatedString):TransformedText{valtrimmed=if(text.text.length>=10)text.text.substring(0..9)elsetext.textvarout=if(trimmed.isNotEmpty())"("else""for(iintrimmed.indices){if(i==3)out+=") "if(i==6)out+="-"out+=trimmed[i]}returnTransformedText(AnnotatedString(out),phoneNumberOffsetTranslator)}privatevalphoneNumberOffsetTranslator=object:OffsetMapping{overridefunoriginalToTransformed(offset:Int):Int=when(offset){0->offset// Add 1 for opening parenthesis.in1..3->offset+1// Add 3 for both parentheses and a space.in4..6->offset+3// Add 4 for both parentheses, space, and hyphen.else->offset+4}overridefuntransformedToOriginal(offset:Int):Int=when(offset){0->offset// Subtract 1 for opening parenthesis.in1..5->offset-1// Subtract 3 for both parentheses and a space.in6..10->offset-3// Subtract 4 for both parentheses, space, and hyphen.else->offset-4}}}
تُدرج الدالة filter() أحرف التنسيق غير الرقمية في
المواضع المناسبة.
يحتوي عنصر phoneNumberOffsetTranslator على طريقتَين. يحدِّد أحدهما
الموضع النسبي بين السلسلة الأصلية والسلسلة المنسَّقة، ويحدِّد الآخر
الربط العكسي. تتيح عمليات الربط هذه تخطّي رموزها عند تغيير
يتم استخدام السلسلة المنسَّقة وphoneNumberOffsetTranslator كوسيطات
لمثيل TransformedText الذي يتم إرجاعه واستخدامه من قِبل
TextField لتنفيذ عملية التنسيق.
النتائج
الشكل 1. رقم هاتف بتنسيق تلقائي في حقل النص
المجموعات التي تتضمّن هذا الدليل
هذا الدليل هو جزء من مجموعات الأدلة السريعة المنظَّمة التي تتناول
أهداف تطوير Android الأوسع نطاقًا:
النص الذي يظهر للمستخدم
يشكّل النص جزءًا أساسيًا من أي واجهة مستخدم. تعرَّف على الطرق المختلفة
التي يمكنك من خلالها عرض النص في تطبيقك لتوفير تجربة رائعة للمستخدم.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-02-06 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-02-06 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Auto-format a phone number in a text field\n\n\u003cbr /\u003e\n\nYou can auto format a phone number in a text field in your app, saving users\ntime by formatting the phone number as they input digits. Follow this guidance\nto auto format a phone number:\n\n- Create the text field.\n- Auto-format a number in the text field.\n\nVersion compatibility\n---------------------\n\nThis implementation requires that your project minSDK be set to API level 21 or\nhigher.\n\n### Dependencies\n\n### Kotlin\n\n\u003cbr /\u003e\n\n```kotlin\n implementation(platform(\"androidx.compose:compose-bom:2025.08.00\"))\n implementation(\"androidx.compose.material3:material3\")\n \n```\n\n\u003cbr /\u003e\n\n### Groovy\n\n\u003cbr /\u003e\n\n```groovy\n implementation platform('androidx.compose:compose-bom:2025.08.00')\n implementation 'androidx.compose.material3:material3'\n \n```\n\n\u003cbr /\u003e\n\nCreate the text field\n---------------------\n\nFirst, configure the [`TextField`](/reference/kotlin/androidx/compose/material/package-summary#TextField(androidx.compose.ui.text.input.TextFieldValue,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Boolean,kotlin.Boolean,androidx.compose.ui.text.TextStyle,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.ui.text.input.VisualTransformation,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.KeyboardActions,kotlin.Boolean,kotlin.Int,kotlin.Int,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.ui.graphics.Shape,androidx.compose.material.TextFieldColors)). This example shows a phone number\nformatted per the North American Numbering Plan\n(NANP).`NanpVisualTransformation` formats a raw string of numbers to NANP, eg.\n1234567890 to (123) 456-7890.\n\n\n```kotlin\n@Composable\nfun PhoneNumber() {\n var phoneNumber by rememberSaveable { mutableStateOf(\"\") }\n val numericRegex = Regex(\"[^0-9]\")\n TextField(\n value = phoneNumber,\n onValueChange = {\n // Remove non-numeric characters.\n val stripped = numericRegex.replace(it, \"\")\n phoneNumber = if (stripped.length \u003e= 10) {\n stripped.substring(0..9)\n } else {\n stripped\n }\n },\n label = { Text(\"Enter Phone Number\") },\n visualTransformation = NanpVisualTransformation(),\n keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number)\n )\n}https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/text/TextSnippets.kt#L797-L816\n```\n\n\u003cbr /\u003e\n\n### Key points about the code\n\n- A `TextField` composable where the `onValueChange` uses a regular expression to remove all non-numeric characters and limits the length to a maximum of 10 characters before updating the `phoneNumber` state.\n- The `TextField` has a custom [`VisualTransformation`](/reference/kotlin/androidx/compose/ui/text/input/VisualTransformation) instance set on the `visualTransformation` attribute. `NanpVisualTransformation`, the custom class instantiated here, is defined in the following section.\n\nAuto-format a number in the text field\n--------------------------------------\n\nTo format a raw string of numbers, use the implementation of the custom\n`NanpVisualTransformation` class:\n\n\n```kotlin\nclass NanpVisualTransformation : VisualTransformation {\n\n override fun filter(text: AnnotatedString): TransformedText {\n val trimmed = if (text.text.length \u003e= 10) text.text.substring(0..9) else text.text\n\n var out = if (trimmed.isNotEmpty()) \"(\" else \"\"\n\n for (i in trimmed.indices) {\n if (i == 3) out += \") \"\n if (i == 6) out += \"-\"\n out += trimmed[i]\n }\n return TransformedText(AnnotatedString(out), phoneNumberOffsetTranslator)\n }\n\n private val phoneNumberOffsetTranslator = object : OffsetMapping {\n\n override fun originalToTransformed(offset: Int): Int =\n when (offset) {\n 0 -\u003e offset\n // Add 1 for opening parenthesis.\n in 1..3 -\u003e offset + 1\n // Add 3 for both parentheses and a space.\n in 4..6 -\u003e offset + 3\n // Add 4 for both parentheses, space, and hyphen.\n else -\u003e offset + 4\n }\n\n override fun transformedToOriginal(offset: Int): Int =\n when (offset) {\n 0 -\u003e offset\n // Subtract 1 for opening parenthesis.\n in 1..5 -\u003e offset - 1\n // Subtract 3 for both parentheses and a space.\n in 6..10 -\u003e offset - 3\n // Subtract 4 for both parentheses, space, and hyphen.\n else -\u003e offset - 4\n }\n }\n}https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/text/TextSnippets.kt#L820-L859\n```\n\n\u003cbr /\u003e\n\n### Key points about the code\n\n- The `filter()` function inserts the non-numeric formatting characters at the appropriate places.\n- The `phoneNumberOffsetTranslator` object contains two methods. One maps the offsets between the original string and the formatted one, and the other does the reverse mapping. These mappings enable the skipping of the formatting characters when the user changes the cursor location in the text field.\n- The formatted string and `phoneNumberOffsetTranslator` are used as arguments for a `TransformedText` instance that is returned and used by the `TextField` to perform the formatting.\n\nResults\n-------\n\n**Figure 1.** An auto-formatted phone number in the text field.\n\nCollections that contain this guide\n-----------------------------------\n\nThis guide is part of these curated Quick Guide collections that cover\nbroader Android development goals: \n\n### Display text\n\nText is a central piece of any UI. Find out different ways you can present text in your app to provide a delightful user experience. \n[Quick guide collection](/develop/ui/compose/quick-guides/collections/display-text) \n\n### Request user input\n\nLearn how to implement ways for users to interact with your app by entering text and using other means of input. \n[Quick guide collection](/develop/ui/compose/quick-guides/collections/request-user-input) \n\nHave questions or feedback\n--------------------------\n\nGo to our frequently asked questions page and learn about quick guides or reach out and let us know your thoughts. \n[Go to FAQ](/quick-guides/faq) [Leave feedback](https://issuetracker.google.com/issues/new?component=1573691&template=1993320)"]]