Verwendung
Überblick
Die Datumseingabe kombiniert drei unterschiedliche Eingabefelder – Tag, Monat und Jahr – in einer einzigen Datumskomponente. Benutzer können mit dieser Komponente Daten eingeben, die nichts mit dem aktuellen Datum zu tun haben, z. B. Geburtsdaten.
Zu verwenden
- Wenn das Datum dem Benutzer bekannt ist, z. B. ein Geburtsdatum oder das Ablaufdatum einer Kreditkarte.
- Wenn eine genaue Datumseingabe erforderlich ist und die Kalenderauswahl umständlich sein kann. Wenn der Benutzer beispielsweise ein Datum eingeben muss, das in der fernen Vergangenheit oder Zukunft liegt, kann es schneller und effizienter sein, das Datum manuell einzugeben.
Nicht zu verwenden
- Für Termine, die nahe am aktuellen Datum liegen (z. B. innerhalb der nächsten Wochen oder Monate). Verwenden Sie stattdessen die Datumsauswahl.
- Wenn es unwahrscheinlich ist, dass der Benutzer sich das Datum gemerkt hat (z. B. wenn ein Termin mehrere Monate im Voraus geplant wird). Verwenden Sie stattdessen die Datumsauswahl.
Siehe auch
Typen
Die Datumseingabekomponente bietet drei Varianten, um unterschiedlichen datumsbezogenen Eingabeanforderungen gerecht zu werden.
| Visualisierung | Typ | Zweck |
|---|
 | Datum | Die Benutzer geben ein vollständiges Datum (Tag, Monat und Jahr) ein. |
 | Monat | Die Benutzer geben einen bestimmten Monat und ein bestimmtes Jahr ohne Tag ein. |
 | Jahr | Die Benutzer geben nur ein Jahr ein. |
Aufbau
Die Datumseingabe besteht aus den folgenden Elementen:
- Beschriftung: Eine klare und prägnante Beschreibung, die den Zweck und den Kontext des Datumseingabefelds enthält. Anhand der Beschriftung können Benutzer das Datum erkennen, das sie eingeben sollen.
- Tagesfeld: Ein Eingabefeld, in das der Benutzer den Tag manuell eingeben kann.
- Monatsfeld: Ein Eingabefeld, in das der Benutzer den Monat manuell eingeben kann.
- Jahresfeld: Ein Eingabefeld, in das der Benutzer das Jahr manuell eingeben kann.
Die Datumseingabekomponente passt sich an die Gebietsschemaeinstellungen des Benutzers an und zeigt die Felder für Tag, Monat und Jahr in der Reihenfolge an, die ihm am vertrautesten ist. Beispiel:
- Vereinigte Staaten: MM/TT/JJJJ
- Vereinigtes Königreich: TT/MM/JJJJ
- Japan: JJJJ/MM/TT
Die Komponente passt die Feldreihenfolge und die Beschriftungen automatisch an das entsprechende Datumsformat für die Region des Benutzers an.
Die Reihenfolge der Eingaben variiert je nach Gebietsschema. Beispiele für Europa (links) und die USA (rechts).
Platzierung von Beschriftungen
Die Beschriftung für die Datumseingabe kann oben (Standard und empfohlen) oder links von der Eingabe selbst erscheinen.
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 Datumseingabefeldes. 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 von Hilfetext
Wenn Sie eine Datumseingabe verwenden, fügen Sie das Datumsformat als Hilfetext hinzu. Es ist problematisch, sich ausschließlich auf Platzhaltertext zu verlassen, um das Datumsformat zu vermitteln, da der Platzhaltertext verschwindet, sobald der Benutzer zu tippen beginnt. Dies kann dazu führen, dass die Benutzer unsicher sind, welches Format erwartet wird.
Quelle: Nielsen Norman Group
Fügen Sie das Datumsformat als Hilfetext hinzu.
Verlassen Sie sich nicht nur auf Platzhaltertext, um das Datumsformat zu vermitteln.
Verhalten
Zustände
Das Datumseingabefeld 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. |
Datumseingabefelder haben auch interaktive Zustände für Aktiviert, Fokussiert, Deaktiviert, Fehler, Schreibgeschützt und Nur Anzeigen.
Interaktionen
Maus
Benutzer können mit diesem Element interagieren, indem sie auf den Bereich innerhalb des Rahmens klicken.
Tastatur
Auf das Eingabeelement kann über die Tastatur zugegriffen werden. Benutzer können mit der TAB-Taste zu der Komponente navigieren und sie wieder verlassen.
Screenreader
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.
Barrierefreiheit
Diese Komponente wurde validiert, um die Richtlinien für Barrierefreiheit WCAG 2.2 AA in der Standardbasiskonfiguration zu erfüllen. Dazu wird u. a. Folgendes sichergestellt:
- 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.
Achten Sie bei der Verwendung dieser Komponente darauf, dass die Beschriftung eindeutig angibt, welches Datum der Benutzer eingeben muss.
Code
Importanweisung
import { DateInput } from '@jutro/components';
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
BeschreibungLabel associated with the input field, also passed as a default value to 'aria-label'.
autoFocus
BeschreibungDetermines whether to switch the focus between fields automatically. If true, the focus is set on the next field after typing the exact amount of characters as set in the max length attribute.
className
BeschreibungCSS class name for this component.
disabled
BeschreibungIf true, the component is rendered in a disabled state.
Typ'vshort' | 'short' | 'long' | 'abbreviated' | 'full'
BeschreibungSets the date format. This prop can only be used along with readOnly and displayOnly props.
displayOnly
BeschreibungIf 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.
hideLabel
BeschreibungIf true, the label is not visible.
initialValue
Typ{ day: number, month: number, year: number }
BeschreibungInitial value of the input. The value must be an object with day, month, and year properties, where month is indexed from 1. If the value prop is specified along with this prop, this prop's value is discarded.
labelPosition
maxDate
Typ{ day: number, month: number, year: number }
BeschreibungMaximum allowed day value.
maxMonth
Typ{ month: number, year: number }
BeschreibungMaximum allowed month value.
maxYear
BeschreibungMaximum allowed year value.
minDate
Typ{ day: number, month: number, year: number }
BeschreibungMinimum allowed day value.
minMonth
Typ{ month: number, year: number }
BeschreibungMinimum allowed month value.
minYear
BeschreibungMinimum allowed year value.
onBlur
Typfunction (FocusEvent<HTMLInputElement>)
BeschreibungA callback called after the component is focused.
onChange
Typfunction (React.ChangeEvent<HTMLInputElement>, { day: number, month: number, year: number })
BeschreibungCallback invoked when component value is changed.
onFocus
Typfunction (FocusEvent<HTMLInputElement>)
BeschreibungA callback called after the component is focused.
readOnly
BeschreibungIf set to true, component is rendered in a read-only state. For values in plain text, consider using displayOnly.
required
BeschreibungIf true, the component is rendered as required and the label will display an asterisk.
secondaryLabel
BeschreibungSecondary label text to display.
stateMessages
BeschreibungAn object with a list of error messages for the current state.
Typ{ text: intlMessageShape, trigger: string } | intlMessageShapetext
BeschreibungText to show tooltip content.
trigger
BeschreibungThe trigger to show the tooltip.
BeschreibungText to be displayed in the tooltip or tooltip object that includes: text - to show tooltip content, trigger - to set tooltip trigger.
value
Typ{ day: number, month: number, year: number }
BeschreibungValue of the input. Takes precedence over initialValue. The value must be in object format with day, month, and year property where month is indexed from 1. If this prop is passed, the component works in controlled mode and its value changes only if this prop changes.
variant
Typ'date' | 'month' | 'year'
BeschreibungVariant of the date input.
Hooks
Für DateInput sind keine Hooks verfügbar.
Übersetzungsschlüssel
Die Datumseingabekomponente erbt die folgenden Übersetzungen:
| Schlüssel | Verwendet für |
|---|
| jutro-components.fields.DatePicker.insertDay | aria-label für das Tagesauswahlfeld. |
| jutro-components.fields.DatePicker.insertMonth | aria-label für das Monatsauswahlfeld. |
| jutro-components.fields.DatePicker.insertYear | aria-label für das Jahresauswahlfeld. |
| jutro-components.fields.DatePicker.placeholderDay | „Tag“-Teil des Platzhalters. Muss aus zwei sich wiederholenden Zeichen bestehen. |
| jutro-components.fields.DatePicker.placeholderMonth | „Monat“-Teil des Platzhalters. Muss aus zwei sich wiederholenden Zeichen bestehen. |
| jutro-components.fields.DatePicker.placeholderYear | „Jahr“-Teil des Platzhalters. Muss aus vier sich wiederholenden Zeichen bestehen. |
Je nach Gebietsschema werden die Eingabefelder entsprechend dem regionalen Datumsformat neu angeordnet. Dies wirkt sich auch auf das Format für die Eigenschaften displayOnly und readOnly aus.
Die Komponente DateInput stellt über die Eigenschaft onChange einen Validierungsmechanismus bereit. Diese Eigenschaft unterstützt die Parameter event, value und errorCode. Folgende errorCode-Werte sind möglich:
INVALID_DATE: Das Datumsformat ist falsch, z. B. wenn ein Monatswert größer als 12 eingegeben wird.MIN_EXCEEDED: Der Eingabewert ist kleiner als der durch die Eigenschaft minDate, minMonth oder minYear festgelegte Mindestwert.MAX_EXCEEDED: Der Eingabewert ist größer als der durch die Eigenschaft maxDate, maxMonth oder maxYear festgelegte Höchstwert.
Sehen Sie sich das Min/Max-Beispiel an, um zu sehen, wie die Prüfung funktioniert.
Mit der Eigenschaft displayFormat kann das Format der Datumsangaben geändert werden, wenn die Eigenschaft readOnly oder displayOnly verwendet wird. Es gibt fünf verschiedene Alternativen:
vshort: 20.6.2024short: 20. Jun 2024long: 20. Juni 2024abbreviated: Do, 20. Juni 2024full: Donnerstag, 20. Juni 2024
Escape Hatches
Weitere Informationen finden Sie in unserer Dokumentation über Escape Hatches.
Verwenden Sie die alten Datumseingabefelder?
- Um die entsprechende Dokumentation für die alten Komponenten anzuzeigen, wechseln Sie zu einer Version der Dokumentation, die älter als 10.7.0 ist.
- Die folgenden älteren Komponenten sind auch in Storybook verfügbar:
Beispiele
Im Abschnitt Verwendung finden Sie Informationen darüber, wie und wann Sie die Komponente DateInput verwenden können.
Sie können die variant-Eigenschaft verwenden, um eine Eingabekomponente mit verschiedenen Feldern zu erstellen:
import React from 'react';
import { DateInput } from '@jutro/components';
export const BasicDateInput = () => {
return (
<div style={{ display: 'flex', gap: '2rem', flexWrap: 'wrap'}}>
<DateInput label="This is a simple date input" />
<DateInput label="This is a month and year input" variant='month' />
<DateInput label="This is a year input" variant='year' />
</div>
);
};
Beispiel für einen Fehler
Mit der Eigenschaft stateMessages können Sie einen Fehler für die DateInput-Komponente anzeigen.
import React from 'react';
import { DateInput } from '@jutro/components';
export const ErrorDateInput = () => {
return (
<div>
<DateInput
label="This is a date input"
stateMessages= {{
error: ['This is an error message'],
}}
/>
</div>
);
};
Beispiel für Min/Max
Mit den Eigenschaften minDate und maxDate können Sie ein Mindest- und ein Höchstdatum für die DateInput-Komponente festlegen. Alternativ können Sie mit minMonth, minYear, maxMonth und maxYear unabhängige Werte für Monate und Jahre festlegen. Im folgenden Beispiel wird geprüft, wann der Fokus verloren geht, wenn der Jahreswert zwischen 2000 und 2024 liegt, und falls er nicht zwischen diesen Werten liegt, wird ein Fehler angezeigt.
import React, { useState } from 'react';
import { DateInput } from '@jutro/components';
export const MinMaxDateInput = () => {
const [stateMessages, setStateMessages] = useState({});
const handleChange = (event, value, errorObject) => {
const errorCode = errorObject?.errorCode;
if (errorCode === 'INVALID_DATE') {
setStateMessages({
error: ['Please enter a valid date.'],
});
return;
}
if (errorCode === 'MIN_EXCEEDED' || errorCode === 'MAX_EXCEEDED') {
setStateMessages({
error: [`The year must be between 2000 and 2024.`],
});
} else {
setStateMessages({});
}
};
return (
<div>
<DateInput
label="Enter a date between year 2000 and year 2024"
minDate={{ day: 1, month: 1, year: 2000 }}
maxDate={{ day: 31, month: 12, year: 2024 }}
onChange={handleChange}
stateMessages={stateMessages}
/>
</div>
);
};
Bei Verwendung der Eigenschaft readOnly oder displayOnly kann das Format der Datumsangaben geändert werden, wenn die Eigenschaft displayFormat verwendet wird.
import React from 'react';
import { DateInput } from '@jutro/components';
export const DisplayOptionsDateInput = () => {
return (
<div>
<div style={{ display: 'flex', gap: '1.5rem', flexWrap: 'wrap'}}>
<DateInput label="Vshort" readOnly displayFormat="vshort" initialValue={{ day: 20, month: 6, year: 2024 }} />
<DateInput label="Short" readOnly displayFormat="short" initialValue={{ day: 20, month: 6, year: 2024 }} />
<DateInput label="Long" readOnly displayFormat="long" initialValue={{ day: 20, month: 6, year: 2024 }} />
</div><br />
<div style={{ display: 'flex', gap: '1.5rem', flexWrap: 'wrap', justifyContent: 'center', alignItems: 'center'}}>
<DateInput label="Abbreviated" readOnly displayFormat="abbreviated" initialValue={{ day: 20, month: 6, year: 2024 }} />
<DateInput label="Full" readOnly displayFormat="full" initialValue={{ day: 20, month: 6, year: 2024 }} />
</div>
</div>
);
};
Änderungsprotokoll
10.13.0
Für die DateInput-Komponente wurde ein Importpfad aus @jutro/components hinzugefügt.
Der alte Importpfad aus @jutro/components/new wird in einer künftigen Hauptversion entfernt.
Benutzern wird empfohlen, den folgenden Befehl auszuführen, um einen Codemod anzuwenden und die Importpfade in ihrem Code zu aktualisieren.
jutro codemod:apply --name=MigrateDateInputImportFromNew
Weitere Informationen zu Jutro-Codemods finden Sie in der Codemods-Dokumentation.
10.5.0
Es wurde eine neue @jutro/components/new/DateInput-Komponente eingeführt, die die abgekündigten Vorgänger @jutro/components/SimpleDateField und @jutro/components/SimpleMonthYearField ersetzt.
