Kotak angka

Mewakili kontrol yang dapat digunakan untuk menampilkan dan mengedit angka. Ini mendukung validasi, peningkatan tahap, dan komputasi perhitungan langsung dari persamaan dasar, seperti perkalian, pembagian, penambahan, dan pengurangan.

Apakah ini kontrol yang tepat?

Anda dapat menggunakan kontrol NumberBox untuk mengambil dan menampilkan input matematika. Jika Anda memerlukan kotak teks yang dapat diedit yang menerima lebih dari angka, gunakan kontrol TextBox . Jika Anda memerlukan kotak teks yang dapat diedit yang menerima kata sandi atau input sensitif lainnya, lihat Kotak Kata Sandi. Jika Anda memerlukan kotak teks untuk memasukkan istilah pencarian, lihat AutoSuggestBox. Jika Anda perlu memasukkan atau mengedit teks yang diformat, lihat RichEditBox.

Recommendations

• Text dan Value memudahkan untuk mengambil nilai NumberBox sebagai String atau sebagai Double tanpa perlu mengonversi nilai di antara jenis. Saat mengubah nilai NumberBox secara terprogram, disarankan untuk melakukannya melalui properti Value. Value akan menimpa Text selama pengaturan awal. Setelah penyiapan awal, perubahan pada satu akan disebarkan ke yang lain, tetapi secara konsisten membuat perubahan terprogram melalui Value membantu menghindari kesalahpahaman konseptual bahwa NumberBox akan menerima karakter non-numerik melalui Text.
• Gunakan Header atau PlaceholderText untuk memberi tahu pengguna bahwa NumberBox hanya menerima karakter numerik sebagai input. Representasi angka yang dieja, seperti "satu", tidak akan menghasilkan nilai yang diterima.

Membuat NumberBox

• API penting:kelas NumberBox

Buka aplikasi Galeri WinUI 3 dan lihat NumberBox dalam tindakan

Aplikasi Galeri WinUI 3 mencakup contoh interaktif kontrol dan fitur WinUI. Dapatkan aplikasi dari Microsoft Store atau telusuri kode sumber pada GitHub.

Berikut adalah XAML untuk NumberBox dasar yang menunjukkan tampilan default. Gunakan x:Bind untuk memastikan data yang ditampilkan kepada pengguna tetap sinkron dengan data yang disimpan di aplikasi Anda.

<NumberBox Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}" />

Kotak Nomor Pelabelan

Gunakan Header atau PlaceholderText jika tujuan NumberBox tidak jelas. Header terlihat apakah NumberBox memiliki nilai atau tidak.

<NumberBox Header="Enter a number:"
    Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}" />

PlaceholderText ditampilkan di dalam NumberBox dan hanya akan muncul ketika Value diatur ke NaN atau ketika input dibersihkan oleh pengguna.

<NumberBox PlaceholderText="1+2^2"
    Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}" />

Mengaktifkan dukungan penghitungan

AcceptsExpression Mengatur properti ke true memungkinkan NumberBox mengevaluasi ekspresi sebaris dasar seperti perkalian, pembagian, penambahan, dan pengurangan menggunakan urutan operasi standar. Evaluasi dipicu pada hilangnya fokus atau ketika pengguna menekan tombol "Enter". Setelah ekspresi dievaluasi, bentuk asli ekspresi tidak dipertahankan.

<NumberBox Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}"
    AcceptsExpression="True" />

Penambahan dan pengurangan langkah

SmallChange Gunakan properti untuk mengonfigurasi berapa banyak nilai di dalam NumberBox yang diubah saat NumberBox dalam fokus dan pengguna:

• Gulungan
• menekan tombol panah atas
• menekan tombol panah bawah

LargeChange Gunakan properti untuk mengonfigurasi berapa banyak nilai di dalam NumberBox yang diubah saat NumberBox dalam fokus dan pengguna menekan tombol PageUp atau PageDown.

SpinButtonPlacementMode Gunakan properti untuk mengaktifkan tombol yang dapat diklik untuk menaikkan atau mengurangi nilai dalam NumberBox berdasarkan jumlah yang ditentukan oleh SmallChange properti . Tombol-tombol ini akan dinonaktifkan jika nilai Maksimum atau Minimum akan dilampaui dengan langkah lain.

Atur SpinButtonPlacementMode ke Inline untuk mengaktifkan tombol agar muncul di samping kontrol.

<NumberBox Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}"
    SmallChange="10"
    LargeChange="100"
    SpinButtonPlacementMode="Inline" />

Atur SpinButtonPlacementMode ke Compact untuk mengaktifkan tombol agar muncul sebagai Flyout hanya saat NumberBox dalam fokus.

<NumberBox Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}"
    SmallChange="10"
    LargeChange="100"
    SpinButtonPlacementMode="Compact" />

Mengaktifkan validasi input

Pengaturan ValidationMode ke InvalidInputOverwritten akan memungkinkan NumberBox untuk menggantikan input yang tidak valid yang bukan angka atau rumus yang sah dengan nilai sah terakhir saat evaluasi dipicu ketika kehilangan fokus atau menekan tombol "Enter".

<NumberBox Header="Quantity"
    Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}"
    ValidationMode="InvalidInputOverwritten" />

Pengaturan ValidationMode untuk Disabled memungkinkan validasi input kustom dikonfigurasi.

Sehubungan dengan titik desimal dan koma, pemformatan yang digunakan oleh pengguna akan digantikan oleh pemformatan yang dikonfigurasi untuk NumberBox. Kesalahan validasi input tidak akan dipicu.

Pemformatan input

Pemformatan angka dapat digunakan untuk memformat nilai dari NumberBox dengan mengonfigurasi instans kelas pemformatan dan menetapkannya ke properti NumberFormatter. Angka desimal, mata uang, persen, dan angka signifikan adalah beberapa kelas pemformatan angka yang tersedia. Perhatikan bahwa pembulatan juga ditentukan oleh sifat-sifat pemformatan angka.

Berikut adalah contoh penggunaan DecimalFormatter untuk memformat nilai NumberBox untuk memiliki satu digit bilangan bulat, dua digit pecahan, dan membulatkan ke atas ke 0,25 terdekat:

<NumberBox  x:Name="FormattedNumberBox"
    Value="{x:Bind Path=ViewModel.NumberBoxValue, Mode=TwoWay}" />

private void SetNumberBoxNumberFormatter()
{
    IncrementNumberRounder rounder = new IncrementNumberRounder();
    rounder.Increment = 0.25;
    rounder.RoundingAlgorithm = RoundingAlgorithm.RoundUp;

    DecimalFormatter formatter = new DecimalFormatter();
    formatter.IntegerDigits = 1;
    formatter.FractionDigits = 2;
    formatter.NumberRounder = rounder;
    FormattedNumberBox.NumberFormatter = formatter;
}

Sehubungan dengan titik desimal dan koma, pemformatan yang digunakan oleh pengguna akan digantikan oleh pemformatan yang dikonfigurasi untuk NumberBox. Kesalahan validasi input tidak akan dipicu.

Komentar

Cakupan Input

Number akan digunakan untuk cakupan input. Cakupan input ini dimaksudkan untuk bekerja dengan digit 0-9. Ini mungkin ditimpa tetapi jenis InputScope alternatif tidak akan didukung secara eksplisit.

Bukan Angka

Ketika NumberBox dibersihkan dari input, Value akan diatur ke NaN untuk menunjukkan tidak ada nilai numerik yang ada.

Evaluasi Ekspresi

NumberBox menggunakan notasi infiks untuk mengevaluasi ekspresi. Dalam urutan prioritas, operator yang diizinkan adalah:

• ^
• */
• +-

Perhatikan bahwa tanda kurung dapat digunakan untuk mengambil alih aturan prioritas.