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:

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") }
)

Kolom teks yang dapat diedit yang berisi kata 

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

Kolom teks yang dapat diedit, dengan batas dan label berwarna ungu.

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)
)

TextField banyak baris, dengan dua baris yang dapat diedit plus label

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.

Mengonfigurasi batas baris

Composable TextField mendukung scroll di sepanjang satu sumbu. Perilaku scroll ditentukan oleh parameter lineLimits. TextField yang dikonfigurasi untuk satu baris akan di-scroll secara horizontal, sedangkan TextField multi-baris akan di-scroll secara vertikal.

Gunakan TextFieldLineLimits untuk memilih konfigurasi baris yang sesuai untuk TextField Anda:

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine
)

Kolom teks satu baris dengan teks

Konfigurasi SingleLine memiliki karakteristik berikut:

  • Teks tidak pernah digabungkan, dan tidak mengizinkan baris baru.
  • TextField selalu memiliki tinggi tetap.
  • Jika teks meluap, teks akan di-scroll secara horizontal.

TextField(
    state = rememberTextFieldState("Hello\nWorld\nHello\nWorld"),
    lineLimits = TextFieldLineLimits.MultiLine(1, 4)
)

Kolom teks multibaris dengan teks

Konfigurasi MultiLine memiliki karakteristik berikut:

  • Menerima dua parameter: minHeightInLines dan maxHeightInLines.
  • Kolom teks memiliki tinggi minimal minHeightInLines.
  • Jika teks meluap, teks akan digabungkan.
  • Jika teks memerlukan lebih banyak baris, kolom akan bertambah hingga setinggi maxHeightInLines, dan di-scroll secara vertikal.

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)
)

Teks yang diketik di kolom teks, menampilkan efek gradien pelangi.
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.

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") }
)

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,
)

TextField dengan teks Username yang muncul di dalam kolom teks.
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, "-")
    }
)

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)

  • 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)

  • clearText: Menghapus semua teks.

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

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.

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

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

Transformasi input kustom

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

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

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()
        }
    }
}

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()),
)

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:

Nomor telepon Amerika, yang diformat dengan benar menggunakan tanda kurung, tanda hubung, dan indeks 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() {
    }
}

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, "-")
    }
}

Selanjutnya, tambahkan OutputTransformation Anda ke TextField:

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)

Cara kerja transformasi bersama-sama

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

Visualisasi cara input teks melalui transformasi sebelum menjadi output teks.
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

Class KeyboardOptions kini menyertakan parameter boolean baru, showKeyboardOnFocus, yang Anda gunakan secara khusus untuk komponen TextField yang terintegrasi dengan TextFieldState. Opsi ini mengatur perilaku keyboard virtual saat TextField mendapatkan fokus melalui cara selain interaksi pengguna langsung (misalnya, secara terprogram).

Jika KeyboardOptions.showKeyboardOnFocus ditetapkan ke benar (true), keyboard virtual tidak akan otomatis muncul jika TextField mendapatkan fokus secara tidak langsung. Dalam kasus tersebut, pengguna harus mengetuk TextField secara eksplisit untuk menampilkan keyboard.

Menentukan logika interaksi keyboard

Tombol tindakan di keyboard virtual Android memungkinkan respons interaktif dalam aplikasi Anda. Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi tombol tindakan, lihat bagian Menetapkan opsi keyboard.

Tombol tindakan keyboard virtual (ikon tanda centang) dilingkari merah.
Gambar 5. Tombol tindakan keyboard virtual.

Untuk menentukan apa yang terjadi saat pengguna mengetuk tombol tindakan ini, gunakan parameter onKeyboardAction. Parameter ini menerima antarmuka fungsional opsional bernama KeyboardActionHandler. Antarmuka KeyboardActionHandler berisi satu metode, onKeyboardAction(performDefaultAction: () -> Unit). Dengan menyediakan implementasi untuk metode onKeyboardAction ini, Anda dapat memperkenalkan logika kustom yang dijalankan saat pengguna menekan tombol tindakan keyboard.

Beberapa jenis tindakan keyboard standar dilengkapi dengan perilaku default bawaan. Misalnya, memilih ImeAction.Next atau ImeAction.Previous sebagai jenis tindakan akan, secara default, mengalihkan fokus ke kolom input berikutnya atau sebelumnya, masing-masing. Demikian pula, tombol tindakan yang ditetapkan ke ImeAction.Done biasanya akan menutup keyboard virtual. Fungsi default ini dijalankan secara otomatis dan tidak mengharuskan Anda menyediakan KeyboardActionHandler.

Anda juga dapat menerapkan perilaku kustom selain tindakan default ini. Saat Anda menyediakan KeyboardActionHandler, metode onKeyboardAction-nya akan menerima fungsi performDefaultAction. Anda dapat memanggil fungsi performDefaultAction() ini kapan saja dalam logika kustom untuk juga memicu perilaku default standar yang terkait dengan tindakan IME saat ini.

TextField(
    state = textFieldViewModel.usernameState,
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
    onKeyboardAction = { performDefaultAction ->
        textFieldViewModel.validateUsername()
        performDefaultAction()
    }
)

Cuplikan ini menggambarkan kasus penggunaan umum di layar pendaftaran yang menampilkan kolom nama pengguna. Untuk kolom ini, ImeAction.Next dipilih untuk tombol tindakan keyboard-nya. Pilihan ini memungkinkan navigasi yang cepat dan lancar ke kolom sandi berikutnya.

Selain navigasi standar ini, ada persyaratan untuk memulai proses validasi latar belakang untuk nama pengguna saat pengguna melanjutkan untuk memasukkan sandi mereka. Untuk memastikan bahwa perilaku pengalihan fokus default yang melekat pada ImeAction.Next dipertahankan bersama logika validasi kustom ini, fungsi performDefaultAction() dipanggil. Memanggil performDefaultAction() secara implisit akan memicu sistem pengelolaan fokus yang mendasarinya untuk memindahkan fokus ke elemen UI berikutnya yang sesuai, sehingga mempertahankan alur navigasi yang diharapkan.

Membuat kolom sandi yang aman

SecureTextField adalah composable yang dibuat di atas kolom teks berbasis status untuk menulis kolom sandi. Sebaiknya gunakan SecureTextField untuk membuat kolom teks sandi, karena kolom ini menyembunyikan input karakter secara default dan menonaktifkan tindakan potong dan salin.

SecureTextField memiliki textObfuscationMode, yang mengontrol cara pengguna melihat input karakter. textObfuscationMode memiliki opsi berikut:

  • Hidden: Menyembunyikan semua input. Perilaku default di platform desktop.

    Kolom teks aman tempat karakter yang diketik disembunyikan.

  • Visible: Menampilkan semua input.

    Kolom teks aman tempat karakter yang diketik terlihat.

  • RevealLastTyped: Menyembunyikan semua input kecuali karakter terakhir. Perilaku default di perangkat seluler.

    Kolom teks aman yang hanya menampilkan karakter terakhir yang diketik secara singkat.

Referensi lainnya