จัดการข้อมูลจากผู้ใช้

TextField อนุญาตให้ผู้ใช้ป้อนและแก้ไขข้อความ หน้านี้อธิบายวิธีการ สามารถใช้อินพุต TextField, รูปแบบ TextField และกำหนดค่า ตัวเลือกอื่นๆ ของ TextField เช่น ตัวเลือกแป้นพิมพ์และการเปลี่ยนรูปแบบ ข้อมูลจากผู้ใช้

เลือกการใช้งาน TextField

การติดตั้งใช้งาน TextField มี 2 ระดับ ได้แก่

1. TextField คือการใช้ดีไซน์ Material เราขอแนะนําให้คุณเลือกใช้การติดตั้งใช้งานนี้เนื่องจากเป็นไปตามหลักเกณฑ์ของ Material Design
   • การจัดรูปแบบเริ่มต้นคือเติมสี
   • OutlinedTextField คือ โครงร่าง เวอร์ชันการจัดรูปแบบ
2. BasicTextField ช่วยให้ผู้ใช้แก้ไขข้อความผ่านฮาร์ดแวร์หรือซอฟต์แวร์ได้ แป้นพิมพ์ แต่ไม่มีการตกแต่ง เช่น คำใบ้หรือตัวยึดตำแหน่ง

@Composable
fun SimpleFilledTextFieldSample() {
    var text by remember { mutableStateOf("Hello") }

    TextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}
TextSnippets.kt

@Composable
fun SimpleOutlinedTextFieldSample() {
    var text by remember { mutableStateOf("") }

    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}
TextSnippets.kt

รูปแบบ TextField

TextField และ BasicTextField ใช้พารามิเตอร์ทั่วไปหลายรายการร่วมกันเพื่อปรับแต่ง ให้พวกเขา ดูรายการทั้งหมดของ TextField ได้ในTextField แหล่งที่มาของโค้ด ต่อไปนี้เป็นรายการพารามิเตอร์ที่มีประโยชน์บางส่วน

• singleLine
• maxLines
• textStyle

@Composable
fun StyledTextField() {
    var value by remember { mutableStateOf("Hello\nWorld\nInvisible") }

    TextField(
        value = value,
        onValueChange = { value = it },
        label = { Text("Enter text") },
        maxLines = 2,
        textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
        modifier = Modifier.padding(20.dp)
    )
}
TextSnippets.kt

เราขอแนะนำให้ใช้ TextField แทน BasicTextField เมื่อการออกแบบต้องใช้วัสดุ TextField หรือ OutlinedTextField แต่ควรใช้ BasicTextField เมื่อสร้างการออกแบบที่ไม่จำเป็นต้องมีการตกแต่งตามข้อมูลจำเพาะของ Material

อินพุตสไตล์ด้วย Brush API

คุณสามารถใช้ Brush API เพื่อจัดสไตล์ขั้นสูงใน TextField ได้ ส่วนต่อไปนี้จะอธิบายวิธีใช้แปรงเพื่อเพิ่มการไล่สีไปยังอินพุต TextField

ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ Brush API เพื่อจัดรูปแบบข้อความได้ที่หัวข้อเปิดใช้การจัดรูปแบบขั้นสูงด้วย Brush API

ข้อควรระวัง: การใช้งานปัจจุบันของ Brush API ใน TextStyle ยังอยู่ระหว่างการทดสอบ API เวอร์ชันทดลองอาจมีการเปลี่ยนแปลงในอนาคต

ใช้การไล่ระดับสีโดยใช้ TextStyle

หากต้องการใช้การไล่ระดับสีขณะที่คุณพิมพ์ภายใน TextField ให้ตั้งค่าแปรง ที่เลือกเป็น TextStyle สำหรับ TextField ของคุณ ในตัวอย่างนี้ เราใช้ แปรงในตัวพร้อม linearGradient เพื่อดูเอฟเฟกต์การไล่ระดับสีรุ้ง พิมพ์ข้อความลงใน TextField

var text by remember { mutableStateOf("") }
val brush = remember {
    Brush.linearGradient(
        colors = rainbowColors
    )
}
TextField(
    value = text, onValueChange = { text = it }, textStyle = TextStyle(brush = brush)
)
TextSnippets.kt

หมายเหตุ: อย่าลืมใช้ฟังก์ชัน remember เพื่อยืนยันแปรง การจัดองค์ประกอบใหม่ เมื่อสถานะ TextField เปลี่ยนแปลงในแต่ละอักขระที่พิมพ์ใหม่

รูปที่ 3 ใช้ buildAnnotatedString และ SpanStyle พร้อมกับ linearGradient เพื่อปรับแต่งเฉพาะข้อความบางส่วน

ตั้งค่าตัวเลือกแป้นพิมพ์

TextField ให้คุณตั้งค่าตัวเลือกการกำหนดค่าแป้นพิมพ์ เช่น แป้นพิมพ์ หรือเปิดการแก้ไขอัตโนมัติ หากแป้นพิมพ์รองรับ ใช้บ้าง อาจไม่รับประกันตัวเลือก หากซอฟต์แวร์แป้นพิมพ์ไม่เป็นไปตาม ที่ระบุไว้ที่นี่ รายการแป้นพิมพ์ที่รองรับมีดังนี้ ดังต่อไปนี้

• capitalization
• autoCorrect
• keyboardType
• imeAction

จัดรูปแบบอินพุต

TextField อนุญาตให้คุณตั้งค่า VisualTransformation กับค่าที่ป้อน เช่น การแทนที่อักขระด้วย * สำหรับรหัสผ่าน หรือ ใส่ขีดกลางสั้นทุกๆ 4 หลักสำหรับหมายเลขบัตรเครดิต:

@Composable
fun PasswordTextField() {
    var password by rememberSaveable { mutableStateOf("") }

    TextField(
        value = password,
        onValueChange = { password = it },
        label = { Text("Enter password") },
        visualTransformation = PasswordVisualTransformation(),
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password)
    )
}
TextSnippets.kt

ดูตัวอย่างเพิ่มเติมได้ในซอร์สโค้ด VisualTransformationSamples

ล้างอินพุต

งานทั่วไปเมื่อแก้ไขข้อความคือ นำอักขระนำหน้าออก เปลี่ยนสตริงอินพุตทุกครั้งที่มีการเปลี่ยนแปลง

ตัวอย่างเช่น คุณควรคิดว่าแป้นพิมพ์อาจมีขนาดที่กำหนดเอง แก้ไข onValueChange แต่ละรายการ กรณีนี้อาจเกิดขึ้นได้ เช่น เมื่อผู้ใช้ใช้การแก้ไขอัตโนมัติ แทนที่คำด้วยอีโมจิ หรือใช้ฟีเจอร์การแก้ไขอัจฉริยะอื่นๆ ถึง จัดการเรื่องนี้ได้อย่างถูกต้อง เขียนตรรกะการเปลี่ยนแปลง โดยมีสมมติฐานที่ว่า ข้อความปัจจุบันที่ส่งไปยัง onValueChange ไม่เกี่ยวข้องกับข้อความก่อนหน้าหรือข้อความถัดไป ค่าที่จะส่งไปยัง onValueChange

หากต้องการใช้ช่องข้อความซึ่งไม่อนุญาตให้ใช้ 0 นำหน้า คุณสามารถทำได้โดย ตัดเลขศูนย์นำหน้าทั้งหมดในทุกการเปลี่ยนแปลงค่า

@Composable
fun NoLeadingZeroes() {
    var input by rememberSaveable { mutableStateOf("") }
    TextField(
        value = input,
        onValueChange = { newText ->
            input = newText.trimStart { it == '0' }
        }
    )
}
TextSnippets.kt

หากต้องการควบคุมตำแหน่งเคอร์เซอร์ขณะทำความสะอาดข้อความ ให้ใช้การโอเวอร์โหลด TextFieldValue ของ TextField เป็นส่วนหนึ่งของสถานะ

แนวทางปฏิบัติแนะนำเกี่ยวกับสถานะ

ต่อไปนี้เป็นชุดแนวทางปฏิบัติแนะนำในการกำหนดและอัปเดต TextField เพื่อป้องกันปัญหาการป้อนข้อมูลในแอปของคุณ

• ใช้ MutableState เพื่อแสดงสถานะ TextField: หลีกเลี่ยงการใช้สตรีมแบบเรียลไทม์ เช่น StateFlow เพื่อแสดงสถานะ TextField เนื่องจากโครงสร้างเหล่านี้อาจทำให้เกิดความล่าช้าแบบไม่พร้อมกัน

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}
TextSnippets.kt

• หลีกเลี่ยงการรอเพื่ออัปเดตสถานะ: เมื่อเรียกใช้ onValueChange ให้อัปเดต TextField แบบซิงค์และทันทีโดยทำดังนี้

// SignUpViewModel.kt

class SignUpViewModel(private val userRepository: UserRepository) : ViewModel() {

    var username by mutableStateOf("")
        private set

    fun updateUsername(input: String) {
        username = input
    }
}

// SignUpScreen.kt

@Composable
fun SignUpScreen(/*...*/) {

    OutlinedTextField(
        value = viewModel.username,
        onValueChange = { username -> viewModel.updateUsername(username) }
        /*...*/
    )
}
TextSnippets.kt

• ตําแหน่งที่จะกําหนดสถานะ: หากสถานะ TextField ของคุณต้องมีการตรวจสอบตรรกะทางธุรกิจขณะที่คุณพิมพ์ การนำสถานะไปไว้ที่ ViewModel นั้นถูกต้อง หากไม่มี คุณสามารถใช้คอมโพสิเบิลหรือคลาสตัวเก็บสถานะเป็นแหล่งข้อมูล ดูข้อมูลเพิ่มเติมเกี่ยวกับตําแหน่งที่จะยกสถานะได้ในส่วนเอกสารประกอบการยกสถานะ

หมายเหตุ: ดูข้อมูลเพิ่มเติมเกี่ยวกับแนวทางปฏิบัติแนะนำเหล่านี้ได้ที่บล็อกโพสต์การจัดการสถานะอย่างมีประสิทธิภาพสำหรับ TextField ในเครื่องมือเขียน