Währungseingabe

Währungseingabe 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

Ein Währungsfeld ist ein erweitertes Eingabefeld, in dem Benutzer einen Geldbetrag in einer bestimmten Währung eingeben können.

Zu verwenden

Wenn Benutzer Geldbeträge in einer spezifischen Währung eingeben sollen, z. B. Euro oder Dollar.

Nicht zu verwenden

Wenn ein numerischer Wert eingegeben und dann schrittweise erhöht oder verringert werden soll. Verwenden Sie stattdessen die Zahleneingabe.

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. Währungscode oder -symbol: Gibt und zeigt den Währungstyp an, damit Benutzer Geldwerte genau eingeben und verstehen können.
4. Währungseingabefeld: Der Container, bestehend aus einer Füllung und einem Rand, in dem der Benutzer Daten eingibt.

Position der Beschriftung

Die Beschriftung für das Währungseingabefeld kann über (Standardeinstellung und empfohlen) oder links von der Eingabe selbst angezeigt werden.

Währungscodes und -symbole

Die Währungscodes entsprechen der Norm ISO 4217. Beim Einrichten der Komponente können Sie vom Währungscode zum Symbol wechseln (z. B. von USD zu $).

Bei mehreren Währungen werden die Währungscodes oder -symbole in einer geschlossenen und alphabetisch sortierten Liste angezeigt.

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 deutliche, sichtbare Beschriftung außerhalb des Währungseingabefelds. 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 Währungseingabefeld 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 das Währungseingabefeld ein.

Fehlertext zur Anleitung der Benutzer verwenden

Der Text der Fehlermeldung erklärt dem Benutzer, wie er den Fehler beheben kann. Fehler bei Währungseingabefeldern beziehen sich häufig auf Validierungsprobleme, die behoben werden müssen. Wenn beispielsweise bei einem Antragsprozess ein Benutzer ein Pflichtfeld für die geschätzten Reparaturkosten nicht ausfüllt, können Sie einen Fehlertext wie „Geben Sie die geschätzten Reparaturkosten ein“ verwenden.

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 Währungseingabefeld 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.

Währungseingabefelder 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.

Interaktionen

Maus

Benutzer können eine Währungseingabe aktivieren, indem sie in 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

Das Eingabefeld ist über eine „for/id“-Beziehung mit der zugehörigen Beschriftung verknüpft. Wenn Sie das Element „required“ in Storybook aktivieren, wechselt der Wert aria-required von „true“ zu „false“.

Tausendertrennzeichen

Das Tausendertrennzeichen wird nicht angezeigt, während der Benutzer Daten eingibt. Es wird angezeigt, nachdem die Eingabe abgeschlossen ist und der Benutzer das Feld per Klick oder Tabulatortaste verlassen hat.

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 Verwendung dieser Komponente in Ihrer Anwendung auf Folgendes:

• Die Beschriftungen und Anweisungen sind aussagekräftig und prägnant. Geben Sie bei Bedarf ergänzende Anweisungen.
• Die Komponente zeigt die richtige Währung an. (Der Standardwert ist USD.)
• Wenn das Eingabefeld erforderlich ist, aktivieren Sie das Kontrollkästchen aria-required 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.

Code

<CurrencyInput
  availableCurrencies={['USD', 'EUR']}
  label="Currency input component"
/>;

Importanweisung

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

availableCurrencieserforderlich

Typ

ISOCurrencyCodes

Beschreibung

List of ISO 4217 currency codes. At least one currency needs to be defined in an array The first currency will be used as a default one.

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.

currencyDisplay

Typ

'code' | 'symbol'

Beschreibung

Whether the currency will be displayed as a symbol or as text.

Standardwert

'symbol'

decimalPlaces

Typ

number

Beschreibung

The number of decimal places to display in the value. If it is set, the user is prevented from entering too many digits after the decimal point. If the value or initialValue props have too many digits after the decimal point, the displayed figure is rounded to the closest valid value.

Standardwert

2

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.

hideGrouping

Typ

boolean

Beschreibung

If set to true, it will hide intl currency value formatting on currency input.

hideLabel

Typ

boolean

Beschreibung

If set to true, the label is not visible.

initialValue

Typ

{ amount: number, currency: ISOCurrencyCode }

amount

Typ

number

Beschreibung

The number to display.

currency

Typ

ISOCurrencyCode

Beschreibung

The ISO Currency Code for this value's currency. Must be an element of the ISO Currency code array.

Beschreibung

Initial value of input. If value prop is specified along with this prop, this prop's value is discarded. If the decimalPlaces prop is specified along with this prop, the displayed value is rounded to the closest valid value.

labelPosition

Typ

'top' | 'left'

Beschreibung

Allows to select label position.

Standardwert

'top'

onChange

Typ

function (React.ChangeEvent<HTMLInputElement>, {amount: number, currency: ISOCurrencyCode})

amount

Typ

number

Beschreibung

The number to display.

currency

Typ

ISOCurrencyCode

Beschreibung

The ISO Currency Code for this value's currency. Must be an element of the ISO Currency code array.

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

{ amount: number, currency: ISOCurrencyCode }

amount

Typ

number

Beschreibung

The number to display.

currency

Typ

ISOCurrencyCode

Beschreibung

The ISO Currency Code for this value's currency. Must be an element of the ISO Currency code array.

Beschreibung

Value of the input. Takes precedence over initialValue. If this prop is passed, the component works in controlled mode and its value only changes if this prop changes. If the decimalPlaces prop is specified along with this prop, the displayed value is rounded to the closest valid value.

Typen ISOCurrencyCodes und ISOCurrencyCode

Typ ISOCurrencyCodes ist ein Zeichenfolgen-Array von ISO-4217-Währungscodes.

Typ ISOCurrencyCode ist eine Zeichenfolge mit einem Wert eines beliebigen Elements im ISOCurrencyCodes-Array.

  [
'AED',
'AFN',
'ALL',
'AMD',
'ANG',
'AOA',
'ARS',
'AUD',
'AWG',
'AZN',
'BAM',
'BBD',
'BDT',
'BGN',
'BHD',
'BIF',
'BMD',
'BND',
'BOB',
'BOV',
'BRL',
'BSD',
'BTN',
'BWP',
'BYN',
'BZD',
'CAD',
'CDF',
'CHE',
'CHF',
'CHW',
'CLF',
'CLP',
'CNY',
'COP',
'COU',
'CRC',
'CUC',
'CUP',
'CVE',
'CZK',
'DJF',
'DKK',
'DOP',
'DZD',
'EGP',
'ERN',
'ETB',
'EUR',
'FJD',
'FKP',
'GBP',
'GEL',
'GHS',
'GIP',
'GMD',
'GNF',
'GTQ',
'GYD',
'HKD',
'HNL',
'HTG',
'HUF',
'IDR',
'ILS',
'INR',
'IQD',
'IRR',
'ISK',
'JMD',
'JOD',
'JPY',
'KES',
'KGS',
'KHR',
'KMF',
'KPW',
'KRW',
'KWD',
'KYD',
'KZT',
'LAK',
'LBP',
'LKR',
'LRD',
'LSL',
'LYD',
'MAD',
'MDL',
'MGA',
'MKD',
'MMK',
'MNT',
'MOP',
'MRU',
'MUR',
'MVR',
'MWK',
'MXN',
'MXV',
'MYR',
'MZN',
'NAD',
'NGN',
'NIO',
'NOK',
'NPR',
'NZD',
'OMR',
'PAB',
'PEN',
'PGK',
'PHP',
'PKR',
'PLN',
'PYG',
'QAR',
'RON',
'RSD',
'RUB',
'RWF',
'SAR',
'SBD',
'SCR',
'SDG',
'SEK',
'SGD',
'SHP',
'SLE',
'SLL',
'SOS',
'SRD',
'SSP',
'STN',
'SVC',
'SYP',
'SZL',
'THB',
'TJS',
'TMT',
'TND',
'TOP',
'TRY',
'TTD',
'TWD',
'TZS',
'UAH',
'UGX',
'USD',
'USN',
'UYI',
'UYU',
'UYW',
'UZS',
'VED',
'VES',
'VND',
'VUV',
'WST',
'XAF',
'XAG',
'XAU',
'XBA',
'XBB',
'XBC',
'XBD',
'XCD',
'XDR',
'XOF',
'XPD',
'XPF',
'XPT',
'XSU',
'XTS',
'XUA',
'XXX',
'YER',
'ZAR',
'ZMW',
'ZWL',
]

Hooks

Für CurrencyInput sind keine Hooks verfügbar.

Übersetzungsschlüssel

Der CurrencyInput-Komponente sind nur 2 Übersetzungsschlüssel zugeordnet, die sich beide auf den aria-label-Standardtext beziehen:

Schlüssel	Verwendet für
jutro-components.fields.CurrencyDisplay.ariaLabel	aria-label-Wert für die Dropdown-Liste der Währungen
jutro-components.fields.CurrencyInput.ariaLabel	aria-label-Wert für die Feldbeschreibung

Escape Hatches

Weitere Informationen finden Sie in unserer Dokumentation über Escape Hatches.

Folgende Optionen sind verfügbar:

• Design-Token
• className-Eigenschaft
• Übergeben nativer HTML-Attribute
• Ref mit imperativen Handlern
• Native Ereigniseigenschaft

Ü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 input-Element für „amount“ zugewiesen.

<CurrencyInput
  availableCurrencies={['USD', 'EUR']}
  initialValue={{
    amount: 5,
    currency: 'USD',
  }}
  label="Currency input component"
  id="amountID1"
  max={10}
/>

Durch die Übergabe der Eigenschaften id und max werden diese Teil des HTML-Elements input, das im HTML-DOM erstellt wird. Im Fall von max wird verhindert, dass der Benutzer einen Wert über 10 schreibt (dies kann nur durch direktes Einfügen des Werts 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.

Benutzerdefinierte Verhalten von CurrencyInput

Bei CurrencyInput sind als Teil der Komponente einige benutzerdefinierte Verhalten implementiert:

Eine oder mehrere Währungen

Dies wird durch die Eigenschaft availableCurrencies gesteuert. Wenn Sie mehr als einen Währungscode angeben, zeigt die Komponente eine Dropdown-Liste zur Auswahl an. Dies gilt nicht, wenn die Eigenschaften displayOnly oder readOnly auf true festgelegt sind.

Verarbeitung ungültiger Werte

Wenn der Eigenschaft initialValue oder value ein Währungscode zugewiesen ist, der nicht in der Eigenschaft availableCurrencies enthalten ist, kann die Komponente nicht gerendert werden.

Ungültiger Währungscode in „initialValue.currency“. In „availableCurrencies“ nicht enthalten: GBP

Zuweisung der Standardwährung

Wenn mit der Eigenschaft initialValue oder value keine Währung angegeben wird, die standardmäßig ausgewählt werden soll, wird in der Komponente die erste in der Eigenschaft availableCurrencies übergebene Währung als Standardwährung verwendet.

Einschränkungen bei kontrollierter Währungseingabe

Sie können React-Zustände verwenden, um den Wert eines CurrencyInput-Elements zu steuern, aber es gibt dabei einige Einschränkungen.

1. Das Ereignis onChange wird nur ausgelöst, wenn der Fokus auf der Eingabe liegt. Wenn der Wert als kontrollierte Komponente aktualisiert wird, wird der onChange-Rückruf nicht ausgeführt.
2. Wenn CurrencyInput über eine decimalPlaces-Eigenschaft verfügt und einen Wert aus einer React-Zustandsaktualisierung erhält, wird der angezeigte Wert auf den nächsten gültigen Wert gerundet.

Im Code unten können Sie z. B. die erste Eingabe verwenden, um den Wert der zweiten Eingabe zu ändern. Dabei lassen sich die folgenden beiden Verhalten beobachten:

1. Wenn in der ersten Eingabe ein Wert größer als 100 oder kleiner als 0 eingegeben wird, werden die Validierungsmeldungen in der zweiten Eingabe nicht angezeigt, da der zugehörige Rückruf nicht ausgeführt wird.
2. Wenn Dezimalwerte eingegeben werden, wird der in der zweiten Eingabe angezeigte Wert auf die nächste ganze Zahl gerundet.

export function CurrencyInputDecimalPlacesControlledExample() {
  const [firstInputValue, setFirstInputValue] = useState({
    amount: 200,
    currency: 'USD',
  });
  const [validationMessages, setValidationMessages] = useState({});
  const max = 100;
  const min = 0;

  const handleFirstInputChange = useCallback((event, newValue) => {
    console.log(newValue);
    if (newValue && newValue.amount !== undefined && newValue.currency) {
      setFirstInputValue(newValue);
    }
  }, []);

  const handleSecondInputChange = useCallback(
    (event, newValue) => {
      setValidationMessages({});

      if (
        newValue &&
        newValue.amount !== undefined &&
        (newValue.amount > max || newValue.amount < min)
      ) {
        setValidationMessages({
          error: ['Value must be between 0 and 100'],
        });
      }
    },
    [max, min]
  );

  return (
    <CurrencyInput
      label="First currency input"
      secondaryLabel="Change this value to see the second input update"
      onChange={handleFirstInputChange}
      availableCurrencies={['USD']}
    />
    <CurrencyInput
      label="Second currency input"
      secondaryLabel="Value controlled by the first input"
      value={firstInputValue}
      decimalPlaces={0}
      onChange={handleSecondInputChange}
      availableCurrencies={['USD']}
      stateMessages={validationMessages}
      min={min}
      max={max}
    />
  );
}

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

Im Abschnitt Verwendung finden Sie Informationen darüber, wie und wann Sie die Komponente CurrencyInput verwenden können.

Beispiel für eine einfache Währungseingabe

Die Komponente CurrencyInput ist Teil des @jutro/components-Pakets. Sie wird zum Rendern einer Eingabe für Währungswerte verwendet. Ein Array von ISO-4217-Währungscodes muss obligatorisch für die Eigenschaft availableCurrencies angegeben werden, damit die Währungen aufgelistet werden, die ein Benutzer auswählen kann.

<CurrencyInput
  availableCurrencies={['USD', 'EUR']}
  label="Currency input component"
/>;

Währungseingabe mit nur einer verfügbaren Währung

Wenn nur eine Währungsoption angegeben wird, kann die Währungsauswahl nicht bearbeitet werden und die Option wird angezeigt.

<CurrencyInput
  availableCurrencies={['USD']}
  label="Currency input component"
/>;

Währungseingabe mit einem Initialwert

Um für CurrencyInput einen Initialwert hinzuzufügen, müssen Sie einen Betrag und eine Währung angeben.

<CurrencyInput
  availableCurrencies={['USD']}
  label="Currency input component"
  initialValue={{
    amount: 15467,
    currency: 'USD',
  }}
/>;

Anzeigeoptionen für Währungscodes

Sie können CurrencyInput so festlegen, dass entweder ein Währungssymbol oder der ISO-4217-Währungscode angezeigt wird.

<CurrencyInput
  availableCurrencies={['USD']}
  label="Currency input component"
  initialValue={{
    amount: 15467,
    currency: 'USD',
  }}
  currencyDisplay='code'
/>
<CurrencyInput
  availableCurrencies={['USD']}
  label="Currency input component"
  initialValue={{
    amount: 15467,
    currency: 'USD',
  }}
  currencyDisplay='symbol'
/>

Dezimalstellen

Die Eigenschaft decimalPlaces gibt die Anzahl der anzuzeigenden Dezimalstellen an. Sie hindert Benutzer daran, zu viele Stellen nach dem Komma einzugeben. Wenn jedoch die Eigenschaften initialValue oder value festgelegt sind, wird die Zahl auf den nächsten gültigen Wert gerundet.

Wenn decimalPlaces beispielsweise auf 0 festgelegt ist, kann der Benutzer keine Dezimalstellen eingeben. Die Eigenschaften initialValue oder value können jedoch Dezimalstellen haben.

<CurrencyInput
  label="Currency input component limited decimals"
  placeholder="Enter a value"
  secondaryLabel="Try to add an additional decimal"
  decimalPlaces={0}
  availableCurrencies={['USD']}
/>
<CurrencyInput
  label="Currency input with initial value"
  secondaryLabel="Rounded up from 5.66"
  initialValue={{currency: 'USD', amount: 5.66}}
  decimalPlaces={0}
  availableCurrencies={['USD']}
/>
<CurrencyInput
  label="Currency input with value"
  secondaryLabel="Rounded up from 5.66"
  value={{currency: 'USD', amount: 5.66}}
  decimalPlaces={0}
  availableCurrencies={['USD']}
/>

Validierung der Benutzereingabe bei Änderung

Das Ereignis onChange unterstützt den neuen Wert, den Sie eingeben, als zweiten Parameter und verwendet ihn für die Validierung. Verwenden Sie die Eigenschaft stateMessages, wenn ein Fehler angezeigt werden soll:

import { useCallback, useState } from 'react';
import { CurrencyInput } from '@jutro/components';

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

  const onChange = useCallback((e, newValue) => {
    const componentValue = newValue.amount;

    if (!componentValue || componentValue != 10) {
      setValidationMessages({
        error: ["The value must be 10. If it's not, we won't not accept it."],
      });
    } else {
      setValidationMessages({});
    }
  }, []);

  return (
    <CurrencyInput
      availableCurrencies={['USD']}
      label="Accept only 10"
      secondaryLabel="Will raise an error except when value is 10"
      stateMessages={validationMessages}
      onChange={onChange}
    />
  );
}

Kontrollierte Komponente

Sie können die value-Eigenschaft für das Szenario der kontrollierten Komponente verwenden:

import { useState } from 'react';
import { CurrencyInput, NumberInput } from '@jutro/components';

export function CurrencyInputControlled() {
  const [updatedValue, setAmount] = useState({
    amount: 200,
    currency: 'USD',
  });

  const onChange = (e, newValue) => {
    setAmount({ amount: newValue, currency: 'USD' });
  };

  return (
    <div>
      <NumberInput
        label="Enter the amount to be assigned to the next field"
        onChange={onChange}
      />
      <CurrencyInput
        availableCurrencies={['USD']}
        label="Changes with the above"
        secondaryLabel="This value is automatically updated when the value in the first field changes"
        value={updatedValue}
      />
    </div>
  );
}

Zugriff auf die ref-Eigenschaft zum Festlegen des Fokus (imperativer Handler)

Bei der Währungseingabe und anderen Eingaben kann über eine ref-Eigenschaft auf einige native Verhalten zugegriffen werden. Es werden jedoch nur bestimmte Funktionen verfügbar gemacht. Wenn Sie in diesem Beispiel auf die Schaltfläche klicken, wird der Fokus automatisch auf die Währungseingabe darunter gelegt.

import { useRef } from 'react';
import { CurrencyInput, Button } from '@jutro/components';

export function CurrencyInputRef() {
  const currencyRef = useRef(null);

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

  return (
    <div>
      <Button
        label="Set focus on currency input"
        onClick={setFocus}></Button>
      <CurrencyInput
        availableCurrencies={['USD']}
        label="Get the focus from the button"
        ref={currencyRef}
      />
    </div>
  );
}

Änderungsprotokoll

10.13.0

Die neue Eigenschaft decimalPlaces wurde der Komponente CurrencyInput hinzugefügt. Sie ist standardmäßig auf 2 festgelegt. Der Benutzer kann keine weiteren Dezimalstellen eingeben, die über dem durch decimalPlaces vorgegebenen Limit liegen.

Die Eigenschaften initialValue und value können zusätzliche Stellen nach dem Dezimaltrennzeichen haben, aber der angezeigte Wert wird auf den nächsten gültigen Wert gerundet.

10.0.0

Es wurde die neue Komponente @jutro/components/CurrencyInput eingeführt, die CurrencyField ersetzt.

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

Ursprünglicher Speicherort der Komponente:

• CurrencyField: @jutro/components/CurrencyField

Aktualisierter Speicherort der Komponente:

• CurrencyField: @jutro/legacy/components/CurrencyField

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