فیلدهای متنی را پیکربندی کنید

TextField به کاربران اجازه می‌دهد متن را وارد و تغییر دهند. دو نوع فیلد متنی وجود دارد که می‌توانید از آنها استفاده کنید: فیلدهای متنی مبتنی بر حالت و فیلدهای متنی مبتنی بر مقدار . نوع مورد نظر برای نمایش محتوا را انتخاب کنید:

ما استفاده از فیلدهای متنی مبتنی بر وضعیت (state-based) را توصیه می‌کنیم، زیرا آنها رویکردی کامل‌تر و قابل اعتمادتر برای مدیریت وضعیت یک TextField ارائه می‌دهند. جدول زیر تفاوت‌های بین این نوع فیلدهای متنی را شرح می‌دهد و مزایای کلیدی فیلدهای متنی مبتنی بر وضعیت را شامل می‌شود:

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

پیاده‌سازی TextField را انتخاب کنید

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

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

TextField(
    state = rememberTextFieldState(initialText = "Hello"),
    label = { Text("Label") }
)
StateBasedText.kt

OutlinedTextField(
    state = rememberTextFieldState(),
    label = { Text("Label") }
)
StateBasedText.kt

استایل دادن TextField

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

• textStyle
• lineLimits

TextField(
    state = rememberTextFieldState("Hello\nWorld\nInvisible"),
    lineLimits = TextFieldLineLimits.MultiLine(maxHeightInLines = 2),
    placeholder = { Text("") },
    textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
    label = { Text("Enter text") },
    modifier = Modifier.padding(20.dp)
)
StateBasedText.kt

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

پیکربندی محدودیت‌های خط

کامپوننت‌های TextField از پیمایش در امتداد یک محور واحد پشتیبانی می‌کنند. رفتار پیمایش توسط پارامتر lineLimits تعیین می‌شود. TextField ها برای پیمایش یک خط به صورت افقی پیکربندی شده‌اند، در حالی که TextField چند خطه به صورت عمودی پیمایش می‌شوند.

از TextFieldLineLimits برای انتخاب پیکربندی خط مناسب برای TextField خود استفاده کنید:

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine
)
StateBasedText.kt

پیکربندی SingleLine دارای ویژگی‌های زیر است:

• متن هرگز پیچیده نمی‌شود و اجازه ایجاد خطوط جدید را نمی‌دهد.
• TextField همیشه ارتفاع ثابتی دارد.
• اگر متن سرریز شود، به صورت افقی اسکرول می‌شود.

TextField(
    state = rememberTextFieldState("Hello\nWorld\nHello\nWorld"),
    lineLimits = TextFieldLineLimits.MultiLine(1, 4)
)
StateBasedText.kt

پیکربندی MultiLine دارای ویژگی‌های زیر است:

• دو پارامتر می‌پذیرد: minHeightInLines و maxHeightInLines .
• فیلد متن حداقل به اندازه minHeightInLines ارتفاع دارد.
• اگر متن سرریز شود، پیچیده می‌شود.
• اگر متن به خطوط بیشتری نیاز داشته باشد، فیلد تا زمانی که به ارتفاع maxHeightInLines برسد، رشد می‌کند و به صورت عمودی اسکرول می‌شود.

ورودی استایل با Brush API

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

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

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

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

val brush = remember {
    Brush.linearGradient(
        colors = listOf(Color.Red, Color.Yellow, Color.Green, Color.Blue, Color.Magenta)
    )
}
TextField(
    state = rememberTextFieldState(), textStyle = TextStyle(brush = brush)
)
StateBasedText.kt

مدیریت وضعیت فیلد متنی

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

• initialText : محتویات TextField .
• initialSelection : نشان می‌دهد که مکان‌نما یا ناحیه انتخاب شده کجا قرار دارد.

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

شما می‌توانید از TextFieldState() برای بالا بردن وضعیت در TextField استفاده کنید. برای این کار، توصیه می‌کنیم از تابع rememberTextFieldState() استفاده کنید. rememberTextFieldState() نمونه TextFieldState در composable شما ایجاد می‌کند، مطمئن می‌شود که شیء state به خاطر سپرده می‌شود و قابلیت ذخیره و بازیابی داخلی را فراهم می‌کند:

val usernameState = rememberTextFieldState()
TextField(
    state = usernameState,
    lineLimits = TextFieldLineLimits.SingleLine,
    placeholder = { Text("Enter Username") }
)
StateBasedText.kt

rememberTextFieldState می‌تواند یک پارامتر خالی داشته باشد یا یک مقدار اولیه برای نمایش مقدار متن در هنگام مقداردهی اولیه به آن ارسال شود. اگر مقدار متفاوتی در ترکیب‌بندی بعدی ارسال شود، مقدار state به‌روزرسانی نمی‌شود. برای به‌روزرسانی state پس از مقداردهی اولیه، متدهای edit را در TextFieldState فراخوانی کنید.

TextField(
    state = rememberTextFieldState(initialText = "Username"),
    lineLimits = TextFieldLineLimits.SingleLine,
)
StateBasedText.kt

تغییر متن با TextFieldBuffer

یک TextFieldBuffer به عنوان یک محفظه متن قابل ویرایش عمل می‌کند، مشابه عملکردی مانند StringBuilder . این محفظه هم محتوای متن و هم اطلاعات مربوط به انتخاب را در خود نگه می‌دارد.

شما اغلب با TextFieldBuffer به عنوان یک دامنه گیرنده در توابعی مانند TextFieldState.edit ، InputTransformation.transformInput یا OutputTransformation.transformOutput مواجه می‌شوید. در این توابع، می‌توانید TextFieldBuffer در صورت نیاز بخوانید یا به‌روزرسانی کنید. پس از آن، این تغییرات یا به TextFieldState اعمال می‌شوند یا در مورد OutputTransformation به خط لوله رندر منتقل می‌شوند.

شما می‌توانید از توابع ویرایش استاندارد مانند append ، insert ، replace یا delete برای تغییر محتویات بافر استفاده کنید. برای تغییر حالت انتخاب، یا مستقیماً متغیر selection: TextRange تنظیم کنید، یا از توابع کاربردی مانند placeCursorAtEnd یا selectAll استفاده کنید. خود انتخاب توسط یک TextRange نمایش داده می‌شود، که در آن شاخص شروع شامل و شاخص پایان منحصر است. یک TextRange با مقادیر شروع و پایان یکسان، مانند (3, 3) ، موقعیت مکان‌نما را بدون هیچ کاراکتر انتخاب شده‌ای نشان می‌دهد.

val phoneNumberState = rememberTextFieldState("1234567890")

TextField(
    state = phoneNumberState,
    keyboardOptions = KeyboardOptions(
        keyboardType = KeyboardType.Phone
    ),
    inputTransformation = InputTransformation.maxLength(10).then {
        if (!asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    },
    outputTransformation = OutputTransformation {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
)
StateBasedText.kt

ویرایش متن در TextFieldState

چندین روش وجود دارد که به شما امکان می‌دهد حالت را مستقیماً از طریق متغیر حالت خود ویرایش کنید:

• edit : به شما امکان ویرایش محتوای حالت را می‌دهد و توابع TextFieldBuffer را در اختیار شما قرار می‌دهد تا بتوانید از متدهایی مانند insert ، replace ، append و موارد دیگر استفاده کنید.

  // Initial textFieldState text passed in is "I love Android"
  // textFieldState.text : I love Android
  // textFieldState.selection: TextRange(14, 14)
  textFieldState.edit { insert(14, "!") }
  // textFieldState.text : I love Android!
  // textFieldState.selection: TextRange(15, 15)
  textFieldState.edit { replace(7, 14, "Compose") }
  // textFieldState.text : I love Compose!
  // textFieldState.selection: TextRange(15, 15)
  textFieldState.edit { append("!!!") }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(18, 18)
  textFieldState.edit { selectAll() }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(0, 18)
  StateBasedText.kt

• setTextAndPlaceCursorAtEnd : متن فعلی را پاک می‌کند، آن را با متن داده شده جایگزین می‌کند و مکان‌نما را در انتها قرار می‌دهد.

  textFieldState.setTextAndPlaceCursorAtEnd("I really love Android")
  // textFieldState.text : I really love Android
  // textFieldState.selection : TextRange(21, 21)
  StateBasedText.kt

• clearText : تمام متن را پاک می‌کند.

  textFieldState.clearText()
  // textFieldState.text :
  // textFieldState.selection : TextRange(0, 0)
  StateBasedText.kt

برای سایر توابع TextFieldState ، به مرجع TextFieldState مراجعه کنید.

تغییر ورودی کاربر

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

فیلتر کردن ورودی کاربر با تبدیل‌های ورودی

یک تبدیل ورودی به شما امکان می‌دهد ورودی کاربر را فیلتر کنید. برای مثال، اگر TextField شما یک شماره تلفن آمریکایی را دریافت کند، شما فقط می‌خواهید 10 رقم را بپذیرید. نتایج InputTransformation در TextFieldState ذخیره می‌شوند.

فیلترهای داخلی برای موارد استفاده رایج InputTransformation وجود دارد. برای محدود کردن طول، InputTransformation.maxLength() را فراخوانی کنید:

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine,
    inputTransformation = InputTransformation.maxLength(10)
)
StateBasedText.kt

تبدیل‌های ورودی سفارشی

InputTransformation یک رابط تک‌تابعی است. هنگام پیاده‌سازی InputTransformation سفارشی خود، باید TextFieldBuffer.transformInput بازنویسی کنید:

class CustomInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
    }
}
StateBasedText.kt

برای شماره تلفن، یک تبدیل ورودی سفارشی اضافه کنید که فقط اجازه تایپ ارقام را در TextField بدهد:

class DigitOnlyInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
        if (!asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    }
}
StateBasedText.kt

تبدیل‌های ورودی زنجیره‌ای

برای افزودن چندین فیلتر به ورودی متن خود، InputTransformation ها را با استفاده از تابع افزونه then به صورت زنجیره‌ای اجرا کنید. فیلترها به صورت متوالی اجرا می‌شوند. به عنوان یک روش بهتر، ابتدا فیلترهای انتخابی‌تر را اعمال کنید تا از تبدیل‌های غیرضروری روی داده‌هایی که در نهایت فیلتر می‌شوند، جلوگیری شود.

TextField(
    state = rememberTextFieldState(),
    inputTransformation = InputTransformation.maxLength(6)
        .then(CustomInputTransformation()),
)
StateBasedText.kt

پس از افزودن تبدیل‌های ورودی، ورودی TextField حداکثر ۱۰ رقم را می‌پذیرد.

قالب‌بندی ورودی قبل از نمایش

OutputTransformation ها به شما امکان می‌دهند ورودی کاربر را قبل از نمایش روی صفحه، قالب‌بندی کنید. برخلاف InputTransformation ، قالب‌بندی انجام شده از طریق OutputTransformation در TextFieldState ذخیره نمی‌شود. با تکیه بر مثال شماره تلفن قبلی، باید پرانتز و خط تیره را در مکان‌های مناسب اضافه کنید:

این روش به‌روزرسانی‌شده‌ی مدیریت VisualTransformation ها در TextField های مبتنی بر مقدار است، با یک تفاوت کلیدی که در آن نیازی به محاسبه‌ی نگاشت‌های آفست آنها نیست.

OutputTransformation یک رابط متد انتزاعی واحد است. برای پیاده‌سازی یک OutputTransformation سفارشی، باید متد transformOutput بازنویسی کنید:

class CustomOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
    }
}
StateBasedText.kt

برای قالب‌بندی شماره تلفن، یک پرانتز باز در اندیس ۰، یک پرانتز بسته در اندیس ۴ و یک خط تیره در اندیس ۸ به OutputTransformation خود اضافه کنید:

class PhoneNumberOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
}
StateBasedText.kt

سپس، OutputTransformation خود را به TextField اضافه کنید:

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)
StateBasedText.kt

چگونه تحولات با هم کار می‌کنند

نمودار زیر جریان را از ورودی متن تا تبدیل و خروجی نشان می‌دهد:

1. ورودی از منبع ورودی دریافت می‌شود.
2. ورودی از طریق InputTransformation فیلتر می‌شود که در TextFieldState ذخیره می‌شود.
3. ورودی برای قالب‌بندی از طریق یک OutputTransformation ارسال می‌شود.
4. ورودی در TextField نمایش داده می‌شود.

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

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

• capitalization
• autoCorrect
• keyboardType
• imeAction

کلاس KeyboardOptions اکنون شامل یک پارامتر بولی جدید به showKeyboardOnFocus است که شما به طور خاص برای کامپوننت‌های TextField که با TextFieldState یکپارچه شده‌اند، استفاده می‌کنید. این گزینه رفتار صفحه کلید نرم‌افزار را هنگامی که TextField از طریقی غیر از تعامل مستقیم کاربر (به عنوان مثال، از طریق برنامه‌نویسی) فوکوس را به دست می‌آورد، کنترل می‌کند.

وقتی KeyboardOptions.showKeyboardOnFocus روی true تنظیم شده باشد، اگر TextField به طور غیرمستقیم فوکوس را به دست آورد، صفحه کلید نرم‌افزار به طور خودکار ظاهر نمی‌شود. در چنین مواردی، کاربر باید صریحاً روی خود TextField ضربه بزند تا صفحه کلید نمایان شود.

تعریف منطق تعامل صفحه کلید

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

برای تعریف اینکه وقتی کاربر این دکمه عملیاتی را فشار می‌دهد چه اتفاقی می‌افتد، از پارامتر onKeyboardAction استفاده کنید. این پارامتر یک رابط تابعی اختیاری به نام KeyboardActionHandler می‌پذیرد. رابط KeyboardActionHandler شامل یک متد واحد به نام onKeyboardAction(performDefaultAction: () -> Unit) است. با ارائه یک پیاده‌سازی برای این متد onKeyboardAction ، می‌توانید منطق سفارشی را معرفی کنید که وقتی کاربر دکمه عملیاتی صفحه کلید را فشار می‌دهد، اجرا شود.

چندین نوع اکشن استاندارد کیبورد با رفتارهای پیش‌فرض داخلی ارائه می‌شوند. برای مثال، انتخاب ImeAction.Next یا ImeAction.Previous به عنوان نوع اکشن، به طور پیش‌فرض، فوکوس را به ترتیب به فیلد ورودی بعدی یا قبلی منتقل می‌کند. به طور مشابه، یک دکمه اکشن که روی ImeAction.Done تنظیم شده باشد، معمولاً کیبورد نرم‌افزاری را غیرفعال می‌کند. این عملکردهای پیش‌فرض به طور خودکار اجرا می‌شوند و نیازی به ارائه KeyboardActionHandler توسط شما ندارند.

شما همچنین می‌توانید علاوه بر این اقدامات پیش‌فرض، رفتار سفارشی نیز پیاده‌سازی کنید. وقتی KeyboardActionHandler خود را ارائه می‌دهید، متد onKeyboardAction آن یک تابع performDefaultAction دریافت می‌کند. می‌توانید این تابع performDefaultAction() را در هر نقطه‌ای از منطق سفارشی خود فراخوانی کنید تا رفتار پیش‌فرض استاندارد مرتبط با اقدام IME فعلی را نیز فعال کند.

TextField(
    state = textFieldViewModel.usernameState,
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
    onKeyboardAction = { performDefaultAction ->
        textFieldViewModel.validateUsername()
        performDefaultAction()
    }
)
StateBasedText.kt

این قطعه کد، یک مورد استفاده رایج در صفحه ثبت نام با فیلد نام کاربری را نشان می‌دهد. برای این فیلد، ImeAction.Next برای دکمه عمل صفحه کلید انتخاب شده است. این انتخاب، پیمایش سریع و یکپارچه به فیلد رمز عبور بعدی را امکان‌پذیر می‌کند.

علاوه بر این ناوبری استاندارد، الزامی برای شروع یک فرآیند اعتبارسنجی پس‌زمینه برای نام کاربری هنگام وارد کردن رمز عبور توسط کاربر وجود دارد. برای اطمینان از اینکه رفتار پیش‌فرض تغییر فوکوس که مختص ImeAction.Next است در کنار این منطق اعتبارسنجی سفارشی حفظ می‌شود، تابع performDefaultAction() فراخوانی می‌شود. فراخوانی performDefaultAction() به طور ضمنی سیستم مدیریت فوکوس را فعال می‌کند تا فوکوس را به عنصر رابط کاربری مناسب بعدی منتقل کند و جریان ناوبری مورد انتظار را حفظ کند.

ایجاد فیلد رمز عبور امن

SecureTextField یک ترکیب‌پذیر (composable) است که بر روی فیلدهای متنی مبتنی بر وضعیت (state-based text field) برای نوشتن فیلد رمز عبور ساخته شده است. ما استفاده از SecureTextField را برای ایجاد فیلدهای متنی رمز عبور توصیه می‌کنیم، زیرا ورودی کاراکتر را به طور پیش‌فرض پنهان می‌کند و عملکردهای برش و کپی را غیرفعال می‌کند.

SecureTextField دارای یک textObfuscationMode است که نحوه‌ی مشاهده‌ی کاراکترهای ورودی توسط کاربر را کنترل می‌کند. textObfuscationMode گزینه‌های زیر را دارد:

• Hidden : تمام ورودی‌ها را پنهان می‌کند. رفتار پیش‌فرض در پلتفرم‌های دسکتاپ.

  

• Visible : تمام ورودی‌ها را نشان می‌دهد.

  

• RevealLastTyped : تمام ورودی‌ها به جز آخرین کاراکتر را پنهان می‌کند. عملکرد پیش‌فرض در دستگاه‌های تلفن همراه.

  

منابع اضافی

• قالب‌بندی خودکار شماره تلفن در فیلد متنی
• نمایش یا پنهان کردن رمز عبور بر اساس گزینه‌ی انتخاب کاربر
• اعتبارسنجی ورودی هنگام تایپ توسط کاربر