Kotak teks
Kontrol TextBox memungkinkan pengguna mengetik teks ke dalam aplikasi. Biasanya digunakan untuk mengambil satu baris teks, tetapi dapat dikonfigurasi untuk mengambil beberapa baris teks. Teks ditampilkan di layar dalam format teks biasa yang sederhana, seragam.
TextBox memiliki sejumlah fitur yang dapat menyederhanakan entri teks. Muncul dengan menu konteks bawaan yang akrab dengan dukungan untuk menyalin dan menempelkan teks. Tombol "hapus semua" memungkinkan pengguna dengan cepat menghapus semua teks yang telah dimasukkan. Ini juga memiliki kemampuan pemeriksaan ejaan bawaan dan diaktifkan secara default.
Apakah ini kontrol yang tepat?
Gunakan kontrol TextBox untuk memungkinkan pengguna memasukkan dan mengedit teks yang tidak diformat, seperti dalam formulir. Anda bisa menggunakan properti Teks untuk mendapatkan dan mengatur teks di TextBox.
Anda dapat membuat TextBox baca-saja, tetapi ini harus menjadi status sementara bersyar. Jika teks tidak pernah dapat diedit, pertimbangkan untuk menggunakan TextBlock sebagai gantinya.
Gunakan kontrol PasswordBox untuk mengumpulkan kata sandi atau data privat lainnya, seperti nomor Jaminan Sosial. Kotak kata sandi terlihat seperti kotak input teks, kecuali kotak tersebut merender poin sebagai pengganti teks yang telah dimasukkan.
Gunakan kontrol AutoSuggestBox untuk memungkinkan pengguna memasukkan istilah pencarian atau untuk memperlihatkan kepada pengguna daftar saran untuk dipilih saat mereka mengetik.
Gunakan RichEditBox untuk menampilkan dan mengedit file teks kaya.
Untuk informasi selengkapnya tentang memilih kontrol teks yang tepat, lihat artikel Kontrol teks .
Rekomendasi
- Gunakan teks label atau tempat penampung jika tujuan kotak teks tidak jelas. Label terlihat apakah kotak input teks memiliki nilai atau tidak. Teks tempat penampung ditampilkan di dalam kotak input teks dan menghilang setelah nilai dimasukkan.
- Beri kotak teks lebar yang sesuai untuk rentang nilai yang bisa dimasukkan. Word panjang bervariasi di antara bahasa, jadi mempertimbangkan pelokalan jika Anda ingin aplikasi Anda siap untuk dunia.
- Kotak input teks biasanya baris tunggal (
TextWrap = "NoWrap"). Saat pengguna perlu memasukkan atau mengedit string panjang, atur kotak input teks ke multibaris (TextWrap = "Wrap"). - Umumnya, kotak input teks digunakan untuk teks yang dapat diedit. Tetapi Anda dapat membuat kotak input teks baca-saja sehingga kontennya dapat dibaca, dipilih, dan disalin, tetapi tidak diedit.
- Jika Anda perlu mengurangi kekacauan dalam tampilan, pertimbangkan untuk membuat sekumpulan kotak input teks hanya muncul saat kotak centang pengontrol dicentang. Anda juga dapat mengikat status kotak input teks yang diaktifkan ke kontrol seperti kotak centang.
- Pertimbangkan perilaku kotak input teks yang Anda inginkan saat berisi nilai dan pengguna mengetuknya. Perilaku default sesuai untuk mengedit nilai daripada menggantinya; titik penyisipan ditempatkan di antara kata-kata dan tidak ada yang dipilih. Jika mengganti adalah kasus penggunaan yang paling umum untuk kotak input teks tertentu, Anda dapat memilih semua teks di bidang setiap kali kontrol menerima fokus, dan mengetik menggantikan pilihan.
Kotak input baris tunggal
Gunakan beberapa kotak teks baris tunggal untuk mengambil banyak bagian kecil informasi teks. Jika kotak teks terkait secara alami, kelompokkan kotak teks tersebut bersama-sama.
Buat ukuran kotak teks baris tunggal sedikit lebih lebar dari input terpanjang yang diantisipasi. Jika melakukannya membuat kontrol terlalu lebar, pisahkan menjadi dua kontrol. Misalnya, Anda dapat membagi input alamat tunggal menjadi "Alamat baris 1" dan "Baris alamat 2".
Atur panjang maksimum untuk karakter yang dapat dimasukkan. Jika sumber data cadangan tidak mengizinkan string input yang panjang, batasi input dan gunakan popup validasi untuk memberi tahu pengguna saat mereka mencapai batas.
Gunakan kontrol input teks baris tunggal untuk mengumpulkan potongan kecil teks dari pengguna.
Contoh berikut menunjukkan kotak teks satu baris untuk mengambil jawaban atas pertanyaan keamanan. Jawabannya diharapkan pendek, sehingga kotak teks satu baris sesuai di sini.
Gunakan sekumpulan kontrol input teks baris tunggal berukuran pendek dan tetap untuk memasukkan data dengan format tertentu.
Gunakan kontrol input teks satu baris yang tidak dibatasi untuk memasukkan atau mengedit string, dikombinasikan dengan tombol perintah yang membantu pengguna memilih nilai yang valid.
Kontrol input teks multibaris
Saat Anda membuat kotak teks kaya, sediakan tombol gaya dan terapkan tindakannya.
Gunakan font yang konsisten dengan gaya aplikasi Anda.
Buat tinggi kontrol teks cukup tinggi untuk mengakomodasi entri umum.
Saat mengambil rentang teks yang panjang dengan karakter maksimum atau jumlah kata, gunakan kotak teks biasa dan berikan penghitung yang berjalan langsung untuk menunjukkan kepada pengguna berapa banyak karakter atau kata yang tersisa sebelum mencapai batas. Anda harus membuat penghitung sendiri; letakkan di bawah kotak teks dan perbarui secara dinamis saat pengguna memasukkan setiap karakter atau kata.
Jangan biarkan kontrol input teks Anda tumbuh tinggi saat pengguna mengetik.
Jangan gunakan kotak teks multibaris saat pengguna hanya memerlukan satu baris.
Jangan gunakan kontrol teks kaya jika kontrol teks biasa memadai.
UWP dan WinUI 2
Penting
Informasi dan contoh dalam artikel ini dioptimalkan untuk aplikasi yang menggunakan SDK Aplikasi Windows dan WinUI 3, tetapi umumnya berlaku untuk aplikasi UWP yang menggunakan WinUI 2. Lihat referensi API UWP untuk informasi dan contoh spesifik platform.
Bagian ini berisi informasi yang Anda butuhkan untuk menggunakan kontrol di aplikasi UWP atau WinUI 2.
API untuk kontrol ini ada di namespace Windows.UI.Xaml.Controls .
- UWP API:Kelas TextBox, properti Teks
- Buka aplikasi Galeri WinUI 2 dan lihat TextBox beraksi. Aplikasi WinUI 2 Gallery mencakup contoh interaktif sebagian besar kontrol, fitur, dan fungsi WinUI 2. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub.
Sebaiknya gunakan WinUI 2 terbaru untuk mendapatkan gaya dan templat terbaru untuk semua kontrol. WinUI 2.2 atau yang lebih baru menyertakan templat baru untuk kontrol ini yang menggunakan sudut bulat. Untuk informasi selengkapnya, lihat Radius sudut.
Membuat kotak teks
- API Penting:Kelas TextBox, properti Teks
Aplikasi WinUI 3 Gallery mencakup contoh interaktif sebagian besar kontrol, fitur, dan fungsi WinUI 3. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub
Berikut adalah XAML untuk kotak teks sederhana dengan teks header dan tempat penampung.
<TextBox Width="500" Header="Notes" PlaceholderText="Type your notes here"/>
TextBox textBox = new TextBox();
textBox.Width = 300;
textBox.Header = "Notes";
textBox.PlaceholderText = "Type your notes here";
// Add the TextBox to the visual tree.
rootGrid.Children.Add(textBox);
Berikut adalah kotak teks yang dihasilkan dari XAML ini.
Menggunakan kotak teks untuk input data dalam formulir
Biasanya menggunakan kotak teks untuk menerima input data pada formulir, dan menggunakan properti Teks untuk mendapatkan string teks lengkap dari kotak teks. Anda biasanya menggunakan peristiwa seperti klik tombol kirim untuk mengakses properti Teks, tetapi Anda dapat menangani peristiwa TextChanged atau TextChanging jika Anda perlu melakukan sesuatu saat teks berubah.
Contoh ini memperlihatkan cara mendapatkan dan mengatur konten kotak teks saat ini.
<TextBox name="SampleTextBox" Text="Sample Text"/>
string sampleText = SampleTextBox.Text;
...
SampleTextBox.Text = "Sample text retrieved";
Anda bisa menambahkan Header (atau label) dan PlaceholderText (atau marka air) ke kotak teks untuk memberi pengguna indikasi untuk apa kotak teks tersebut. Untuk mengkustomisasi tampilan header, Anda bisa mengatur properti HeaderTemplate alih-alih Header. Untuk informasi desain, lihat Panduan untuk label.
Anda dapat membatasi jumlah karakter yang dapat di ketik pengguna dengan mengatur properti MaxLength . Namun, MaxLength tidak membatasi panjang teks yang ditempelkan. Gunakan peristiwa Tempel untuk mengubah teks yang ditempelkan jika ini penting untuk aplikasi Anda.
Kotak teks menyertakan tombol kosongkan semua ("X") yang muncul saat teks dimasukkan dalam kotak. Saat pengguna mengklik "X", teks dalam kotak teks dikosongkan. Kelihatannya seperti ini.
Tombol hapus semua ditampilkan hanya untuk kotak teks satu baris yang dapat diedit yang berisi teks dan memiliki fokus.
Tombol hapus semua tidak ditampilkan dalam salah satu kasus ini:
- IsReadOnly adalah benar
- AcceptsReturn adalah true
- TextWrap memiliki nilai selain NoWrap
Contoh ini memperlihatkan cara mendapatkan dan mengatur konten kotak teks saat ini.
<TextBox name="SampleTextBox" Text="Sample Text"/>
string sampleText = SampleTextBox.Text;
...
SampleTextBox.Text = "Sample text retrieved";
Membuat kotak teks baca-saja
Anda dapat membuat kotak teks baca-saja dengan mengatur properti IsReadOnly ke true. Anda biasanya mengalihkan properti ini di kode aplikasi berdasarkan kondisi di aplikasi Anda. Jika memerlukan teks yang selalu baca-saja, pertimbangkan untuk menggunakan TextBlock sebagai gantinya.
Anda dapat membuat TextBox baca-saja dengan mengatur properti IsReadOnly ke true. Misalnya, Anda mungkin memiliki TextBox bagi pengguna untuk memasukkan komentar yang hanya diaktifkan dalam kondisi tertentu. Anda dapat membuat TextBox baca-saja hingga kondisi terpenuhi. Jika Anda hanya perlu menampilkan teks, pertimbangkan untuk menggunakan TextBlock atau RichTextBlock sebagai gantinya.
Kotak teks baca-saja terlihat sama dengan kotak teks baca/tulis, sehingga mungkin membingungkan pengguna. Pengguna dapat memilih dan menyalin teks. IsEnabled
Mengaktifkan input multibaris
Ada dua properti yang bisa Anda gunakan untuk mengontrol apakah kotak teks menampilkan teks pada lebih dari satu baris. Anda biasanya mengatur kedua properti untuk membuat kotak teks multibaris.
- Untuk mengizinkan kotak teks memperbolehkan dan menampilkan baris baru atau mengembalikan karakter, atur properti AcceptsReturn ke true.
- Untuk mengaktifkan pembungkusan teks, atur properti TextWrapping ke Wrap. Ini menyebabkan teks dibungkus saat mencapai tepi kotak teks, terlepas dari karakter pemisah baris.
Catatan
TextBox dan RichEditBox tidak mendukung nilai WrapWholeWords untuk properti TextWrapping mereka. Jika Anda mencoba menggunakan WrapWholeWords sebagai nilai untuk TextBox.TextWrapping atau RichEditBox.TextWrapping pengecualian argumen yang tidak valid akan dilemparkan.
Kotak teks multibaris akan terus bertambah secara vertikal saat teks dimasukkan kecuali dibatasi oleh properti Tinggi atau MaxHeight , atau oleh kontainer induk. Anda harus menguji bahwa kotak teks multibaris tidak tumbuh di luar area yang terlihat, dan membatasi pertumbuhannya jika terjadi. Kami menyarankan agar Anda selalu menentukan tinggi yang sesuai untuk kotak teks multibaris, dan tidak membiarkannya bertambah tinggi sebagai jenis pengguna.
Menggulir menggunakan roda gulir atau sentuhan diaktifkan secara otomatis saat diperlukan. Namun, bilah gulir vertikal tidak terlihat secara default. Anda dapat menampilkan bilah gulir vertikal dengan mengatur ScrollViewer.VerticalScrollBarVisibility ke Auto pada ScrollViewer yang disematkan, seperti yang ditunjukkan di sini.
<TextBox AcceptsReturn="True" TextWrapping="Wrap"
MaxHeight="172" Width="300" Header="Description"
ScrollViewer.VerticalScrollBarVisibility="Auto"/>
TextBox textBox = new TextBox();
textBox.AcceptsReturn = true;
textBox.TextWrapping = TextWrapping.Wrap;
textBox.MaxHeight = 172;
textBox.Width = 300;
textBox.Header = "Description";
ScrollViewer.SetVerticalScrollBarVisibility(textBox, ScrollBarVisibility.Auto);
Berikut tampilan kotak teks setelah teks ditambahkan.
Memformat tampilan teks
Gunakan properti TextAlignment untuk meratakan teks dalam kotak teks. Untuk meratakan kotak teks di dalam tata letak halaman, gunakan properti HorizontalAlignment dan VerticalAlignment .
Meskipun kotak teks hanya mendukung teks yang tidak diformat, Anda bisa mengkustomisasi bagaimana teks ditampilkan di kotak teks agar sesuai dengan merek Anda. Anda dapat mengatur properti Kontrol standar seperti FontFamily, FontSize, FontStyle, Background, Foreground, dan CharacterSpacing untuk mengubah tampilan teks. Properti ini hanya memengaruhi cara kotak teks menampilkan teks secara lokal, jadi jika Anda menyalin dan menempelkan teks ke dalam kontrol teks kaya, misalnya, tidak ada pemformatan yang akan diterapkan.
Contoh ini memperlihatkan kotak teks baca-saja dengan beberapa properti diatur untuk menyesuaikan tampilan teks.
<TextBox Text="Sample Text" IsReadOnly="True"
FontFamily="Verdana" FontSize="24"
FontWeight="Bold" FontStyle="Italic"
CharacterSpacing="200" Width="300"
Foreground="Blue" Background="Beige"/>
TextBox textBox = new TextBox();
textBox.Text = "Sample Text";
textBox.IsReadOnly = true;
textBox.FontFamily = new FontFamily("Verdana");
textBox.FontSize = 24;
textBox.FontWeight = Windows.UI.Text.FontWeights.Bold;
textBox.FontStyle = Windows.UI.Text.FontStyle.Italic;
textBox.CharacterSpacing = 200;
textBox.Width = 300;
textBox.Background = new SolidColorBrush(Windows.UI.Colors.Beige);
textBox.Foreground = new SolidColorBrush(Windows.UI.Colors.Blue);
// Add the TextBox to the visual tree.
rootGrid.Children.Add(textBox);
Kotak teks yang dihasilkan terlihat seperti ini.
Mengubah menu konteks
Secara default, perintah yang ditampilkan di menu konteks kotak teks bergantung pada status kotak teks. Misalnya, perintah berikut dapat ditampilkan saat kotak teks dapat diedit.
| Perintah | Ditampilkan ketika... |
|---|---|
| Menyalin | teks dipilih. |
| Potong | teks dipilih. |
| Tempel | clipboard berisi teks. |
| Memilih semua | Kotak Teks berisi teks. |
| Undo | teks telah diubah. |
Untuk mengubah perintah yang ditampilkan di menu konteks, tangani peristiwa ContextMenuOpening . Untuk contohnya, lihat Menyesuaikan CommandBarFlyout RichEditBox - menambahkan contoh 'Bagikan' di Galeri WinUI 2. Untuk informasi desain, lihat Panduan untuk menu konteks.
Pilih, salin, dan tempel
Anda bisa mendapatkan atau mengatur teks yang dipilih dalam kotak teks menggunakan properti SelectedText . Gunakan properti SelectionStart dan SelectionLength , dan metode Pilih dan PilihSemua , untuk memanipulasi pilihan teks. Tangani peristiwa SelectionChanged untuk melakukan sesuatu saat pengguna memilih atau membatalkan pilihan teks. Anda dapat mengubah warna yang digunakan untuk menyorot teks yang dipilih dengan mengatur properti SelectionHighlightColor .
TextBox mendukung salin dan tempel secara default. Anda dapat menyediakan penanganan kustom peristiwa Tempel pada kontrol teks yang dapat diedit di aplikasi Anda. Misalnya, Anda dapat menghapus pemisah baris dari alamat multibaris saat menempelkannya ke dalam kotak pencarian satu baris. Atau, Anda mungkin memeriksa panjang teks yang ditempelkan dan memperingatkan pengguna jika melebihi panjang maksimum yang dapat disimpan ke database. Untuk informasi dan contoh selengkapnya, lihat peristiwa Tempel .
Di sini, kami memiliki contoh properti dan metode ini yang digunakan. Saat Anda memilih teks di kotak teks pertama, teks yang dipilih ditampilkan di kotak teks kedua, yang bersifat baca-saja. Nilai properti SelectionLength dan SelectionStart diperlihatkan dalam dua blok teks. Ini dilakukan menggunakan peristiwa SelectionChanged .
<StackPanel>
<TextBox x:Name="textBox1" Height="75" Width="300" Margin="10"
Text="The text that is selected in this TextBox will show up in the read only TextBox below."
TextWrapping="Wrap" AcceptsReturn="True"
SelectionChanged="TextBox1_SelectionChanged" />
<TextBox x:Name="textBox2" Height="75" Width="300" Margin="5"
TextWrapping="Wrap" AcceptsReturn="True" IsReadOnly="True"/>
<TextBlock x:Name="label1" HorizontalAlignment="Center"/>
<TextBlock x:Name="label2" HorizontalAlignment="Center"/>
</StackPanel>
private void TextBox1_SelectionChanged(object sender, RoutedEventArgs e)
{
textBox2.Text = textBox1.SelectedText;
label1.Text = "Selection length is " + textBox1.SelectionLength.ToString();
label2.Text = "Selection starts at " + textBox1.SelectionStart.ToString();
}
Berikut adalah hasil dari kode ini.
Pilih keyboard yang tepat untuk kontrol teks Anda
Untuk membantu pengguna memasukkan data menggunakan keyboard sentuh, atau Panel Input Lunak (SIP), Anda dapat mengatur cakupan input kontrol teks agar sesuai dengan jenis data yang diharapkan dimasukkan pengguna.
Keyboard sentuh dapat digunakan untuk entri teks saat aplikasi Anda berjalan di perangkat dengan layar sentuh. Keyboard sentuh dipanggil saat pengguna mengetuk bidang input yang dapat diedit, seperti TextBox atau RichEditBox. Anda dapat membuatnya jauh lebih cepat dan lebih mudah bagi pengguna untuk memasukkan data di aplikasi Anda dengan mengatur cakupan input kontrol teks agar sesuai dengan jenis data yang Anda harapkan untuk dimasukkan pengguna. Cakupan input memberikan petunjuk kepada sistem tentang jenis input teks yang diharapkan oleh kontrol sehingga sistem dapat menyediakan tata letak keyboard sentuh khusus untuk jenis input.
Misalnya, jika kotak teks hanya digunakan untuk memasukkan PIN 4 digit, atur properti InputScope ke Angka. Ini memberi tahu sistem untuk menampilkan tata letak keypad angka, yang memudahkan pengguna untuk memasukkan PIN.
Penting Cakupan input tidak menyebabkan validasi input dilakukan, dan tidak mencegah pengguna memberikan input apa pun melalui keyboard perangkat keras atau perangkat input lainnya. Anda masih bertanggung jawab untuk memvalidasi input dalam kode Anda sesuai kebutuhan.
Properti lain yang memengaruhi keyboard sentuh adalah IsSpellCheckEnabled, IsTextPredictionEnabled, dan PreventKeyboardDisplayOnProgrammaticFocus. (IsSpellCheckEnabled juga memengaruhi TextBox saat keyboard perangkat keras digunakan.)
Untuk informasi dan contoh selengkapnya, lihat Menggunakan cakupan input untuk mengubah keyboard sentuh dan dokumentasi properti.
Dapatkan kode sampel
- Sampel Galeri WinUI - Lihat semua kontrol XAML dalam format interaktif.
Artikel terkait
Windows developer
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk