Stepper
Beispiele
Im Abschnitt Verwendung finden Sie Informationen über das richtige Design eines Steppers und die verschiedenen Konfigurationsoptionen, die wir bereitstellen.
Zahl eingeben
Sie können dem Benutzer erlauben, mithilfe der Stepper-Komponente eine Zahl einzugeben. Verwenden Sie dann den Handler, um die ausgewählte Zahl abzurufen.
import { Stepper } from '@jutro/components/new';
// ...
<Stepper
label="Enter Number"
name="Number picker"
/>;
Zahl mit Einschränkungen eingeben
Sie können den Bereich der auszuwählenden Zahlen mit den Eigenschaften min und max einschränken. Dabei handelt es sich um inklusive Grenzen.
import { Stepper } from '@jutro/components/new';
// ...
<Stepper
label="Enter Number"
secondaryLabel="From 1 to 10 inclusive"
min={1}
max={10}
/>;
Benutzerdefinierte Validierungsmeldung
Stepper stellt keine spezielle Validierungslogik zur Verfügung, bietet aber die Möglichkeit, die Validierung durch den Entwickler einzubeziehen und die stateMessages-Eigenschaft zur Anzeige der erforderlichen Fehlermeldung zu verwenden.
Dies ist ein Beispiel für die Handhabung der Validierung, wenn ein onChange-Ereignis ausgelöst wird. Geben Sie einen Wert unter 0 oder über 10 ein, ohne die Schaltflächen zum Testen zu verwenden.
export function StepperValidation() {
const [validationMessages, setValidationMessages] = useState({});
const max = 10;
const min = 0;
const onChange = useCallback((e, newValue) => {
setValidationMessages({});
if (newValue && (newValue > max || newValue < min)) {
setValidationMessages({
error: ['Value must be between 0 and 10'],
});
}
}, []);
return (
<JutroWrapper>
<div style={{ padding: '2rem 1rem' }}>
<Stepper
label="Enter Number"
secondaryLabel="From 1 to 10 inclusive"
onChange={handleChange}
stateMessages={validationMessages}
min={min}
max={max}
/>
</div>
</JutroWrapper>
);
}
Verwendung
Überblick
Die Komponente stepper ermöglicht es den Benutzern, einen numerischen Wert inkrementell zu erhöhen oder zu verringern. Benutzer können numerische Werte auch direkt in das Eingabefeld eingeben.
Zu verwenden
- Für numerische Parameter mit einem eindeutigen Standardwert, den die meisten Benutzer wahrscheinlich auswählen werden.
- Zum Anpassen numerischer Felder um einen kleinen diskreten Betrag von nicht mehr als 10 Erhöhungs- oder Verringerungsschritte. Sie können den Stepper beispielsweise verwenden, um die Anzahl der Insassen in einem Fahrzeug oder die Anzahl der zu erstellenden Kopien zu ändern.
Nicht zu verwenden
- Wenn häufige große Abweichungen vom Standardwert zu erwarten sind.
- Zur Auswahl eines einzelnen Wertes oder eines Wertebereichs aus einem festen Satz von Optionen. Verwenden Sie stattdessen den Schieberegler.
- Für kontinuierliche Variablen wie Alter, Größe, Preis oder Entfernung. Verwenden Sie die Zahleneingabe, um den genauen Wert innerhalb eines großen Bereichs anzugeben.
Quelle: Nielsen Norman Group
Formatierung
Aufbau

Der Stepper besteht aus den folgenden Elementen:
- Beschriftung: Gibt an, welchen Wert der Stepper ändert, z. B. die Anzahl der Passagiere.
- Schaltfläche „Verringern“: Diese Schaltfläche dient zum Verringern des Wertes. Der Wert wird um 1 verringert, wenn ein Benutzer auf die Schaltfläche klickt.
- Wert: Der aktuelle Wert, der ausgewählt oder vorgegeben wurde. Die Benutzer haben die Möglichkeit, einen numerischen Wert manuell einzugeben, indem sie in das Texteingabefeld klicken.
- Schaltfläche „Erhöhen“: Diese Schaltfläche dient zum Erhöhen des Wertes. Der Wert wird um 1 erhöht, wenn ein Benutzer auf die Schaltfläche klickt.
Inhalt
Allgemeine Richtlinien fürs Schreiben
- Verwenden Sie die Großschreibung des ersten Worts und von Substantiven für alle Aspekte der Gestaltung von Guidewire-Produktschnittstellen. Schreiben Sie nicht alles groß.
- Verwenden Sie in den meisten Situationen Verben im Präsens und im Aktiv.
- Verwenden Sie gebräuchliche Abkürzungen, um Ihrem Text einen natürlichen und informellen Ton zu verleihen.
- Verwenden Sie eine einfache Sprache. Vermeiden Sie unnötigen Jargon und komplexe Sprache.
- Halten Sie Wörter und Sätze kurz.
Eine Beschriftung einfügen
Positionieren Sie eine deutlich sichtbare Beschriftung außerhalb des Stepper-Eingabefeldes. Der Beschriftungstext erklärt den Zweck des Steppers und bietet dem Benutzer einen Kontext. Ein Eingabefeld ohne Beschriftung ist mehrdeutig und nicht barrierefrei.
label-Eigenschaft ist für die Stepper-Komponente obligatorisch. Wenn Sie nicht möchten, dass die Beschriftung sichtbar ist, können Sie hideLabel = true unter der label-Eigenschaft einfügen.

Fügen Sie Hilfetext hinzu, wenn er aussagekräftig ist
Verwenden Sie Hilfetext, um relevante Informationen zu vermitteln, wie z. B. den maximalen oder minimalen Eingabewert.


Verwenden von Fehlertext zur Anleitung der Benutzer
Der Text der Fehlermeldung erklärt dem Benutzer, wie er den Fehler beheben kann. Beim Stepper hängen Fehler häufig mit ungültigen Daten oder einem nicht ausgefüllten Pflichtfeld zusammen.
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.


Pflichtfelder markieren
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 scannen.
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.


Schreiben Sie das erste Wort und Substantive groß.
Für Feldbeschriftungen wird die übliche Groß- und Kleinschreibung verwendet.
Weitere Informationen zum Implementieren der Groß- und Kleinschreibung finden Sie im UI-Textstyleguide.


Verhalten
Zustände
Das Stepper-Feld weist die Zustände aktiviert, deaktiviert, fokussiert, Fehler, schreibgeschützt und nur anzeigen auf.
Stepper-Steuerelemente verwenden Symbolschaltflächen. Weitere Informationen über die Zustände von Symbolschaltflächen finden Sie in der Dokumentation zu den Schaltflächenzuständen.
| Zustand | Beschreibung | |
|---|---|---|
![]() | Aktiviert (Standard) | Teilt dem Benutzer mit, dass das Element für die Interaktion aktiviert ist. |
| 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. | |
![]() | Fokussiert | Zeigt an, dass der Benutzer das Element hervorgehoben hat, in der Regel über eine Eingabemethode wie eine Tastatur oder Sprachbefehl. |
![]() | Fehler | Zeigt an, dass der Benutzer einen Fehler bei der Validierung gemacht hat. Eine Validierungsbeschriftung gibt Benutzern eine korrigierende Rückmeldung. |
| Schreibgeschützt | Zeigt dem Benutzer an, dass der Eingabewert aufgrund externer Faktoren nicht geändert werden kann. Zum 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:
read-only genannt. |
Interaktionen
Maus
Die Benutzer können einen numerischen Wert manuell eingeben, indem sie in das Texteingabefeld klicken. Sie können den Wert auch inkrementell erhöhen oder verringern, indem sie auf das Symbol „Addieren“ oder „Subtrahieren“ klicken.

Tastatur
Jedes Element in der Jutro-Stepper-Komponente ist Tabulator-indiziert und kann somit über die Tab-Taste aufgerufen werden. Die Werte können mit der Leertaste und der Eingabetaste erhöht oder verringert werden. Der Wert innerhalb des Eingabefeldes kann auch explizit mit den Cursor-Pfeiltasten oder durch manuelle Eingabe des Wertes festgelegt werden.
Screenreader
Die Plus- und Minuswert-Schaltflächen enthalten jeweils ein aria-label-Attribut „Wert erhöhen“ bzw. „Wert verringern“. Diese können in Storybook in den messageProps-Feldern geändert werden. Das Eingabefeld nutzt aria-live="polite", um blinden Menschen seinen Wert zu vermitteln, und es wird über aria-labelledby mit dem Beschriftungstext der Komponente verknüpft.
Standardwerte
Legen Sie den am häufigsten ausgewählten Wert als Stepper-Standard fest. Beispielsweise ist 1 in der Regel die Standardanzahl von Erwachsenen für die Buchung eines Hotelzimmers, während 0 die Standardanzahl von Kindern bei einer Hotelreservierung sein kann.
Quelle: Nielsen Norman Group


Barrierefreiheit
Das Kontrastverhältnis von Textelementen zu ihrem Hintergrund liegt über 4,5:1 gemäß den Anforderungen der WCAG 2.1 AA. Nicht-textuelle Inhalte, die eine Bedeutung vermitteln müssen (z. B. Symbole und Sichtbarkeit des Tastaturfokus), weisen ein Kontrastverhältnis von mindestens 3:1 zu den angrenzenden Farben auf. Alle Inhalte sind bis einschließlich 400 % sichtbar und funktionsfähig, ohne dass ein Scrollen in zwei Dimensionen erforderlich ist.
Diese Komponente wurde validiert, um die Zugänglichkeitsrichtlinien WCAG 2.1 AA zu erfüllen. Vom Autor des Inhalts vorgenommene Änderungen können sich jedoch auf die Konformität mit der Barrierefreiheit auswirken.
Code
<Stepper label="Enter Number" />
Importanweisung
import { Stepper } from '@jutro/components/new';
Komponentenvertrag
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.
Eigenschaften
labelerforderlich- Beschreibung
Label associated with input field, also passed as a default value to 'aria-label'.
className- Typ
stringBeschreibungCSS class name for this component.
disabled- Typ
booleanBeschreibungIf set to
true, component is rendered in disabled state. displayOnly- Typ
booleanBeschreibungIf set to
true, displays the component value in plain text. Consider usingreadonlyinstead, if possible, because plain text is worse for accessibility than readonly inputs. hideLabel- Typ
booleanBeschreibungIf set to
true, the label is not visible. initialValue- Typ
numberBeschreibungInitial value of input. If value prop is specified along with this prop, this prop's value is discarded.
labelPosition- Typ
'top' | 'left'BeschreibungAllows to select label position.
max- Typ
numberBeschreibungMaximum value of input. If this prop is passed, component does not allow to enter values, higher than specified one by using arrow up key/button.
min- Typ
numberBeschreibungMinimum value of input. If this prop is passed, component does not allow to enter values, lower than specified one by using arrow down key/button.
onChange- Typ
function (React.ChangeEvent<HTMLInputElement>, number)BeschreibungCallback invoked when component value is changed.
readOnly- Typ
booleanBeschreibungIf set to
true, component is rendered in a read-only state. For values in plain text, consider usingdisplayOnly. required- Typ
booleanBeschreibungIf set to
true, component is rendered as required and label has asterisk. secondaryLabel- Beschreibung
Secondary label text to display.
stateMessages- Typ
{ error: string[] }BeschreibungAn object with a list of error messages for the current state.
step- Typ
numberBeschreibungStep value for value change. If this prop is passed, component will increase/decrease it's value on step when user press arrow key or button.
tooltip- Typ
{ text: intlMessageShape, trigger: string } | intlMessageShapeBeschreibungText to be displayed in the tooltip or tooltip object that includes: text - to show tooltip content, trigger - to set tooltip trigger.
value- Typ
numberBeschreibungValue of input. Takes precedence over initialValue. If this prop is passed, component works in controlled mode and its value will change only if this prop changes.
Hooks
Für Stepper sind keine Hooks verfügbar.
Übersetzungsschlüssel
Es gibt keine Übersetzungen für Stepper.
Informationen über die Verwaltung von Übersetzungen finden Sie in unserem Abschnitt über Internationalisierung.
Escape Hatches
Weitere Informationen finden Sie in unserer Dokumentation über Escape-Hatches.
- Design-Token
classNameEigenschaft- Übergeben nativer HTML-Attribute
- Ref mit imperativen Handlern
- Native Ereigniseigenschaft
Benutzerdefinierte Verhaltensweisen
Überschreiben der Einstellungen min und max
Obwohl die Eigenschaften min und max zur Einschränkung der Werte verwendet werden können, die mit den Schaltflächen (+) und (-) in der Komponente eingestellt werden können, gibt es 3 verschiedene Möglichkeiten, wie die Stepper-Komponente einen Wert außerhalb dieser Grenzen einstellen kann:
- Eigenschaften
initialValueodervalue: Diese Eigenschaften können jede beliebige Zahl annehmen. Wenn die angegebene Zahl außerhalb der festgelegten Grenzen liegt, wird sie trotzdem verwendet. - Manuelle Benutzereingabe: Der Benutzer kann jede beliebige Zahl eingeben, auch wenn sie außerhalb der festgelegten Grenzen liegt
Falls ein initialValue-Wert oder ein manuell eingegebener Wert außerhalb der Grenzwerte liegt, führt die Stepper-Komponente folgende Aktion durch:
- Deaktiviert die Schaltfläche (+), wenn der Wert über dem Wert der
max-Eigenschaft liegt - Deaktiviert die Schaltfläche (-), wenn der Wert unter dem Wert der
min-Eigenschaft liegt - Setzt den Wert auf
minoder die festgelegten Höchstwerte, wenn die entsprechende Schaltfläche angeklickt wird
Vorrang von disabled, displayOnly und readOnly
Wenn zwei oder mehr der Eigenschaften disabled, displayOnly, und readOnly gleichzeitig auf true gesetzt werden, gilt die folgende Vorrangregel:
displayOnly>readOnly>disabled
Validierung von Benutzereingaben
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.
Jutro-Komponenten verhalten sich in Abhängigkeit von der Implementierung des Entwicklers.
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:
{
error: ['error message 1', 'error message 2', 'error message N'];
}
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.
Information zu älteren Komponenten
Verwenden Sie den alten Stepper?
- Um die Dokumente für die alte Komponente anzuzeigen, wechseln Sie zu einer Version der Dokumente, die älter als 10.3.0 ist.
- Die ältere Komponente ist auch in Storybook verfügbar:


