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

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

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

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

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

תכונה	שדות טקסט מבוססי-ערך	שדות טקסט מבוססי-מצב	הטבה שמבוססת על מדינה
ניהול מצב	עדכון המצב של שדה הטקסט באמצעות הקריאה החוזרת (callback) 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.

הגדרת מגבלות על שורות

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

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

טרנספורמציות של קלט בשרשרת

כדי להוסיף כמה מסננים לקלט הטקסט, משתמשים בפונקציית ההרחבה then כדי לשרשר כמה פונקציות InputTransformation. המסננים מופעלים ברצף. מומלץ להחיל קודם את המסננים הסלקטיביים ביותר כדי להימנע משינויים מיותרים בנתונים שבסופו של דבר יסוננו.

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

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

אם הערך של KeyboardOptions.showKeyboardOnFocus מוגדר כ-True, המקלדת הווירטואלית לא מופיעה אוטומטית אם TextField מקבל פוקוס באופן עקיף. במקרים כאלה, המשתמש צריך להקיש באופן מפורש על TextField כדי שהמקלדת תופיע.

הגדרת לוגיקה של אינטראקציה עם המקלדת

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

איור 5. כפתור הפעולה במקלדת הווירטואלית.

כדי להגדיר מה קורה כשמשתמש מקיש על לחצן הפעולה הזה, משתמשים בפרמטר onKeyboardAction. הפרמטר הזה מקבל ממשק פונקציונלי אופציונלי בשם KeyboardActionHandler. הממשק KeyboardActionHandler מכיל שיטה אחת, onKeyboardAction(performDefaultAction: () -> Unit). אם תספקו הטמעה של שיטת onKeyboardAction הזו, תוכלו להוסיף לוגיקה מותאמת אישית שתופעל כשמשתמש ילחץ על לחצן הפעולה במקלדת.

לכמה סוגים של פעולות סטנדרטיות במקלדת יש התנהגויות ברירת מחדל מובנות. לדוגמה, אם בוחרים באפשרות ImeAction.Next או ImeAction.Previous כסוג הפעולה, המיקוד עובר כברירת מחדל לשדה הקלט הבא או הקודם, בהתאמה. באופן דומה, לחצן פעולה שמוגדר לImeAction.Done בדרך כלל מסתיר את המקלדת הווירטואלית. הפונקציות האלה מופעלות כברירת מחדל באופן אוטומטי, ולא צריך לספק KeyboardActionHandler.

בנוסף לפעולות ברירת המחדל האלה, אפשר גם להטמיע התנהגות מותאמת אישית. כשמספקים את KeyboardActionHandler, הפונקציה performDefaultAction מתקבלת בשיטה onKeyboardAction. אפשר להפעיל את הפונקציה 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 הוא קומפוזיציה שנבנתה על גבי שדות טקסט מבוססי-מצב לכתיבת שדה סיסמה. מומלץ להשתמש ב-SecureTextField כדי ליצור שדות טקסט של סיסמאות, כי הוא מסתיר את קלט התווים כברירת מחדל ומשבית את פעולות החיתוך וההעתקה.

ל-SecureTextField יש textObfuscationMode, שקובע איך המשתמש רואה את הקלט של התווים. textObfuscationMode כולל את האפשרויות הבאות:

• ‫Hidden: מסתיר את כל הקלט. התנהגות ברירת המחדל בפלטפורמות למחשבים.

  

• ‫Visible: הצגת כל הקלט.

  

• ‫RevealLastTyped: מסתיר את כל הקלט חוץ מהתו האחרון. התנהגות ברירת המחדל במכשירים ניידים.

  

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

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