Mengonfigurasi kolom teks

TextField memungkinkan pengguna memasukkan dan mengubah teks. Ada dua jenis kolom teks yang dapat Anda gunakan: kolom teks berbasis status dan kolom teks berbasis nilai. Pilih jenis yang ingin Anda tampilkan kontennya:

Kolom teks berbasis status Kolom teks berbasis nilai

Sebaiknya gunakan kolom teks berbasis status, karena kolom ini memberikan pendekatan yang lebih lengkap dan andal untuk mengelola status TextField. Tabel berikut menguraikan perbedaan antara jenis kolom teks ini, dan menyertakan keunggulan utama yang ditawarkan kolom teks berbasis status:

Fitur	Kolom teks berbasis nilai	Kolom teks berbasis status	Manfaat berbasis negara bagian
Pengelolaan status	Memperbarui status kolom teks dengan callback onValueChange. Anda bertanggung jawab untuk memperbarui value dalam status Anda sendiri berdasarkan perubahan yang dilaporkan oleh onValueChange.	Secara eksplisit menggunakan objek TextFieldState untuk mengelola status input teks (nilai, pilihan, dan komposisi). Status ini dapat diingat dan dibagikan.	Callback onValueChange telah dihapus, sehingga Anda tidak dapat memperkenalkan perilaku asinkron. Status tetap ada selama rekomposisi, konfigurasi, dan penghentian proses.
Transformasi visual	Menggunakan VisualTransformation untuk mengubah tampilan teks yang ditampilkan. Hal ini biasanya menangani pemformatan input dan output dalam satu langkah.	Menggunakan InputTransformation untuk mengubah input pengguna sebelum di-commit ke status, dan OutputTransformation untuk memformat konten kolom teks tanpa mengubah data status yang mendasarinya.	Anda tidak perlu lagi memberikan pemetaan offset antara teks mentah asli dan teks yang diubah dengan OutputTransformation.
Batas baris	Menerima singleLine: Boolean, maxLines: Int, dan minLines: Int untuk mengontrol jumlah baris.	Menggunakan lineLimits: TextFieldLineLimits untuk mengonfigurasi jumlah minimum dan maksimum baris yang dapat ditempati kolom teks.	Menghilangkan ambiguitas saat mengonfigurasi batas baris dengan menyediakan parameter lineLimits dari jenis TextFieldLineLimits.
Kolom teks aman	T/A	SecureTextField adalah composable yang dibuat di atas kolom teks berbasis status untuk menulis kolom sandi.	Memungkinkan Anda mengoptimalkan keamanan di balik layar, dan dilengkapi dengan UI yang telah ditetapkan dengan textObfuscationMode.

Halaman ini menjelaskan cara mengimplementasikan TextField, menata gaya input TextField, dan mengonfigurasi opsi TextField lainnya, seperti opsi keyboard dan mengubah input pengguna secara visual.

Memilih penerapan TextField

Ada dua tingkat penerapan TextField:

1. TextField adalah penerapan Desain Material. Sebaiknya pilih penerapan ini karena mengikuti panduan Desain Material:
   • Gaya default adalah filled
   • OutlinedTextField adalah versi gaya outlined
2. BasicTextField memungkinkan pengguna mengedit teks menggunakan keyboard hardware atau keyboard virtual, tetapi tidak memberikan dekorasi seperti petunjuk atau placeholder.

TextField(
    state = rememberTextFieldState(initialText = "Hello"),
    label = { Text("Label") }
)
StateBasedText.kt

OutlinedTextField(
    state = rememberTextFieldState(),
    label = { Text("Label") }
)
StateBasedText.kt

Gaya TextField

TextField dan BasicTextField berbagi banyak parameter umum untuk penyesuaian. Daftar lengkap untuk TextField tersedia di kode sumber TextField. Berikut adalah daftar tidak lengkap beberapa parameter yang berguna:

• 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

Sebaiknya gunakan TextField daripada BasicTextField saat desain Anda memanggil TextField atau OutlinedTextField Material. Namun, BasicTextField harus digunakan saat mem-build desain yang tidak memerlukan dekorasi dari spesifikasi Material.

Menata gaya input dengan Brush API

Anda dapat menggunakan Brush API untuk penataan gaya yang lebih canggih di TextField. Bagian berikut menjelaskan cara menggunakan Brush untuk menambahkan gradien berwarna ke input TextField.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan Brush API untuk menata gaya teks, lihat Mengaktifkan penataan gaya lanjutan dengan Brush API.

Menerapkan gradien berwarna menggunakan TextStyle

Untuk menerapkan gradien berwarna saat Anda mengetik dalam TextField, tetapkan kuas pilihan Anda sebagai TextStyle untuk TextField. Dalam contoh ini, kita menggunakan kuas bawaan dengan linearGradient untuk melihat efek gradien pelangi saat teks diketik ke dalam 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

Gambar 1. Efek gradien pelangi untuk konten TextField.

Mengelola status kolom teks

TextField menggunakan class holder status khusus yang disebut TextFieldState untuk konten dan pilihannya. TextFieldState dirancang untuk diangkat di mana pun yang sesuai dalam arsitektur Anda. Ada 2 properti utama yang disediakan oleh TextFieldState:

• initialText: Isi TextField.
• initialSelection: Menunjukkan posisi kursor atau pilihan.

Yang membedakan TextFieldState dari pendekatan lain, seperti callback onValueChange, adalah TextFieldState sepenuhnya mengenkapsulasi seluruh alur input. Hal ini termasuk menggunakan struktur data pendukung yang benar, menyisipkan filter dan pemformat, serta menyinkronkan semua pengeditan yang berasal dari berbagai sumber.

Catatan: Meskipun TextFieldState termasuk dalam modul Compose Foundation, modul ini tidak memiliki dependensi UI dan dirancang untuk menjadi holder status yang andal. TextFieldState hanya menggunakan struktur data yang disediakan oleh sistem snapshot Compose. Sebaiknya buat instance dan simpan instance TextFieldState di ViewModel Anda.

Anda dapat menggunakan TextFieldState() untuk mengangkat status di TextField. Untuk itu, sebaiknya gunakan fungsi rememberTextFieldState(). rememberTextFieldState() membuat instance TextFieldState di composable Anda, memastikan objek status diingat, dan menyediakan fungsi simpan dan pulihkan bawaan:

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

rememberTextFieldState dapat memiliki parameter kosong atau memiliki nilai awal yang diteruskan untuk merepresentasikan nilai teks pada inisialisasi. Jika nilai yang berbeda diteruskan dalam rekomposisi berikutnya, nilai status tidak akan diperbarui. Untuk memperbarui status setelah diinisialisasi, panggil metode edit di TextFieldState.

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

Gambar 2. TextField dengan "Username" sebagai teks awal.

Ubah teks dengan TextFieldBuffer

TextFieldBuffer berfungsi sebagai penampung teks yang dapat diedit, yang fungsinya mirip dengan StringBuilder. Class ini menyimpan konten teks dan informasi tentang pilihan.

Anda sering menemukan TextFieldBuffer sebagai cakupan penerima pada fungsi seperti TextFieldState.edit, InputTransformation.transformInput, atau OutputTransformation.transformOutput. Dalam fungsi ini, Anda dapat membaca atau memperbarui TextFieldBuffer sesuai kebutuhan. Setelah itu, perubahan ini akan di-commit ke TextFieldState, atau diteruskan ke pipeline rendering dalam kasus OutputTransformation.

Anda dapat menggunakan fungsi pengeditan standar seperti append, insert, replace, atau delete untuk mengubah konten buffer. Untuk mengubah status pilihan, tetapkan variabel selection: TextRange secara langsung, atau gunakan fungsi utilitas seperti placeCursorAtEnd atau selectAll. Pilihan itu sendiri diwakili oleh TextRange, dengan indeks awal bersifat inklusif dan indeks akhir bersifat eksklusif. TextRange dengan nilai awal dan akhir yang identik, seperti (3, 3), menandakan posisi kursor tanpa karakter yang dipilih.

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

Mengedit teks di TextFieldState

Ada beberapa metode yang memungkinkan Anda mengedit status secara langsung melalui variabel status:

• edit: Memungkinkan Anda mengedit konten status dan memberi Anda fungsi TextFieldBuffer sehingga Anda dapat menggunakan metode seperti insert, replace, append, dan lainnya.

  // 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: Menghapus teks saat ini, menggantinya dengan teks yang diberikan, dan menetapkan kursor di akhir.

  textFieldState.setTextAndPlaceCursorAtEnd("I really love Android")
  // textFieldState.text : I really love Android
  // textFieldState.selection : TextRange(21, 21)
  StateBasedText.kt

• clearText: Menghapus semua teks.

  textFieldState.clearText()
  // textFieldState.text :
  // textFieldState.selection : TextRange(0, 0)
  StateBasedText.kt

Untuk fungsi TextFieldState lainnya, lihat referensi TextFieldState.

Mengubah input pengguna

Bagian berikut menjelaskan cara mengubah input pengguna. Transformasi input memungkinkan Anda memfilter input TextField saat pengguna mengetik, sedangkan transformasi output memformat input pengguna sebelum ditampilkan di layar.

Memfilter input pengguna dengan transformasi input

Transformasi input memungkinkan Anda memfilter input dari pengguna. Misalnya, jika TextField Anda menerima nomor telepon Amerika, Anda hanya ingin menerima 10 digit. Hasil InputTransformation disimpan di TextFieldState.

Catatan: Jangan mengubah status di dalam panggilan InputTransformation.transformInput(). Sebagai gantinya, gunakan cakupan penerima TextFieldBuffer untuk mengedit teks.

Ada filter bawaan untuk kasus penggunaan InputTransformation umum. Untuk membatasi panjang, panggil InputTransformation.maxLength():

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine,
    inputTransformation = InputTransformation.maxLength(10)
)
StateBasedText.kt

Transformasi input kustom

InputTransformation adalah antarmuka fungsi tunggal. Saat menerapkan InputTransformation kustom, Anda harus mengganti TextFieldBuffer.transformInput:

class CustomInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
    }
}
StateBasedText.kt

Untuk nomor telepon, tambahkan transformasi input kustom yang hanya mengizinkan digit diketik ke dalam TextField:

class DigitOnlyInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
        if (!asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    }
}
StateBasedText.kt

Transformasi input berantai

Untuk menambahkan beberapa filter pada input teks, buat rantai InputTransformation menggunakan fungsi ekstensi then. Filter dijalankan secara berurutan. Sebagai praktik terbaik, terapkan filter yang paling selektif terlebih dahulu untuk menghindari transformasi yang tidak perlu pada data yang pada akhirnya akan difilter.

TextField(
    state = rememberTextFieldState(),
    inputTransformation = InputTransformation.maxLength(6)
        .then(CustomInputTransformation()),
)
StateBasedText.kt

Setelah menambahkan transformasi input, input TextField menerima maksimum 10 digit.

Memformat input sebelum ditampilkan

OutputTransformation memungkinkan Anda memformat input pengguna sebelum dirender di layar. Tidak seperti InputTransformation, pemformatan yang dilakukan melalui OutputTransformation tidak disimpan di TextFieldState. Berdasarkan contoh nomor telepon sebelumnya, Anda perlu menambahkan tanda kurung dan tanda hubung di tempat yang sesuai:

Gambar 3. Nomor telepon Amerika dengan format yang tepat dan indeks yang sesuai.

Ini adalah cara terbaru untuk menangani VisualTransformation dalam TextField berbasis nilai, dengan perbedaan utama bahwa Anda tidak perlu menghitung pemetaan offset-nya.

OutputTransformation adalah antarmuka metode abstrak tunggal. Untuk mengimplementasikan OutputTransformation kustom, Anda harus mengganti metode transformOutput:

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

Untuk memformat nomor telepon, tambahkan tanda kurung buka di indeks 0, tanda kurung tutup di indeks 4, dan tanda hubung di indeks 8 ke 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

Selanjutnya, tambahkan OutputTransformation Anda ke TextField:

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)
StateBasedText.kt

Cara kerja transformasi bersama-sama

Diagram berikut menunjukkan alur dari input teks ke transformasi hingga output:

Gambar 4. Diagram yang menunjukkan cara input teks melalui transformasi sebelum menjadi output teks.

1. Input diterima dari sumber input.
2. Input difilter melalui InputTransformation, yang disimpan di TextFieldState.
3. Input diteruskan melalui OutputTransformation untuk pemformatan.
4. Input ditampilkan dalam TextField.

Menetapkan opsi keyboard

TextField memungkinkan Anda menyetel opsi konfigurasi keyboard, seperti tata letak keyboard, atau mengaktifkan koreksi otomatis jika didukung oleh keyboard. Beberapa opsi mungkin tidak dijamin jika keyboard virtual tidak sesuai dengan opsi yang disediakan di sini. Berikut adalah daftar opsi keyboard yang didukung:

• capitalization
• autoCorrect
• keyboardType
• imeAction

Referensi lainnya

• Memformat nomor telepon secara otomatis di kolom teks
• Menampilkan atau menyembunyikan sandi berdasarkan tombol pengguna
• Memvalidasi input saat pengguna mengetik