Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.
Die Zahleneingabe ermöglicht es dem Benutzer, numerische Werte innerhalb eines vorgegebenen Bereichs einzugeben oder auszuwählen. Sie enthält Steuerelemente zum schrittweisen Erhöhen oder Verringern des Wertes. Benutzer können numerische Werte auch direkt in das Eingabefeld eingeben.
Verwenden Sie diese Komponente nicht, wenn für den Benutzer nicht der genaue Wert wichtig ist, sondern nur der ungefähre Bereich. Ziehen Sie in Betracht, stattdessen die Schieberegler-Komponente zu verwenden.
Beschriftung: Beschreibt den Zweck eines Eingabefeldes.
Hilfstext (optional): Bietet zusätzlichen Kontext, Hinweise oder hilfreiche Informationen zur Unterstützung des Benutzers. Wird oft verwendet, um bestimmte Anforderungen für das korrekte Ausfüllen eines Feldes zu erklären.
Numerischer Wert: Ändert sich, wenn der Benutzer einen Wert in das Feld eingibt oder die beiden Pfeile am Ende der Eingabe verwendet, um Werte zu addieren und zu subtrahieren.
Zahleneingabefeld: der Container, bestehend aus einer Füllung und einem Strich, in den der Benutzer Daten eingibt.
Positionieren Sie eine deutlich sichtbare Beschriftung außerhalb des Zahleneingabefeldes. Ein Eingabefeld ohne Beschriftung ist mehrdeutig und nicht barrierefrei.
Positionieren Sie eine dauerhafte Beschriftung außerhalb des Felds.
Gehen Sie nicht davon aus, dass das Feld ohne Beschriftung selbsterklärend ist.
Verwenden Sie Hilfetext, der erklärt, was wie eingeben werden muss. Hier einige Beispiele dafür, welche Informationen Sie im Hilfetext angeben können:
Kontext zur Unterstützung des Benutzers, z. B. wie die Informationen verwendet werden sollen
Hinweise dazu, welche Art von Informationen in das Eingabefeld gehören
Formatierungsbeispiele oder -anforderungen
Verwenden Sie Hilfetext nur für relevante Informationen. Vermeiden Sie Hilfetexte, die lediglich dieselben Informationen wiedergeben, die bereits in der Beschriftung stehen.
Verwenden Sie für Hilfetext die übliche Groß- und Kleinschreibung. Schreiben Sie den Hilfetext in 1 bis 2 kurzen, vollständigen Sätzen, die mit einem Punkt enden. Formatierungsbeispiele müssen nicht mit einem Punkt enden.
Verwenden Sie Hilfetext, um dem Benutzer zusätzliche Hilfe oder Kontext zu bieten.
Wiederholen Sie im Hilfetext nicht einfach die Informationen, die bereits in der Beschriftung stehen.
Fügen Sie keinen Platzhaltertext in das Eingabefeld für die Zahl ein. Platzhaltertext belastet das Kurzzeitgedächtnis der Benutzer, da er nach der Eingabe eines Werts verschwindet. Auch für Benutzer mit vermindertem Sehvermögen und kognitiven Beeinträchtigungen stellt er eine zusätzliche Belastung dar.
Positionieren Sie Hinweise und Anweisungen, einschließlich Formatierungsbeispiele und -anforderungen, stattdessen außerhalb des Felds.
Der Text der Fehlermeldung erklärt dem Benutzer, wie er den Fehler beheben kann. Im Falle des Zahleneingabefelds hängen die Fehler oft mit etwas zusammen, das für die Inline-Validierung korrigiert werden muss. Wenn der Benutzer beispielsweise ein Pflichtfeld nicht ausfüllt, in dem er nach seiner geschätzten jährlichen Fahrleistung gefragt wird, können Sie ihn mithilfe von Fehlertext zu einer Lösung führen: „Geben Sie Ihre geschätzte Jahresfahrleistung ein.“
Verwenden Sie für Fehlertext die übliche Groß- und Kleinschreibung. Schreiben Sie 1 bis 2 kurze, vollständige Sätze, die mit einem Punkt enden.
Verwenden Sie Fehlermeldungstexte, um den Benutzer anzuleiten und ihm eine Lösung aufzuzeigen.
Schreiben Sie keine zweideutigen Fehlermeldungen und lassen Sie die Benutzer nicht im Unklaren darüber, wie ein Problem zu lösen ist.
Markieren Sie erforderliche Felder mit einem Sternchen (*). Das Sternchen steht vor der Feldbeschriftung. Benutzer können so leicht herausfinden, welche Felder erforderlich sind, indem sie nur das Zeichen ganz links in der Beschriftung prüfen.
Zusätzlich zur Markierung erforderlicher Felder mit einem Sternchen wird empfohlen, klare Anweisungen am oberen Rand des Formulars einzufügen, z. B. „Alle mit einem Sternchen gekennzeichneten Felder sind Pflichtfelder“, um sicherzustellen, dass die Benutzer die Bedeutung des Sternchens verstehen.
Verwenden Sie ein Sternchen, um anzuzeigen, dass ein Feld ein Pflichtfeld ist.
Verwenden Sie kein Sternchen, um optionale Elemente zu kennzeichnen.
Das Zahleneingabefeld wird ohne Wert (Standard), mit Platzhaltertext oder mit vorausgefüllter Eingabe angezeigt.
Visualisierung
Zustand
Beschreibung
Kein Wert (Standard)
Zeigt dem Benutzer an, dass kein Wert eingegeben wurde und kein Platzhalter vorhanden ist.
Platzhalter
Zeigt dem Benutzer an, dass kein Wert eingegeben wurde. Der Platzhalter ist ausgegraut.
Vorausgefüllte Eingabe
Gibt für den Benutzer an, dass die Eingabe mit Daten vorausgefüllt ist.
Zahleneingabefelder haben auch interaktive Zustände für Aktiviert, Fokus, Deaktiviert, Fehler, Schreibgeschützt und Nur Anzeigen.
Zustand
Beschreibung
Aktiviert
Zeigt dem Benutzer an, dass das Element für die Interaktion aktiviert ist.
Fokussiert
Zeigt dem Benutzer an, auf welchem UI-Element im System der Fokus liegt.
Deaktiviert
Zeigt dem Benutzer an, dass der Eingabewert aufgrund lokaler Faktoren nicht geändert werden kann. Zum Beispiel muss ein Kontrollkästchen über dem Eingabefeld aktiviert sein, um auf dieses Eingabefeld zuzugreifen. Der Benutzer kann durch Interaktion mit der Seite eine Aktion zur Aktivierung durchführen.
Fehler
Zeigt an, dass der Benutzer einen Fehler bei der Validierung gemacht hat. Der Fehlertext gibt dem Benutzer eine korrigierende Rückmeldung.
Schreibgeschützt
Zeigt dem Benutzer an, dass der Eingabewert aufgrund externer Faktoren nicht geändert werden kann. Beispiel: fehlender Schreibzugriff. Der Benutzer kann Maßnahmen zur Aktivierung ergreifen, indem er sich z. B. an einen Administrator wendet.
Nur Anzeige
Der Zustand „Nur Anzeige“ wird in zwei Fällen verwendet:
Ein UI-Element wird im Anzeigemodus verwendet.
Ein UI-Element wird im Bearbeitungsmodus angezeigt, ist aber nie bearbeitbar.
Dieser Zustand wurde zuvor als „Schreibgeschützt“ bezeichnet.
Benutzer können eine Zahleneingabe aktivieren, indem sie auf den Bereich innerhalb des Rahmens klicken. Wenn der Fokus aktiviert ist, werden zwei Pfeile am Ende der Eingabe angezeigt. Mit diesen Steuerelementen können Benutzer den Wert inkrementell erhöhen oder verringern.
Auf das Eingabeelement kann über die Tastatur zugegriffen werden. Benutzer können mit der TAB-Taste zu der Komponente navigieren und sie wieder verlassen.
Der barrierefreie Name der Zahleneingabe-Komponente wird über ein aria-label-Attribut abgeleitet. Wenn Sie den Textwert des Beschriftungselements ändern, ändert sich auch der Wert des barrierefreien Namens. Das Standardattribut aria-required='true' wechselt zu „false“, wenn das erforderliche Kontrollkästchen in Storybook aktiviert ist.
Das Kontrastverhältnis von Textelementen zu ihrem Hintergrund liegt über 4,5:1.
Nicht-textuelle Inhalte, die eine Bedeutung vermitteln sollen (z. B. Symbole und Fokusanzeigen), weisen ein Kontrastverhältnis von mindestens 3:1 zu den angrenzenden Farben auf.
Das jeweilige Element kann sowohl über eine Tastatur als auch über eine Maus bedient werden.
Der Zugriff auf die Inhalte erfolgt über Screenreader wie JAWS oder VoiceOver.
Die Konformität mit den Richtlinien für Barrierefreiheit hängt letztendlich davon ab, wie diese Komponente implementiert und angepasst wird. Vom Autor des Inhalts vorgenommene Änderungen können sich auf die Barrierefreiheit auswirken. Details zu unserem Modell der geteilten Verantwortung finden Sie in unserer Erklärung zur Barrierefreiheit von Jutro.
Wenn Sie diese Komponente in Ihrer Anwendung verwenden, stellen Sie sicher, dass Beschriftungen und Anweisungen aussagekräftig und prägnant sind. Geben Sie bei Bedarf ergänzende Anweisungen.
Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.
Vergewissern Sie sich, dass Sie die API-Oberfläche der Design System-Komponenten und die damit verbundenen Auswirkungen und Kompromisse verstehen. Erfahren Sie mehr in unserer Einführung zur Komponenten-API.
The number of decimal places to display in the value. If it is set, the user is prevented from entering too many digits after the decimal point. If the value or initialValue props have too many digits after the decimal point, the displayed figure is rounded to the closest valid value.
If set to true, displays the component value in plain text. Consider using readonly instead, if possible, because plain text is worse for accessibility than readonly inputs.
Initial value of the input. If the value prop is specified along with this prop, this prop's value is discarded. If the decimalPlaces prop is specified along with this prop, the displayed value is rounded to the closest valid value.
Maximum value of the input. If this prop is passed, the component does not allow entering values higher than the specified value when using the Up Arrow key.
Minimum value of the input. If this prop is passed, the component does not allow entering values lower than the specified value when using the Down Arrow key.
Step increment for value changes. If this prop is passed, the component will increase or decrease its value by the specified step when the Up Arrow or Down Arrow keys are pressed.
Value of the input. Takes precedence over initialValue. If this prop is passed, the component works in controlled mode and its value will change only if this prop changes. If the decimalPlaces prop is specified along with this prop, the displayed value is rounded to the closest valid value.
Übergeben von HTML-Eigenschaften an die Komponente
Sie können Attribute der HTML-Eingabe verwenden, mit Ausnahme derjenigen, die von Jutro überschrieben werden. Diese Attribute werden dem HTML-Element input zugewiesen.
Bitte beachten Sie, dass die meisten eingabespezifischen Attribute (step, min und max) als Teil der Komponenten-API enthalten sind und möglicherweise mit einer Jutro-spezifischen Logik verbunden sind.
Die Jutro-Eingaben haben imperative Handler als Mechanismus implementiert, um Zugang zu einigen gängigen nativen Funktionen zu bieten, die für Sie nützlich sein könnten. Die folgenden Funktionen sind verfügbar:
Fokus setzen ermöglicht es, den Fokus des Benutzers auf eine bestimmte Komponente zu setzen.
Fokus aufheben ermöglicht es, den Fokus von der Komponente zu entfernen.
Zur Komponente scrollen ermöglicht es, den Benutzer zu einem bestimmten Bereich der Seite zu führen.
Diese Funktionen werden über die ref-Eigenschaft bereitgestellt, die sie wie folgt verfügbar macht:
Obwohl einige Jutro-Komponenten ergänzende Funktionen oder eine Hilfsfunktion zur Erleichterung des Validierungsprozesses bereitstellen, liegt es in Ihrer Verantwortung als Entwickler, die Validierung von Benutzereingaben (mit oder ohne Verwendung der ergänzenden Hilfsfunktionen) durchzuführen und zu entscheiden, welche Fehlermeldungen angezeigt werden sollen.
Das Verhalten von Jutro-Komponenten hängt von der Implementierung durch den Entwickler ab.
Wann werden Fehlermeldungen angezeigt?
Fehlermeldungen werden nur angezeigt, wenn Sie sie über die Eigenschaft stateMessages an die Komponente übergeben. Diese Eigenschaft empfängt ein Objekt mit dem folgenden Inhalt:
Die Komponente zeigt alle bereitgestellten Fehlermeldungen in der gleichen Reihenfolge wie im Array an.
Wann erfolgt die Validierung?
Dies ist Ihre Entscheidung als Entwickler. Da die Komponenten nicht festlegen, wann die Validierung durchgeführt wird oder wann der Fehler angezeigt werden muss, müssen Sie die Logik für die Behandlung entsprechend den Projektanforderungen implementieren, z. B. w ährend der Benutzer den Inhalt bearbeitet, wenn die Komponente den Fokus verliert und bei der Formularübermittlung.
Sie können React-Zustände verwenden, um den Wert eines NumberInput-Elements zu steuern, aber es gibt dabei einige Einschränkungen.
Das Ereignis onChange wird nur ausgelöst, wenn der Fokus auf der Eingabe liegt. Wenn der Wert als kontrollierte Komponente aktualisiert wird, wird der onChange-Rückruf nicht ausgeführt.
Wenn NumberInput über eine decimalPlaces-Eigenschaft verfügt und einen Wert aus einer React-Zustandsaktualisierung erhält, wird der angezeigte Wert auf den nächsten gültigen Wert gerundet.
Im Code unten können Sie z. B. die erste Eingabe verwenden, um den Wert der zweiten Eingabe zu ändern. Dabei lassen sich die folgenden beiden Verhalten beobachten:
Wenn in der ersten Eingabe ein Wert größer als 100 oder kleiner als 0 eingegeben wird, werden die Validierungsmeldungen in der zweiten Eingabe nicht angezeigt, da der zugehörige Rückruf nicht ausgeführt wird.
Wenn mehr als zwei Dezimalstellen eingegeben werden, wird der in der zweiten Eingabe angezeigte Wert auf den nächsten gültigen Wert gerundet.
exportfunctionNumberInputDecimalPlacesControlledExample(){ const[firstInputValue, setFirstInputValue]=useState(); const[secondInputValue, setSecondInputValue]=useState(); const[validationMessages, setValidationMessages]=useState({}); const max =100; const min =0; const handleFirstInputChange =useCallback((event, newValue)=>{ console.log(newValue) setFirstInputValue(newValue ||0); },[]); const handleSecondInputChange =useCallback((e, newValue)=>{ setValidationMessages({}); if(newValue &&(newValue > max || newValue < min)){ setValidationMessages({ error:['Value must be between 0 and 100'], }); } },[]); return( <NumberInput label="Number input" secondaryLabel="Change this value to see the second input update" onChange={handleFirstInputChange} /> <NumberInput label="Second number input" secondaryLabel="Value controlled by the first input" value={firstInputValue} decimalPlaces={2} onChange={handleSecondInputChange} stateMessages={validationMessages} min={min} max={max} readOnly /> ); }
Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.
Zum Anzeigen einer einfachen Zahleneingabe-Komponente ist lediglich die Eigenschaft label erforderlich. Andere Eigenschaften können verwendet werden, um ihr Verhalten zu ergänzen: placeholder, secondaryLabel, onChange oder die zahlenbezogenen Eigenschaften.
<NumberInput label="Number input component" placeholder="Write what you want here" secondaryLabel="Free text input" />
Mit der Zahleneingabe-Komponente können die Maximal- und Minimalwerte festgelegt werden. Dies hat jedoch nichts mit einer Validierungsfunktion zu tun, sondern mit dem Verhalten der Komponente. Wenn Sie eine dieser beiden Eigenschaften einstellen, ist es nicht möglich, mit den Komponentenpfeilen einen Wert einzustellen, der unter der min-Eigenschaft liegt oder einen Wert, der über der max-Eigenschaft liegt.
Wenn eine spezielle Validierung erforderlich ist, muss diese vom Entwickler vorgenommen werden. Einzelheiten dazu finden Sie im Beispiel für die Validierung der Zahleneingabe bei Änderungen.
<NumberInput label="Number input component with min and max" placeholder="Enter a value" secondaryLabel="Test the limits with using the arrows" min={20} max={40} />
Die Zahleneingabe-Komponente stellt keine spezielle Validierungslogik zur Verfügung, bietet aber die Möglichkeit, die Validierung durch den Entwickler einzubeziehen und die Eigenschaft stateMessages zur Anzeige der erforderlichen Fehlermeldung zu verwenden.
Dies ist ein Beispiel für die Handhabung der Validierung, wenn ein onChange-Ereignis ausgelöst wird.
exportfunctionNumberInputValidation(){ const[validationMessages, setValidationMessages]=useState({}); const max =100; const min =0; const onChange =useCallback((e, newValue)=>{ setValidationMessages({}); if(newValue &&(newValue > max || newValue < min)){ setValidationMessages({ error:['Value must be between 0 and 100'], }); } },[]); return( <NumberInput label="Enter value" secondaryLabel="Min = 0. Max = 100" stateMessages={validationMessages} min={min} max={max} onChange={onChange} /> ); }
Die Eigenschaft decimalPlaces gibt die Anzahl der anzuzeigenden Dezimalstellen an. Sie hindert Benutzer daran, zu viele Stellen nach dem Komma einzugeben. Wenn jedoch die Eigenschaften initialValue oder value festgelegt sind, wird die Zahl auf den nächsten gültigen Wert gerundet.
Wenn decimalPlaces beispielsweise auf 2 festgelegt ist, kann der Benutzer keine Dezimalstellen eingeben. Die Eigenschaften initialValue oder value können jedoch drei oder mehr Dezimalstellen haben.
<NumberInput label="Number input component limited decimals" placeholder="Enter a value" secondaryLabel="Try to add an additional decimal" decimalPlaces={2} /> <NumberInput label="Number input with initial value" secondaryLabel="Rounded up from 5.666" initialValue={5.666} decimalPlaces={2} readOnly /> <NumberInput label="Number input with value" secondaryLabel="Rounded up from 5.666" value={5.666} decimalPlaces={2} readOnly />
Das Verhalten der Eigenschaft decimalPlaces wurde geändert. Der Benutzer kann nun über das Limit für decimalPlaces hinaus keine weiteren Ziffern mehr eingeben. Beispiel: Wenn decimalPlaces den Wert 2 hat, kann der Benutzer keine dritte Stelle nach dem Dezimalkomma eingeben.
Die Eigenschaften initialValue und value können zusätzliche Stellen nach dem Dezimaltrennzeichen haben, aber der angezeigte Wert wird auf den nächsten gültigen Wert gerundet.
Es wurde eine neue @jutro/components/NumberInput-Komponente eingeführt, welche InputNumberField ersetzt.
Die frühere zahlenbezogene Komponente InputNumberField wurde abgekündigt und in das @jutro/legacy-Paket verschoben. Um die entsprechende Dokumentation anzuzeigen, wechseln Sie zu einer älteren Version.
