Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.3.x ist, um die entsprechende Dokumentation anzuzeigen.
Verwendung
Überblick
Eine Eingabemaske hilft Benutzern bei der Eingabe von Daten, da die Eingabe auf ein spezifisches Format beschränkt und festgelegt ist.
Sie können eine Maske auf das Texteingabefeld und das Telefoneingabefeld anwenden.
Zu verwenden
In Feldern mit einem spezifischen erwarteten Format, z. B. die Sozialversicherungsnummer oder Postleitzahl.
Nicht zu verwenden
- Bei Eingaben, bei denen ein Feld mit freier Formatierung erforderlich ist.
- In Fällen, in denen das Eingabemuster zu komplex für eine Maske ist. Für eine E-Mail-Adresse gibt es beispielsweise viele mögliche Optionen für die Eingabe.
Aufbau
Beispiel für das Telefoneingabefeld mit einer Eingabemaske
- Beschriftung: Beschreibt den Zweck eines Eingabefeldes.
- Eingabemaske: Ein Zeichenfolgenausdruck, der die Eingabe auf gültige Eingabewerte beschränkt. Die Eingabemaske erhält den Fokus.
- Eingabefeld Telefon: Erweitertes Feld, in dem Benutzer ihre Telefonnummer eingeben können. Es akzeptiert nur numerische Eingaben und wird automatisch formatiert.
Inhalt
Inhaltsstandards finden Sie in den Schreibrichtlinien für Texteingabe und Telefoneingabe.
Verhalten
Die Eingabemaske wird angezeigt, sobald der Fokus auf dem Feld liegt. Davor ist die Eingabe leer oder enthält einen Platzhaltertext.
Beispiel für ein aktiviertes Texteingabefeld (links) und ein fokussiertes Texteingabefeld (rechts).
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.3.x ist, um die entsprechende Dokumentation anzuzeigen.
Code
Importanweisung
import { MaskInput } 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 input field, also passed as a default value to aria-label.
maskerforderlich
BeschreibungString that formats the mask to display, for example 999-999-9999. It defines the structure of the input value, where each character represents a different type of input. For example, 9 represents a numeric character, A represents an alphabetical character, and * represents an alphanumeric character. It also defines the position of static characters, such as dashes or parentheses, and the overall input length. The component follows a fixed-length pattern, hence mask property does not allow optional characters.
className
BeschreibungCSS class name for this component.
disabled
BeschreibungIf set to true, component is rendered in disabled state.
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.
BeschreibungA map of special mask formatting characters and the corresponding regular expressions the input must satisfy.
Standardwert{9: '[0-9]', a: '[A-Za-z]', A: '[A-Z]', '*': '[A-Za-z0-9]', '&': '[0-9A-Z]'}
hideLabel
BeschreibungIf set to true, the label is not visible.
initialValue
BeschreibungInitial value of input. If the value property is specified along with this property, this property's value is discarded.
labelPosition
BeschreibungAllows to select label position.
onBlur
Typfunction (FocusEvent<HTMLInputElement>)
BeschreibungA callback called after the component is focused.
onChange
Typfunction (React.ChangeEvent<HTMLInputElement>, string)
BeschreibungCallback invoked when component value is changed.
onFocus
Typfunction (FocusEvent<HTMLInputElement>)
BeschreibungA callback called after the component is focused.
placeholder
BeschreibungPlaceholder to display on an empty component.
readOnly
BeschreibungIf set to true, component is rendered in a read-only state. For values in plain text, consider using displayOnly.
required
BeschreibungIf set to true, sets the field as required displaying 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
BeschreibungValue of input. Takes precedence over initialValue. If this property is passed, component works in controlled mode and its value changes only if this property changes.
Hooks
Für MaskInput sind keine Hooks verfügbar.
Übersetzungsschlüssel
Mit der Komponente MaskInput sind keine Übersetzungsschlüssel verknüpft.
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
Benutzerdefinierte Verhalten
Maskierter und unmaskierter Wert
Bei der Eingabe eines Werts in MaskInput wird dieser automatisch formatiert und als zweites Argument im onChange-Ereignis angegeben. Wenn Sie auf den unformatierten Wert zugreifen möchten, kann das MaskInput-Ereignis der Komponente onChange um einen dritten Parameter erweitert werden. Dieser Parameter ist ein Objekt, das die unmaskierte Eigenschaft enthält, die den unformatierten Wert enthält.
In einem nicht fokussierten und leeren MaskInput-Feld wird entweder nichts oder ein definierter Platzhalter angezeigt, wenn er standardmäßig definiert ist. Beim Fokussieren auf das Feld wird die Maske sichtbar. Benutzer können Werte eingeben, die mit der Maske übereinstimmen, wodurch die Maske ausgeblendet wird. Wenn der eingegebene Wert weniger Zeichen enthält als in der Maske angegeben, wird die Eingabe ignoriert. Bei teilweise ausgefüllten Masken werden der eingegebene Wert beibehalten und die restlichen Maskenzeichen angefügt, auch wenn das Feld den Fokus verliert. Im Modus readOnly und displayOnly bleibt die Maske unabhängig vom Zustand der Eingabe ausgeblendet. Im Modus disabled bleibt die Maske wie im Modus enabled sichtbar.
Kopieren und Einfügen
Wenn ein Wert in das Feld eingefügt wird, wird er entsprechend der angegebenen Maske formatiert. Wenn in MaskInput ein Zeichen gefunden wird, das nicht mit der Maske übereinstimmt, z. B. wenn Buchstaben eingefügt werden, obwohl Zahlen erwartet werden, werden das nicht übereinstimmende Zeichen und die übrigen Zeichen des Werts ignoriert. Wenn der eingegebene Wert die in der Maske angegebene Länge überschreitet, wird der Wert außerdem entsprechend der Länge der Maske abgeschnitten.
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
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.
Verwenden Sie die alte InputMaskField-Komponente?
- Um die entsprechende Dokumentation für die alten Komponenten anzuzeigen, wechseln Sie zu einer Version der Dokumentation, die älter als 10.3 ist.
- Diese ältere Komponente ist auch in Storybook verfügbar:
Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.3.x ist, um die entsprechende Dokumentation anzuzeigen.
Beispiele
import React from 'react';
import { MaskInput } from '@jutro/components';
export const BasicMaskinput = () => {
return (
<MaskInput
label="Mask input component"
mask="(999) 999-9999"
secondaryLabel="This is a secondary label"
initialValue="(123) 942-4237"
/>
);
};
Note: Wenn initialValue festgelegt ist und nicht mit der Maske übereinstimmt, wird dieser Wert verworfen.
Sie können eine benutzerdefinierte Zuordnung von Formatierungszeichen und den entsprechenden regulären Ausdrücken erstellen, die für die Eingabe vorgegeben sind. In diesem Beispiel steht die Maske DDD für alle Buchstaben von a bis z in Großbuchstaben und 0000 für alle Zahlen von 0 bis 5.
import React, { useState } from 'react';
import { TextInput, MaskInput } from '@jutro/components';
export const FormatCharsMaskInput = () => {
const [value, setValue] = useState('');
const formatChars = {
D: '[A-Z]',
0: '[0-5]',
};
return (
<div>
<MaskInput
label="Enter 3 letters in upper case"
mask="DDD-0000"
formatChars={formatChars}
/>
</div>
);
};
Sie können die value-Eigenschaft für das Szenario der kontrollierten Komponente verwenden:
import React, { useState } from 'react';
import { TextInput, MaskInput } from '@jutro/components';
export const ControlledMaskInput = () => {
const [enteredValue, setEnteredValue] = useState('');
const onChangefunc = (event) => {
const newValue = event.target.value;
setEnteredValue(newValue);
console.log('Entered value:', newValue);
};
return (
<div>
<MaskInput
label="Enter a number to be assigned to the following field"
mask="(999) 999-9999"
onChange={onChangefunc}
stateMessages={{}}
required
/>
<TextInput
label="The value is updated when the first field is modified"
value={enteredValue}
/>
</div>
);
};
Validierung
Mit den Eigenschaften onChange und onBlur können Sie die Eingabe validieren, wenn das Feld geändert wird oder den Fokus verliert. In diesem Beispiel wird das Feld außerdem über die required-Eigenschaft als Pflichtfeld festgelegt.
import React, { useState } from 'react';
import { TextInput, MaskInput } from '@jutro/components';
export const ValidationMaskInput = () => {
const [enteredValue, setEnteredValue] = useState('');
const onBlurfunc = (event) => {
const newValue = event.target.value;
setEnteredValue(newValue);
};
return (
<div>
<MaskInput
label="Validation onBlur example"
mask="(999) 999-9999"
onBlur={onBlurfunc}
stateMessages={{}}
required
/>
<TextInput
label="The value is updated when the first field loses its focus"
value={enteredValue}
/>
</div>
);
};
Fehlermeldung
Es kann eine benutzerdefinierte Fehlermeldung festgelegt werden.
import React from 'react';
import { MaskInput } from '@jutro/components';
export const ErrorMaskInput = () => {
return (
<MaskInput
label="Error field"
mask="(999) 999-9999"
stateMessages={{
error: ['This is a custom error message'],
}}
/>
);
};
Änderungsprotokoll
10.13.0
Für die MaskInput-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=MigrateMaskInputImportFromNew
Weitere Informationen zu Jutro-Codemods finden Sie in der Codemods-Dokumentation.
10.3.0
Es wurde eine neue @jutro/components/new/MaskInput-Komponente eingeführt, welche InputMaskField ersetzt.
Die frühere maskenbezogene Komponente InputMaskField wurde abgekündigt und in das @jutro/legacy-Paket verschoben. Um die entsprechende Dokumentation anzuzeigen, wechseln Sie zu einer älteren Version.
Ursprünglicher Speicherort der Komponente:
InputMaskField: @jutro/components/InputMaskField
Aktualisierter Speicherort der Komponente:
InputMaskField: @jutro/legacy/components/InputMaskField