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

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

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 باید هنگام ساخت طرح هایی که به تزئینات مربوط به مشخصات مواد نیاز ندارند استفاده شود.

ورودی سبک با 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

منابع اضافی

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