Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.
Beschriftung: Beschreibt den Zweck eines Eingabefeldes.
Hilfstext: 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.
Eingabefeld Telefon: Erweitertes Feld, in dem Benutzer ihre Telefonnummer eingeben können. Es akzeptiert nur numerische Eingaben und wird automatisch formatiert.
Landesvorwahl-Selector (optional): Dropdown-Liste, in der der Benutzer aus einer Liste von Landesvorwahlen auswählen kann. Der Vorwahl ist die entsprechende Landesflagge vorangestellt, um die Erkennung zu erleichtern.
Positionieren Sie eine deutlich sichtbare Beschriftung außerhalb des Telefoneingabefeldes. 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 Telefonnummer 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 Telefonnummereingabefelds 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 Telefonnummer gefragt wird, können Sie ihn mithilfe von Fehlertext zu einer Lösung führen: „Geben Sie Ihre Telefonnummer 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 Telefoneingabefeld 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.
Telefoneingabefelder 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.
Der Benutzer kann die Telefonnummer eingeben, indem er den Telefoneingabebereich auswählt oder fokussiert. Die Eingaben werden formatiert, wenn der Fokus aufgehoben wird.
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.
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.
Optional ISO 3611-1 country codes to include with the phone number.
Beschreibung
Initial value of input. If value prop is specified along with this prop, this prop's value is discarded. Accepts object with phoneNumber and optionally countryCode.
Value 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. Accepts object with phoneNumber and optionally countryCode.
Es gibt mehrere Übersetzungsschlüssel, die mit der PhoneInput-Komponente verknüpft sind. Sie lassen sich in zwei Gruppen einteilen: Platzhalter-Standard und Ländernamen.
Der Name des Landes, das mit dem spezifischen Ländercode verbunden ist.
Dies ist die Liste der Ländercodes, die Sie mit dem obigen Übersetzungsschlüssel verwenden können:
ac ad ae af ag ai al am ao ar as at au aw ax az ba bb be bf bg bh bi bj bl bm bn bo bq br bs bt bw by bz ca cc cd cf cg ch ci ck cl cm cn co cr cu cv cw cx cy cz de dj dk dm do dz ec ee eg eh er es et fi fj fk fm fo fr ga gb gd ge gf gg gh gi gl gm gn gp gq gr gt gu gw gy hk hn hr ht hu id ie il im in io iq ir is it je jm jo jp ke kg kh ki km kn kp kr kw ky kz la lb lc li lk lr ls lt lu lv ly ma mc md me mf mg mh mk ml mm mn mo mp mq mr ms mt mu mv mw mx my mz na nc ne nf ng ni nl no np nr nu nz om pa pe pf pg ph pk pl pm pr ps pt pw py qa re ro rs ru rw sa sb sc sd se sg sh si sj sk sl sm sn so sr ss st sv sx sy sz tc td tg th tj tk tl tm tn to tr tt tv tw tz ua ug us uy uz va vc ve vg vi vn vu wf ws xk ye yt za zm zw
Übergeben von HTML-Eigenschaften an die Komponente
Sie können HTML-Eingabeattribute verwenden, mit Ausnahme derjenigen, die von Jutro überschrieben werden. Diese Attribute werden dem HTML-Element input zugewiesen.
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:
Die Validierung und Formatierung von Telefonnummern wird ständig weiterentwickelt, um sich an die von jedem Land neu definierten Regeln anzupassen. PhoneNumberInput wurde zur Unterstützung dieser Standards entwickelt und wird jeweils aktualisiert, um neue Regeln zu berücksichtigen, sobald sie erscheinen. Diese Aktualisierungen können das Verhalten der Komponente ändern, um die spezifischen Anforderungen der Regeln zu unterstützen.
Automatischer Platzhalter für das ausgewählte Land
Wenn die placeholder-Eigenschaft nicht gesetzt ist, setzt PhoneNumberInput den Eingabeplatzhalter automatisch auf eine Beispielnummer für das ausgewählte Land.
Wenn der Ländercode bei der Eingabe der Telefonnummer eingegeben wird, wird sie automatisch verwendet, um den Wert des Länderwahlschalters festzulegen, und der Code wird aus der Nummerneingabe entfernt. Wird ein ungültiger Code verwendet, wird die automatische Änderung nicht angewendet.
Obwohl Sie für die Fehlerbehandlung verantwortlich sind, verfügt die PhoneNumberInput-Komponente über bestimmte interne Validierungs- und Transformationsmechanismen, deren Ergebnisse Ihnen zur Unterstützung des Validierungsprozesses zur Verfügung stehen.
Das onChange-Ereignis liefert einen dritten Parameter mit dem Ergebnis der durchgeführten Validierung, ein Objekt mit einem numerischen errorCode zur Identifizierung des Problems, so dass Sie es einer benutzerdefinierten Fehlermeldung zuordnen können.
Die errorCode-Validierungslogik wird durch die Übergabe des Codes an die intl-tel-input-Bibliothek ausgeführt, die unabhängig aktualisiert werden kann.
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.
Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.
Obwohl Sie nicht verpflichtet sind, einen Ländercode an PhoneNumberInput zu übergeben, verhält sich die Komponente ohne Ländercode nicht wie eine Telefonnummerneingabe. Sie haben 3 verschiedene Möglichkeiten, diesen anzugeben:
Mit der countries-Eigenschaft: Damit können Sie einen einzelnen ISO-Ländercode übergeben, der als Standard verwendet wird, und der numerische Ländercode wird angezeigt.
<PhoneNumberInput label="Phone input component with US set as default" countries={['US']} />
Mit der initialValue-Eigenschaft: Damit wird die Eingabekomponente initialisiert und der Ländercode wird nicht angezeigt. Die telefonbezogenen Funktionen funktionieren jedoch normal.
Mit der value-Eigenschaft: Damit wird die Komponente gesteuert. Die Komponente wird initialisiert und der Ländercode wird nicht angezeigt. Die telefonbezogenen Funktionen funktionieren jedoch normal.
Die PhoneNumberInput-Komponente zeigt eine Dropdown-Auswahl für Ländercodes an, wenn Sie mehr als einen ISO-Ländercode in der countries-Eigenschaft angeben. Wenn Sie keine initialValue angeben, wird der erste Ländercode im Array als Anfangswert in der Auswahlliste angezeigt.
Einfache Telefonnummer mit benutzerdefiniertem Platzhalter
Die PhoneNumberInput-Komponente verwaltet den Platzhalter, der je nach ausgewähltem Land angezeigt wird. Sie können ihn jedoch überschreiben und einen eigenen Platzhalter festlegen.
<PhoneNumberInput label="Phone input component with a custom placeholder" countries={['PL','US']} placeholder="this is a custom placeholder" />
Die PhoneNumberInput-Komponente 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 Fehlermeldungen zu verwenden.
Dies ist ein Beispiel für die Handhabung der Validierung, wenn ein onChange-Ereignis ausgelöst wird.
exportfunctionPhoneNumberInputValidation(){ const[validationMessages, setValidationMessages]=useState({}); const onChange =useCallback((e, newValue, errorCode)=>{ const componentPhoneNumber = newValue.phoneNumber; const componentCountryCode = newValue.countryCode; const componentErrorCode = errorCode?.errorCode; setValidationMessages({}); if(componentErrorCode && componentErrorCode !=0){ setValidationMessages({ error:['The phone number is not correct'], }); }else{ if( componentPhoneNumber && componentCountryCode && componentCountryCode =='ES'&& componentPhoneNumber.indexOf('6')==0 ){ setValidationMessages({ error:['Only landline numbers are accepted for Spain'], }); } } },[]); return( <PhoneNumberInput countries={['ES','US']} label="Accepts any US number but accepts only landline numbers for Spain" secondaryLabel="Landline numbers cannot start by 6" stateMessages={validationMessages} onChange={onChange} /> ); }
Verwendung von „ref“ zur Festlegung des Fokus (imperativer Handler)
PhoneNumberInput und andere Eingaben ermöglichen es Ihnen, über eine ref-Eigenschaft auf einige native Verhaltensweisen zuzugreifen. Es werden jedoch nur bestimmte Funktionen verfügbar gemacht. Wenn Sie in diesem Beispiel auf die Schaltfläche klicken, wird der Fokus automatisch in der Eingabe unten gesetzt.
exportfunctionPhoneNumberRef(){ const inputRef =useRef(null); constsetFocus=(e)=>{ inputRef?.current?.focus(); }; return( <div> <Button label="Set the focus on input" onClick={setFocus}></Button> <PhoneNumberInput label="Get the focus from the button" countries={['ES','US']} ref={inputRef} /> </div> ); }
Es wurde eine neue @jutro/components/PhoneNumberInput-Komponente eingeführt, welche PhoneNumberField und IntlPhoneNumberField ersetzt.
Die früheren telefonbezogenen Komponenten PhoneNumberField und IntlPhoneNumberField wurden abgekündigt und in das @jutro/legacy-Paket verschoben. Um die entsprechende Dokumentation anzuzeigen, wechseln Sie zu einer Version der Dokumentation, die älter als 10.0 ist.
