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

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

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

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

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

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

1. TextField הוא ההטמעה של Material Design. מומלץ לבחור בהטמעה הזו כי היא תואמת להנחיות של Material Design:
   • עיצוב ברירת המחדל הוא filled
   • OutlinedTextField היא הגרסה עם הסגנון outlined
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 כשהעיצוב דורש את החומר 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

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

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

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

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

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

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

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

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

שינוי טקסט באמצעות TextFieldBuffer

TextFieldBuffer משמש כקונטיינר טקסט שניתן לעריכה, בדומה ל-StringBuilder. הוא מכיל גם את תוכן הטקסט וגם מידע על הבחירה הנוכחית.

לעיתים קרובות TextFieldBuffer מופיע כטווח מקלט בפונקציות כמו TextFieldState.edit,‏ InputTransformation.transformInput או OutputTransformation.transformOutput. בפונקציות האלה אפשר לקרוא או לעדכן את TextFieldBuffer לפי הצורך. לאחר מכן, השינויים האלה מועברים ל-TextFieldState או לצינור עיבוד הנתונים לעיבוד (render) במקרה של 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. בהמשך לדוגמה הקודמת של מספר הטלפון, צריך להוסיף סוגריים ודיסקים במקומות המתאימים:

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

OutputTransformation הוא ממשק של שיטה מופשטת אחת. כדי להטמיע OutputTransformation בהתאמה אישית, צריך לשנות את השיטה transformOutput:

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

כדי לעצב מספר טלפון, מוסיפים ל-OutputTransformation סוגריים פתוחים במדד 0, סוגריים סגורים במדד 4 וקו מפריד במדד 8:

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

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

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