با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
میتوانید شماره تلفن را در یک فیلد نوشتاری در برنامه خود قالببندی کنید و با فرمت کردن شماره تلفن در هنگام وارد کردن ارقام، در وقت کاربران صرفهجویی کنید. برای فرمت خودکار شماره تلفن این دستورالعمل را دنبال کنید:
فیلد متن را ایجاد کنید.
فرمت خودکار یک عدد در قسمت متن.
سازگاری نسخه
این پیاده سازی مستلزم آن است که minSDK پروژه شما روی سطح API 21 یا بالاتر تنظیم شود.
وابستگی ها
فیلد متن را ایجاد کنید
ابتدا TextField را پیکربندی کنید. این مثال شماره تلفنی را نشان می دهد که بر اساس طرح شماره گذاری آمریکای شمالی (NANP) فرمت شده است. NanpVisualTransformation یک رشته خام از اعداد را به NANP فرمت می کند، به عنوان مثال. 1234567890 تا (123) 456-7890.
یک TextField قابل ترکیب که در آن onValueChange از یک عبارت منظم برای حذف همه نویسههای غیر عددی استفاده میکند و قبل از بهروزرسانی وضعیت phoneNumber ، طول آن را به حداکثر 10 کاراکتر محدود میکند.
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. یک شماره تلفن با فرمت خودکار در قسمت متن.
مجموعه هایی که حاوی این راهنما هستند
این راهنما بخشی از مجموعههای راهنمای Quick Guide است که اهداف توسعه Android گستردهتری را پوشش میدهد:
نمایش متن
متن بخش مرکزی هر رابط کاربری است. روش های مختلفی را بیابید که می توانید متن را در برنامه خود ارائه دهید تا تجربه کاربری لذت بخشی را ارائه دهید.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-02-06 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 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)"]]