کنترل ورودی کاربر

TextField به کاربران اجازه می دهد متن را وارد کرده و تغییر دهند. این صفحه نحوه پیاده‌سازی TextField ، سبک ورودی TextField و پیکربندی سایر گزینه‌های TextField ، مانند گزینه‌های صفحه کلید و تبدیل بصری ورودی کاربر را توضیح می‌دهد.

اجرای TextField را انتخاب کنید

دو سطح پیاده سازی TextField وجود دارد:

1. TextField پیاده سازی Material Design است. توصیه می‌کنیم این پیاده‌سازی را مطابق دستورالعمل‌های طراحی متریال انتخاب کنید:
   • استایل پیش فرض پر شده است
   • OutlinedTextField نسخه یک ظاهر طراحی شده است
2. BasicTextField کاربران را قادر می‌سازد تا متن را از طریق صفحه کلید سخت‌افزاری یا نرم‌افزاری ویرایش کنند، اما هیچ تزئینی مانند اشاره یا مکان‌نما ارائه نمی‌دهد.

@Composable
fun SimpleFilledTextFieldSample() {
    var text by remember { mutableStateOf("Hello") }

    TextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}
TextSnippets.kt

@Composable
fun SimpleOutlinedTextFieldSample() {
    var text by remember { mutableStateOf("") }

    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}
TextSnippets.kt

Style TextField

TextField و BasicTextField پارامترهای مشترک زیادی برای سفارشی کردن آنها به اشتراک می گذارند. فهرست کامل TextField در کد منبع TextField موجود است. این یک لیست غیر جامع از برخی از پارامترهای مفید است:

• singleLine
• maxLines
• textStyle

@Composable
fun StyledTextField() {
    var value by remember { mutableStateOf("Hello\nWorld\nInvisible") }

    TextField(
        value = value,
        onValueChange = { value = it },
        label = { Text("Enter text") },
        maxLines = 2,
        textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
        modifier = Modifier.padding(20.dp)
    )
}
TextSnippets.kt

وقتی طراحی شما نیاز به یک Material TextField یا OutlinedTextField دارد، TextField به BasicTextField توصیه می کنیم. با این حال، BasicTextField باید هنگام ساخت طرح هایی که به تزئینات مربوط به مشخصات مواد نیاز ندارند استفاده شود.

ورودی سبک با Brush API

می‌توانید از Brush API برای استایل‌سازی پیشرفته‌تر در TextField خود استفاده کنید. بخش زیر نحوه استفاده از Brush را برای افزودن یک گرادیان رنگی به ورودی TextField توضیح می دهد.

برای اطلاعات بیشتر در مورد استفاده از Brush API برای استایل دادن به متن، به فعال کردن یک ظاهر طراحی پیشرفته با Brush API مراجعه کنید.

شیب های رنگی را با استفاده از TextStyle پیاده سازی کنید

برای پیاده سازی یک گرادیان رنگی هنگام تایپ در یک TextField ، براش انتخابی خود را به عنوان TextStyle برای TextField خود تنظیم کنید. در این مثال، ما از یک براش داخلی با یک linearGradient برای مشاهده افکت گرادیان رنگین کمان هنگام تایپ متن در TextField استفاده می‌کنیم.

var text by remember { mutableStateOf("") }
val brush = remember {
    Brush.linearGradient(
        colors = rainbowColors
    )
}
TextField(
    value = text, onValueChange = { text = it }, textStyle = TextStyle(brush = brush)
)
TextSnippets.kt

گزینه های صفحه کلید را تنظیم کنید

TextField به شما امکان می‌دهد گزینه‌های پیکربندی صفحه‌کلید، مانند طرح‌بندی صفحه‌کلید را تنظیم کنید، یا اگر توسط صفحه‌کلید پشتیبانی می‌شود، تصحیح خودکار را فعال کنید. اگر صفحه‌کلید نرم‌افزار با گزینه‌های ارائه‌شده در اینجا مطابقت نداشته باشد، ممکن است برخی از گزینه‌ها تضمین نشوند. در اینجا لیستی از گزینه های صفحه کلید پشتیبانی شده است:

• capitalization
• autoCorrect
• keyboardType
• imeAction

فرمت ورودی

TextField به شما امکان می دهد یک VisualTransformation روی مقدار ورودی تنظیم کنید، مانند جایگزینی کاراکترها با * برای رمزهای عبور، یا درج خط فاصله هر 4 رقم برای یک شماره کارت اعتباری:

@Composable
fun PasswordTextField() {
    var password by rememberSaveable { mutableStateOf("") }

    TextField(
        value = password,
        onValueChange = { password = it },
        label = { Text("Enter password") },
        visualTransformation = PasswordVisualTransformation(),
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password)
    )
}
TextSnippets.kt

نمونه های بیشتری در کد منبع VisualTransformationSamples موجود است.

ورودی تمیز

یک کار رایج هنگام ویرایش متن این است که کاراکترهای اصلی را حذف کنید یا رشته ورودی را با هر بار تغییر تغییر دهید.

به عنوان یک مدل، باید فرض کنید که صفحه‌کلید ممکن است هر یک onValueChange ویرایش‌های دلخواه و بزرگ انجام دهد. این ممکن است اتفاق بیفتد، برای مثال، اگر کاربر از تصحیح خودکار استفاده کند، یک کلمه را با ایموجی یا سایر ویژگی‌های ویرایش هوشمند جایگزین کند. برای مدیریت صحیح این موضوع، هر منطق تبدیلی را با این فرض بنویسید که متن فعلی ارسال شده به onValueChange با مقادیر قبلی یا بعدی که به onValueChange ارسال می‌شوند، ارتباطی ندارد.

برای پیاده‌سازی یک فیلد متنی که صفرهای ابتدایی را مجاز نمی‌داند، می‌توانید این کار را با حذف تمام صفرهای ابتدایی در هر تغییر مقدار انجام دهید.

@Composable
fun NoLeadingZeroes() {
    var input by rememberSaveable { mutableStateOf("") }
    TextField(
        value = input,
        onValueChange = { newText ->
            input = newText.trimStart { it == '0' }
        }
    )
}
TextSnippets.kt

برای کنترل موقعیت مکان نما در حین تمیز کردن متن، از TextFieldValue اضافه بار TextField به عنوان بخشی از حالت استفاده کنید.

بهترین شیوه ها با دولت

در زیر مجموعه ای از بهترین روش ها برای تعریف و به روز رسانی وضعیت TextField برای جلوگیری از مشکلات ورودی در برنامه شما آمده است.

• از MutableState برای نمایش وضعیت TextField استفاده کنید : از استفاده از جریان های واکنشی مانند StateFlow برای نشان دادن وضعیت TextField خودداری کنید، زیرا این ساختارها ممکن است تاخیرهای ناهمزمان ایجاد کنند.

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}
TextSnippets.kt

• برای به‌روزرسانی وضعیت از تأخیر جلوگیری کنید : وقتی با onValueChange تماس می‌گیرید، TextField خود را به‌طور همزمان و بلافاصله به‌روزرسانی کنید:

// SignUpViewModel.kt

class SignUpViewModel(private val userRepository: UserRepository) : ViewModel() {

    var username by mutableStateOf("")
        private set

    fun updateUsername(input: String) {
        username = input
    }
}

// SignUpScreen.kt

@Composable
fun SignUpScreen(/*...*/) {

    OutlinedTextField(
        value = viewModel.username,
        onValueChange = { username -> viewModel.updateUsername(username) }
        /*...*/
    )
}
TextSnippets.kt

• محل تعریف حالت : اگر حالت TextField شما به اعتبارسنجی منطق تجاری در حین تایپ نیاز دارد، درست است که حالت را به ViewModel خود ارتقا دهید. اگر اینطور نیست، می توانید از composable ها یا یک کلاس دارنده حالت به عنوان منبع حقیقت استفاده کنید. برای کسب اطلاعات بیشتر در مورد مکان بالا بردن ایالت خود، به اسناد بالا بردن ایالت مراجعه کنید.