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

با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

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

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

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

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

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

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

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

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

Style 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

وقتی طراحی شما نیاز به یک Material 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

می‌توانید از Brush API برای استایل‌سازی پیشرفته‌تر در 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 به گونه ای طراحی شده است که در هر جایی که در معماری شما قرار می گیرد، بلند می شود. 2 ویژگی اصلی وجود دارد که توسط TextFieldState ارائه شده است:

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

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

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

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

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

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

متن را با TextFieldBuffer تغییر دهید

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

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

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

val phoneNumberState = rememberTextFieldState()

LaunchedEffect(phoneNumberState) {
    phoneNumberState.edit { // TextFieldBuffer scope
        append("123456789")
    }
}

TextField(
    state = phoneNumberState,
    inputTransformation = InputTransformation { // TextFieldBuffer scope
        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 و غیره استفاده کنید.

  val usernameState = rememberTextFieldState("I love Android")
  // textFieldState.text : I love Android
  // textFieldState.selection: TextRange(14, 14)
  usernameState.edit { insert(14, "!") }
  // textFieldState.text : I love Android!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { replace(7, 14, "Compose") }
  // textFieldState.text : I love Compose!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { append("!!!") }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(18, 18)
  usernameState.edit { selectAll() }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(0, 18)
  StateBasedText.kt

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

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

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

  usernameState.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 (!TextUtils.isDigitsOnly(asCharSequence())) {
            revertAllChanges()
        }
    }
}
StateBasedText.kt

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

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

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

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

ورودی را قبل از نمایش فرمت کنید

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

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

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

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

برای قالب بندی شماره تلفن، یک پرانتز باز در نمایه 0، یک پرانتز بسته در نمایه 4 و یک خط تیره در نمایه 8 به 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() به طور ضمنی سیستم مدیریت فوکوس زیربنایی را فعال می کند تا فوکوس را به عنصر UI مناسب بعدی منتقل کند و جریان ناوبری مورد انتظار را حفظ کند.

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

SecureTextField یک فایل ترکیبی است که بر روی فیلدهای متنی مبتنی بر حالت برای نوشتن فیلد رمز عبور ساخته شده است. توصیه می کنیم از SecureTextField برای ایجاد فیلدهای متنی رمز عبور استفاده کنید، زیرا به طور پیش فرض ورودی کاراکتر را پنهان می کند و اقدامات برش و کپی را غیرفعال می کند.

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

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

  

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

  

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

  

منابع اضافی

• فرمت خودکار شماره تلفن در یک فیلد متنی
• نمایش یا پنهان کردن رمز عبور بر اساس تغییر کاربری
• اعتبار ورودی را با نوع کاربر تأیید کنید