Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.
Textbereich ist ein Eingabefeld, in das die Benutzer langen Text eingeben können, der sich über mehrere Zeilen erstreckt. Häufige Anwendungsfälle sind die Eingabe ausführlicher Beschreibungen in Formularen und das Bereitstellen von Benutzerkommentaren.
Positionieren Sie eine deutlich sichtbare Beschriftung außerhalb des Textbereichsfeldes. 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 Texteingabefeld 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 Textbereichsfelds 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 eine Beschreibung seines Schadens abgefragt wird, können Sie ihn mithilfe von Fehlertext zu einer Lösung führen: „Geben Sie eine Beschreibung des Schadens 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.
Die Textbereichskomponente 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.
Textbereiche haben auch interaktive Zustände für Aktiviert, Fokussiert, 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 die Breite und Höhe des Textbereichs mit dem Ziehpunkt zur Größenänderung rechts unten im Feld bearbeiten. Wenn der Inhalt den sichtbaren Bereich überschreitet, wird ein vertikaler Bildlauf aktiviert.
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.
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.
Ü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.
<TextArea label="Text area component" id="textID1" rows={10} />
Durch die Übergabe dieser Eigenschaften id und rows werden diese Teil des HTML-input, das im HTML-DOM erstellt wird. Im Fall von rows hat das Textbereichselement 10 sichtbare Zeilen.
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:
Wenn maxLength angegeben wird, lässt die TextArea-Komponente die Eingabe von mehr Zeichen als dem festgelegten Wert nicht zu. Wenn der Wert jedoch programmgesteuert mit den Eigenschaften initialValue oder value festgelegt wird, wird diese Steuerung nicht angewendet, sodass Sie in diesem Szenario möglicherweise eine spezielle Validierung implementieren müssen, um unerwünschte Werte zu verhindern.
Die Standardanzahl der Zeilen, die die TextArea-Komponente anzeigt, ist 3. Wenn Sie diese Anzahl anpassen müssen, können Sie das native rows-Attribut verwenden.
Standardmäßig wird die Größe der TextArea-Komponente automatisch an den gesamten Inhalt angepasst (automatische Größenänderung). Wenn der Benutzer die Größe der Komponente manuell ändert, wird das Standardverhalten deaktiviert und die Komponente bleibt in der vom Benutzer eingestellten Breite und Höhe.
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.
Die TextArea-Komponente hat nur eine erforderliche Eigenschaft: label. Sie können andere Eigenschaften verwenden, um ihr Verhalten zu ergänzen, z. B. placeholder, secondaryLabel, onChange usw.
<TextInput label="Text area component" placeholder="Write something here" secondaryLabel="Free text element" />
Durch die tooltip-Eigenschaft wird für die TextArea-Komponente das QuickInfo-Symbol angezeigt und, wenn der Benutzer mit ihm interagiert, werden einige ergänzende Informationen angezeigt. Diese Eigenschaft kann einfach den anzuzeigenden Text empfangen {text: "this will be displayed when tooltip is opened"}. Sie können auch steuern, welche spezifische Aktion die QuickInfo anzeigen lässt, indem Sie ein zweites Attribut trigger übergeben. Es akzeptiert die standardmäßigen HTML-Ereignisse wie pointerover, focus oder blur. Standardmäßig wird die QuickInfo geöffnet, wenn der Benutzer auf das QuickInfo-Symbol klickt.
In diesem Beispiel wird die QuickInfo angezeigt, wenn sich der Mauszeiger über dem QuickInfo-Symbol befindet:
Die TextArea-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.
exportfunctionTextAreaValidation(){ const[validationMessages, setValidationMessages]=useState({}); const onChange =useCallback((e, newValue)=>{ if(!newValue || newValue.indexOf('a')==-1){ setValidationMessages({}); }else{ setValidationMessages({ error:['The text cannot contain the character `a`'], }); } },[]); return( <TextArea label="Do not accept words containing the 'a' character" secondaryLabel="Raises an error if the input contains the character 'a'" stateMessages={validationMessages} onChange={onChange} /> ); }
Sie können die value-Eigenschaft für das Szenario der kontrollierten Komponente verwenden:
exportfunctionTextAreaControlled(){ const[updatedValue, setNewValue]=useState('first given value'); constonChange=(e, newValue)=>{ setNewValue(newValue); }; return( <div> <TextArea label="Enter the value to be assigned to the input below" onChange={onChange} /> <br/> <TextArea label="Changes with the above" secondaryLabel="This value is automatically updated when the value above changes" value={updatedValue} /> </div> ); }
TextArea 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:
exportfunctionTextAreaRef(){ const textAreaRef =useRef(null); constsetFocus=(e)=>{ textAreaRef?.current?.focus(); }; return( <div> <Button label="Set focus on TextArea" onClick={setFocus}></Button> <TextArea label="Get the focus from the button" ref={textAreaRef} /> </div> ); }
Es wurde die neue Komponente @jutro/components/TextArea eingeführt, welche TextAreaField ersetzt.
Die frühere Komponente TextAreaField wurde 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.
