Zahlenbox

Stellt ein Steuerelement dar, das zum Anzeigen und Bearbeiten von Zahlen verwendet werden kann. Dies unterstützt die Validierung, das schrittweise Inkrementieren und die Inline-Berechnung grundlegender Gleichungen, wie z. B. Multiplikation, Division, Addition und Subtraktion.

Ist dies das richtige Steuerelement?

Sie können ein NumberBox-Steuerelement verwenden, um mathematische Eingaben zu erfassen und anzuzeigen. Wenn Sie ein bearbeitbares Textfeld benötigen, das mehr als Zahlen akzeptiert, verwenden Sie das TextBox-Steuerelement . Wenn Sie ein bearbeitbares Textfeld benötigen, das Kennwörter oder andere vertrauliche Eingaben akzeptiert, lesen Sie PasswordBox. Wenn Sie ein Textfeld zum Eingeben von Suchbegriffen benötigen, lesen Sie AutoSuggestBox. Wenn Sie formatierten Text eingeben oder bearbeiten müssen, lesen Sie RichEditBox.

Recommendations

• Mit Text und Value kann der Wert einer NumberBox leicht als Zeichenfolge oder als Double-Wert erfasst werden, ohne dass der Wert zwischen den Typen umgewandelt werden müsste. Beim programmgesteuerten Ändern des Werts eines NumberBox-Objekts wird empfohlen, dies über die Eigenschaft Value zu tun. Value überschreibt Text während der Ersteinrichtung. Nach der ursprünglichen Einrichtung werden Änderungen am einen Typ an den anderen weitergegeben, die einheitliche Verwendung von Value für programmgesteuerte Änderungen hilft aber, konzeptionelle Missverständnisse, dass NumberBox nicht numerische Zeichen über Text akzeptiert, zu vermeiden.
• Verwenden Sie Header oder PlaceholderText, um Benutzer darüber zu informieren, dass NumberBox nur Ziffern als Eingabe unterstützt. Die Wortdarstellung von Zahlen, wie etwa "Eins", führt nicht zu einem akzeptierten Wert.

Erstellen einer NumberBox

Die WinUI 3 Gallery-App enthält interaktive Beispiele für WinUI-Steuerelemente und -Features. Rufen Sie die App aus dem Microsoft Store ab, oder durchsuchen Sie den Quellcode auf GitHub.

Hier ist das XAML für eine einfache NumberBox, die das Standardaussehen demonstriert. Verwenden Sie "x:Bind" , um sicherzustellen, dass die für den Benutzer angezeigten Daten mit den in Ihrer App gespeicherten Daten synchronisiert bleiben.

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

Beschriftung der NumberBox

Verwenden Sie Header oder PlaceholderText, wenn der Zweck der NumberBox nicht eindeutig ist. Header ist immer sichtbar, unabhängig davon, ob die NumberBox einen Wert aufweist.

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

PlaceholderText wird innerhalb des Zahlenfelds angezeigt und ist nur sichtbar, wenn Value auf NaN festgelegt ist oder die Eingabe vom Benutzer gelöscht wird.

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

Aktivieren der Berechnungsunterstützung

Wenn Sie die AcceptsExpression-Eigenschaft auf true festlegen, kann NumberBox einfache Inline-Ausdrücke wie Multiplikation, Division, Addition und Subtraktion in der Standardreihenfolge der Operationen berechnen. Die Auswertung wird durch den Verlust des Eingabefokus oder durch Drücken der EINGABETASTE durch den Benutzer ausgelöst. Nach der Auswertung eines Ausdrucks bleibt dessen ursprüngliche Form nicht erhalten.

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

Inkrementelle und dekrementelle Schritte

Verwenden Sie die SmallChange-Eigenschaft, um zu konfigurieren, wie stark sich der Wert in einem NumberBox ändert, wenn die NumberBox den Fokus hat und der Benutzer einen Wert ändert.

• Scrollen
• Drückt die Nach-oben-Taste
• Drücken der NACH-UNTEN-TASTE

Verwenden Sie die LargeChange-Eigenschaft, um zu konfigurieren, wie stark sich der Wert in einer NumberBox ändert, wenn die NumberBox den Fokus hat und der Benutzer die NACH-OBEN- oder NACH-UNTEN-TASTE drückt.

Verwenden Sie die SpinButtonPlacementMode-Eigenschaft, um Schaltflächen zu aktivieren, mit denen Sie den Wert im Zahlenfeld durch Klicken um den in der SmallChange-Eigenschaft angegebenen Betrag erhöhen oder verringern können. Diese Schaltflächen werden deaktiviert, wenn mit dem nächsten Schritt ein Maximal- oder Minimalwert über- bzw. unterschritten würde.

Legen Sie SpinButtonPlacementMode auf Inline fest, um die Darstellung der Schaltflächen neben dem Steuerelement zu aktivieren.

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

Legen Sie SpinButtonPlacementMode auf Compact fest, um das Erscheinen der Schaltflächen als Flyout zu aktivieren, wenn die NumberBox fokussiert ist.

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

Aktivieren der Eingabevalidierung

Das Festlegen von ValidationMode auf InvalidInputOverwritten ermöglicht es NumberBox, ungültige Eingaben, die weder numerisch noch als gültige Formel zu verstehen sind, mit dem zuletzt gültigen Wert zu überschreiben, wenn die Auswertung durch den Verlust des Fokus oder das Drücken der EINGABETASTE ausgelöst wird.

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

Das Festlegen von ValidationMode auf Disabled ermöglicht die Konfiguration von benutzerdefinierter Eingabevalidierung.

Im Hinblick auf Dezimalpunkte und Kommas wird die vom User verwendete Formatierung durch die für die NumberBox konfigurierte Formatierung ersetzt. Es wird kein Eingabevalidierungsfehler ausgelöst.

Formatieren der Eingabe

Die Zahlenformatierung kann verwendet werden, um den Wert eines NumberBox-Objekts zu formatieren, indem eine Instanz einer Formatierungsklasse konfiguriert und der NumberFormatter Eigenschaft zugewiesen wird. Dezimal, Währung, Prozent und signifikante Stellen sind nur einige der verfügbaren Klassen mit Zahlenformaten. Beachten Sie, dass durch die Eigenschaften zur Formatierung von Zahlen auch die Rundungseigenschaften festgelegt werden.

Hier ist ein Beispiel für die Verwendung eines DecimalFormatters, um den Wert einer NumberBox so zu formatieren, dass er eine ganzzahlig Stelle mit zwei Dezimalstellen hat und auf die nächste 0,25 aufgerundet wird.

<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;
}

Im Hinblick auf Dezimalpunkte und Kommas wird die vom User verwendete Formatierung durch die für die NumberBox konfigurierte Formatierung ersetzt. Es wird kein Eingabevalidierungsfehler ausgelöst.

Bemerkungen

Eingabebereich

Number wird für den Eingabebereich verwendet. Dieser Eingabebereich ist für die Funktion mit den Zahlen 0–9 vorgesehen. Diese Einstellung kann überschrieben werden, alternative InputScope-Typen werden aber nicht explizit unterstützt.

Not a Number (NaN, kein Zahlenwert)

Wenn in einer NumberBox alle Eingaben gelöscht werden, wird Value auf NaN festgelegt, um anzuzeigen, dass kein Zahlenwert vorhanden ist.

Ausdrucksauswertung

NumberBox verwendet die Infix-Notation zum Auswerten von Ausdrücken. Dies sind die zulässigen Operatoren in der Reihenfolge ihres Vorrangs:

• ^
• */
• +-

Beachten Sie, dass zum Außer-Kraft-Setzen der Vorrangsregeln Klammern verwendet werden können.