הגדרת שדות טקסט

‫TextField מאפשר למשתמשים להזין ולשנות טקסט. יש שני סוגים של שדות טקסט שאפשר להשתמש בהם: שדות טקסט מבוססי-מצב ושדות טקסט מבוססי-ערך. בוחרים את הסוג שרוצים להציג את התוכן שלו:

שדות טקסט מבוססי-מצב שדות טקסט מבוססי-ערך

מומלץ להשתמש בשדות טקסט מבוססי-מצב, כי הם מספקים גישה מלאה ואמינה יותר לניהול המצב של TextField. בטבלה הבאה מפורטים ההבדלים בין סוגי שדות הטקסט האלה, ומוצגים היתרונות העיקריים של שדות טקסט מבוססי-מצב:

ניסיוני: שדות טקסט מבוססי-מצב מסתמכים על Material 3 גרסה 1.4.0-alpha14. אפשר לדווח על באגים בכלי למעקב אחר בעיות.

Feature	שדות טקסט מבוססי-ערך	שדות טקסט מבוססי-מצב	הטבה לפי מדינה
ניהול מצב	מעדכן את הסטטוס של שדה הטקסט באמצעות הקריאה החוזרת onValueChange. אתם אחראים לעדכן את value במדינה שלכם על סמך השינויים שדווחו על ידי onValueChange.	משתמש במפורש באובייקט TextFieldState כדי לנהל את מצב קלט הטקסט (ערך, בחירה והרכבה). אפשר לזכור את המצב הזה ולשתף אותו.	הוסר ה-callback‏ onValueChange, ולכן אי אפשר להוסיף התנהגויות אסינכרוניות. המצב נשמר גם אחרי הרכבה מחדש, הגדרה וסיום התהליך.
טרנספורמציה חזותית	משתמשים ב-VisualTransformation כדי לשנות את המראה של הטקסט המוצג. בדרך כלל, הפעולה הזו מטפלת בפורמט של הקלט ושל הפלט בשלב אחד.	משתמשים ב-InputTransformation כדי לשנות את הקלט של המשתמש לפני שהוא נשמר במצב, וב-OutputTransformation כדי לעצב את התוכן של שדה הטקסט בלי לשנות את נתוני המצב הבסיסיים.	אין יותר צורך לספק את מיפוי ההיסט בין הטקסט הגולמי המקורי לבין הטקסט שעבר טרנספורמציה באמצעות OutputTransformation.
מגבלות על שורות	מקבל את הערכים singleLine: Boolean, maxLines: Int ו-minLines: Int כדי לשלוט במספר השורות.	משתמשים ב-lineLimits: TextFieldLineLimits כדי להגדיר את מספר השורות המינימלי והמקסימלי שהטקסט יכול לתפוס בשדה.	כדי למנוע אי-בהירות כשמגדירים מגבלות על שורות, צריך לספק פרמטר lineLimits מסוג TextFieldLineLimits.
שדה טקסט מאובטח	לא רלוונטי	‫SecureTextField הוא קומפוזבילי שמבוסס על שדות טקסט מבוססי-מצב לכתיבת שדה סיסמה.	האפשרות הזו מאפשרת לכם לבצע אופטימיזציה של האבטחה מתחת לפני השטח, והיא מגיעה עם ממשק משתמש מוגדר מראש עם textObfuscationMode.

בדף הזה מוסבר איך להטמיע את TextField, איך להגדיר את הסגנון של הקלט TextField ואיך להגדיר אפשרויות אחרות של TextField, כמו אפשרויות של מקלדת ושינוי ויזואלי של קלט של משתמשים.

בחירת הטמעה של TextField

יש שתי רמות של הטמעה של TextField:

1. ‫TextField הוא ההטמעה של Material Design. מומלץ לבחור בהטמעה הזו כי היא תואמת להנחיות של Material Design:
   • עיצוב ברירת המחדל הוא מילוי
   • ‫OutlinedTextField היא גרסת הסגנון עם קו מתאר
2. ‫BasicTextField מאפשר למשתמשים לערוך טקסט באמצעות מקלדת חומרה או מקלדת וירטואלית, אבל לא מספק קישוטים כמו רמז או placeholder.

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 במקום ב-BasicTextField כשרוצים להשתמש בעיצוב של Material TextField או OutlinedTextField. עם זאת, כדאי להשתמש ב-BasicTextField כשיוצרים עיצובים שלא צריך בהם את הקישוטים ממפרט Material.

הוספת סגנון לקלט באמצעות Brush API

אפשר להשתמש ב-Brush API כדי להחיל סגנונות מתקדמים יותר על TextField. בקטע הבא מוסבר איך להשתמש במברשת כדי להוסיף שיפוע צבעוני לקלט 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

איור 1. אפקט של מעבר צבעים בצבעי הקשת לתוכן של TextField.

ניהול המצב של שדה טקסט

‫TextField משתמש במחזיק מצב ייעודי שנקרא TextFieldState בשביל התוכן והבחירה שלו. ‫TextFieldState מיועד להצבה בכל מקום שמתאים בארכיטקטורה שלכם. יש 2 מאפיינים עיקריים שמופיעים ב-TextFieldState:

• ‫initialText: התוכן של TextField.
• ‫initialSelection: מציין איפה נמצא הסמן או הבחירה.

מה שמבדיל בין TextFieldState לבין גישות אחרות, כמו הקריאה החוזרת (callback) onValueChange, הוא ש-TextFieldState מכיל באופן מלא את כל זרימת הקלט. הפעולה הזו כוללת שימוש במבני נתונים נכונים לגיבוי, שימוש במסננים ובמעצבים מוטבעים וגם סנכרון של כל העריכות שמגיעות ממקורות שונים.

הערה: למרות ש-TextFieldState שייך למודול Compose Foundation, אין לו תלות בממשק המשתמש והוא נועד להיות מאחסן מצב רב עוצמה. ‫TextFieldState משתמש רק במבני נתונים שסופקו על ידי מערכת הצילום של Compose. מומלץ ליצור מופעים של TextFieldState ולשמור אותם ב-ViewModels.

אפשר להשתמש ב-TextFieldState() כדי להעביר את מצב הרכיב ב-TextField. לשם כך, מומלץ להשתמש בפונקציה rememberTextFieldState(). ‫rememberTextFieldState() יוצר את המופע TextFieldState בקומפוזיציה, מוודא שאובייקט המצב נשמר ומספק פונקציונליות מובנית של שמירה ושחזור:

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

איור 2. ‫TextField עם 'שם משתמש' כטקסט הראשוני.

שינוי הטקסט באמצעות 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.transformInput() לפונקציה. במקום זאת, משתמשים בהיקף המקלט TextFieldBuffer כדי לערוך טקסט.

יש מסננים מובנים לתרחישי שימוש נפוצים ב-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 יכול לקבל עד 10 ספרות.

עיצוב הקלט לפני שהוא מוצג

‫OutputTransformations מאפשרים לכם לעצב קלט משתמש לפני שהוא מוצג במסך. בניגוד ל-InputTransformation, העיצוב שנעשה באמצעות התג OutputTransformation לא נשמר ב-TextFieldState. בהמשך לדוגמה הקודמת של מספר הטלפון, צריך להוסיף סוגריים ומקפים במקומות המתאימים:

איור 3. מספר טלפון אמריקאי בפורמט המתאים עם אינדקסים תואמים.

זו הדרך המעודכנת לטפל ב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

איך טרנספורמציות פועלות יחד

התרשים הבא מראה את התהליך מקלט טקסט ועד לשינוי שלו לפלט:

איור 4. דיאגרמה שמראה איך קלט טקסט עובר טרנספורמציות לפני שהוא הופך לפלט טקסט.

1. הקלט מתקבל ממקור הקלט.
2. הקלט מסונן באמצעות InputTransformation, שנשמר ב-TextFieldState.
3. הקלט מועבר דרך OutputTransformation כדי לעצב אותו.
4. הקלט מוצג בTextField.

הגדרת אפשרויות מקלדת

‫TextField מאפשרת להגדיר אפשרויות של המקלדת, כמו פריסת המקלדת, או להפעיל את התיקון האוטומטי אם המקלדת תומכת בו. יכול להיות שחלק מהאפשרויות לא יהיו זמינות אם המקלדת הווירטואלית לא תהיה תואמת לאפשרויות שמופיעות כאן. רשימת האפשרויות הנתמכות במקלדת:

• capitalization
• autoCorrect
• keyboardType
• imeAction

מקורות מידע נוספים

• עיצוב אוטומטי של מספר טלפון בשדה טקסט
• הצגה או הסתרה של הסיסמה על סמך מתג של משתמש
• אימות הקלט בזמן שהמשתמש מקליד