Texteingabe

Texteingabe in Storybook

Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.

Verwendung

Überblick

Die Texteingabekomponente ermöglicht es Benutzern, Text und Zahlen in Dateneingabefelder einzugeben. Texteingaben gehören zu den wichtigsten und am häufigsten verwendeten Komponenten der Benutzeroberfläche, mit denen Benutzer interagieren. Sie ermöglichen es Benutzern, die notwendigen Informationen bereitzustellen, die ein System benötigt, um eine bestimmte Aufgabe oder einen Satz von Aufgaben zu erfüllen.

Zu verwenden

• Für die Eingabe eindeutiger Informationen, die mit einem vordefinierten Satz von Optionen nicht vorhergesagt werden können.
• Für die einzeilige Texteingabe.

Nicht zu verwenden

• Für Datums- oder Uhrzeiteintrag. Verwenden Sie stattdessen die Komponenten Datumsauswahl und Zeitauswahl.
• Wenn der Benutzer nach etwas suchen muss. Verwenden Sie stattdessen die Suchkomponente.
• Wenn der Benutzer nur eine Option aus einer vordefinierten Liste eingeben kann. Erwägen Sie die Verwendung eines Auswahlsteuerelements wie der Dropdown- oder Optionsfeldgruppe.

Formatierung

Aufbau

1. Beschriftung: Beschreibt den Zweck eines Eingabefeldes.
2. 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.
3. Texteingabefeld: Der Textfeld-Container, bestehend aus einer Füllung und einem Strich, auf dem die Benutzer Text eingeben.

Position der Beschriftung

Die Beschriftung für das aktuelle Texteingabefeld kann oben (Standard und empfohlen) oder links von der Eingabe selbst erscheinen.

Anpassung und Breite der Texteingabe

Die Größe der Eingabe sollte proportional zur Textmenge sein, die der Benutzer eingeben soll.

Quelle: Nielsen Norman Group

Passen Sie die Felder an den Typ und die Größe der Eingabe an.

Verwenden Sie keine übermäßig langen Eingabefelder.

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 Texteingabefeldes. 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

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.

Keinen Platzhaltertext verwenden

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.

Quelle: Nielsen Norman Group

Positionieren Sie Hinweise und Anweisungen, einschließlich Formatierungsbeispiele und -anforderungen, außerhalb des Felds.

Fügen Sie keine Platzhalter in Texteingabefelder ein.

Fehlertext zur Anleitung der Benutzer verwenden

Der Text der Fehlermeldung erklärt dem Benutzer, wie er den Fehler beheben kann. Im Falle des Texteingabefelds 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 E-Mail-Adresse gefragt wird, können Sie ihn mithilfe von Fehlertext zu einer Lösung führen: „Geben Sie Ihre E-Mail-Adresse 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.

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 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.

Groß- und Kleinschreibung verwenden

Für Feldbeschriftungen wird die übliche Groß- und Kleinschreibung verwendet.

Weitere Informationen zum Implementieren der Groß- und Kleinschreibung finden Sie im UI Text Style Guide.

Verwenden Sie die übliche Groß- und Kleinschreibung.

Schreiben Sie nicht alles groß. Dies beeinträchtigt die Lesbarkeit.

Verhalten

Zustände

Das Texteingabefeld 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.

Texteingabefelder 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.

Interaktionen

Maus

Benutzer können eine Texteingabe aktivieren, indem sie auf den Bereich innerhalb des Rahmens klicken.

Tastatur

Die Texteingabe-Komponente kann mit der Tastatur fokussiert werden.

Screenreader

Die Beschriftung und die Eingabe werden programmgesteuert miteinander verknüpft. Standardmäßig befindet sich eine QuickInfo neben der Beschriftung. Darin enthalten ist das WAI-ARIA-Attribut von aria-label="Show tooltip"und auch aria-expanded="false", das auf „true“ umschaltet, wenn die QuickInfo ausgelöst wird. Der Inhalt der QuickInfo wird von Screenreadern mithilfe der WAI-ARIA-Rolle „alert“ gesprochen. Wenn das erforderliche Kontrollkästchen in Storybook aktiviert ist, wird das Attribut „required“ zum Markup hinzugefügt und der Wert aria-required wechselt von „true“ zu „false“.

Textüberlauf

Wenn der Inhalt innerhalb der Texteingabe überläuft, sollte der Benutzer in der Lage sein, horizontal von einem Ende zum anderen zu scrollen, indem er Shift+Scroll verwendet. Der Benutzer kann auch die Tasten Left Arrow und Right Arrow verwenden, um den Mauszeiger von einer Seite zur anderen zu bewegen.

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.

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.

Code

<TextInput label="Text input component" />

Importanweisung

import { TextInput } 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

Typ

IntlMessageShape

Beschreibung

Label associated with input field, also passed as a default value to aria-label.

className

Typ

string

Beschreibung

CSS class name for this component.

disabled

Typ

boolean

Beschreibung

If set to true, component is rendered in disabled state.

displayOnly

Typ

boolean

Beschreibung

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.

hideLabel

Typ

boolean

Beschreibung

If set to true, the label is not visible.

initialValue

Typ

string

Beschreibung

Initial value of input. If value prop is specified along with this prop, this prop's value is discarded.

labelPosition

Typ

'top' | 'left'

Beschreibung

Allows to select label position.

Standardwert

'top'

onChange

Typ

function (React.ChangeEvent<HTMLInputElement>, string)

Beschreibung

Callback invoked when component value is changed.

placeholder

Typ

IntlMessageShape

Beschreibung

Placeholder to display on an empty component.

readOnly

Typ

boolean

Beschreibung

If set to true, component is rendered in a read-only state. For values in plain text, consider using displayOnly.

required

Typ

boolean

Beschreibung

If set to true, component is rendered as required and label has asterisk.

secondaryLabel

Typ

IntlMessageShape

Beschreibung

Secondary label text to display.

stateMessages

Typ

{ error: string[] }

Beschreibung

An object with a list of error messages for the current state.

tooltip

Typ

{ text: intlMessageShape, trigger: string } | intlMessageShape

text

Typ

IntlMessageShape

Beschreibung

Text to show tooltip content.

trigger

Typ

string

Beschreibung

The trigger to show the tooltip.

Beschreibung

Text to be displayed in the tooltip or tooltip object that includes: text - to show tooltip content, trigger - to set tooltip trigger.

value

Typ

string

Beschreibung

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.

Hooks

Für TextInput sind keine Hooks verfügbar.

Übersetzungsschlüssel

Es gibt keine Übersetzungen für TextInput.

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.

Folgende Optionen sind verfügbar:

• Design-Token
• Eine className-Eigenschaft
• Möglichkeit zum Übergeben von nativen HTML-Attributen
• Ref mit imperativen Handlern
• Eine native event-Eigenschaft

Ü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.

<TextInput
  label="Text input component"
  id="textID1"
  maxLength={10}
/>

Durch die Übergabe dieser Eigenschaften id und maxLength werden diese Teil des HTML-input, das im HTML-DOM erstellt wird. Im Fall von maxLength wird verhindert, dass der Benutzer mehr als 10 Zeichen schreibt. Dies kann nur durch direktes Einfügen des Wertes erfolgen.

Ref mit imperativen Handlern

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:

    const componentRef = useRef(null);

    const setFocus = () => {
        componentRef?.current.focus();
    }

    const removeFocus = () => {
        componentRef?.current.blur();
    }

    const scrollToComponent = () => {
        componentRef?.current.scrollIntoView();
    }

    <Component ref={componentRef}>

In Zukunft könnten weitere Optionen hinzukommen.

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.

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:

{
  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 die ältere InputField-Komponente?

• Um die entsprechende Dokumentation für die alten Komponenten anzuzeigen, wechseln Sie zu einer Version der Dokumentation, die älter als 10.0 ist.
• Die folgenden älteren Komponenten sind auch in Storybook verfügbar:

  • CurrencyField

Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.

Beispiele

Lesen Sie den Abschnitt Verwendung, um zu erfahren, wie und wann Sie die Texteingabekomponente verwenden können.

Basiseingabe

Die TextInput-Komponente benötigt nur die Eigenschaft label, um angezeigt zu werden. Andere Eigenschaften wie placeholder, secondaryLabel und onChange können verwendet werden, um das Verhalten zu ergänzen.

<TextInput
  label="Text input component"
  placeholder="Write what you want here"
  secondaryLabel="Free text input"
/>

Schreibgeschützt

TextInput und die anderen Eingaben bieten die Möglichkeit, die Komponente als display only zu setzen. Wenn diese Eigenschaft displayOnly auf true festgelegt ist, wird die Komponente als Text angezeigt, ohne das spezifische Aussehen der Eingabe.

<TextInput
  label="Text input component"
  placeholder="Write what you want here"
  secondaryLabel="Free text input"
  value="this is the value"
  displayOnly={true}
/>

QuickInfo

Durch die tooltip-Eigenschaft wird für die Komponente das QuickInfo-Symbol angezeigt. Wenn der Benutzer damit interagiert, werden auch einige ergänzende Informationen angezeigt. Diese Eigenschaft kann 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. Dies akzeptiert die standardmäßigen HTML-Ereignisse wie pointerover, focus und blur. Standardmäßig wird die QuickInfo durch Klicken auf das QuickInfo-Symbol geöffnet.

In diesem Beispiel wird die QuickInfo angezeigt, wenn sich der Mauszeiger über dem QuickInfo-Symbol befindet.

<TextInput
  label="Text input component"
  placeholder="Write what you want here"
  secondaryLabel="Free text input"
  tooltip={{ text: 'tooltip text', trigger: 'pointerover' }}
/>

Texteingabeüberprüfung bei Änderung

TextInput stellt keine spezielle Validierungslogik zur Verfügung, bietet aber eine Methode, 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 das onChange-Ereignis ausgelöst wird.

function TextInputValidation() {
  const [validationMessages, setValidationMessages] = useState({});

  const onChange = useCallback((e, newValue) => {
    if (!newValue || newValue.indexOf('a') == -1) {
      setValidationMessages({});
    } else {
      setValidationMessages({
        error: ['The text cannot contain `a` character'],
      });
    }
  }, []);

  return (
    <TextInput
      label="Do not accept words with 'a'"
      secondaryLabel="Will raise an error if contains 'a' character"
      stateMessages={validationMessages}
      onChange={onChange}
    />
  );
}

Kontrollierte Komponente

Die value-Eigenschaft kann für das Szenario der kontrollierten Komponenten verwendet werden:

export function InputControlled() {
  const [updatedValue, setNewValue] = useState('first given value');

  const onChange = (e, newValue) => {
    setNewValue(newValue);
  };

  return (
    <div>
      <TextInput
        label="Enter here the value to be assigned input below"
        onChange={onChange}
      />
      <br />
      <TextInput
        label="Changes with the above"
        secondaryLabel="This cannot be manually modified"
        value={updatedValue}
      />
    </div>
  );
}

Verwendung von ref zur Festlegung des Fokus

TextInput zusammen mit anderen Eingaben ermöglichen es Ihnen, über eine ref-Eigenschaft auf einige native Verhaltensweisen zuzugreifen. Es werden jedoch nur einige Funktionen verfügbar gemacht. In diesem Fall wird beim Klicken auf die Schaltfläche automatisch der Fokus auf die folgende Eingabe gesetzt:

export function InputRef() {
  const inputRef = useRef(null);

  const setFocus = (e) => {
    inputRef?.current?.focus();
  };

  return (
    <div>
      <Button
        label="Set focus on text input"
        onClick={setFocus}></Button>
      <TextInput
        label="Get the focus from the button"
        ref={inputRef}
      />
    </div>
  );
}

Änderungsprotokoll

10.0.0

Es wurde die neue Komponente @jutro/components/TextInput eingeführt, welche InputField ersetzt.

Die frühere Komponente InputField 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.

Komponente	Alter Ort	Neuer Ort
InputField	@jutro/components/InputField	@jutro/legacy/components/InputField

Es gibt Codemods, mit denen Sie vorhandene Importe automatisch umbenennen können.