Verwendung
Überblick
Die LookupField-Komponente ermöglicht es Benutzern, anhand von Schlüsselwörtern einen Wert aus den verfügbaren Werten auszuwählen. Sie kann eine Hauptquelle für die Entdeckung oder Filterung von Inhalten sein.
Bei Verwendung als Suchleiste bestimmt die Platzierung der Suchleiste den Umfang der Suche und der Ergebnisse.
- Suchleisten, die in einer Kopfzeile platziert sind, suchen in der gesamten Anwendung nach Ergebnissen.
- Suchleisten, die innerhalb eines Elements platziert werden, suchen nur innerhalb des Elements nach Ergebnissen.
Aufbau

Die LookupField-Komponente erscheint mit einer Beschriftung, einem Eingabefeld und einem Symbol.
LookupField besteht aus:
- Beschriftung: stellt den Kontext für die Suche des Benutzers her.
- Eingabefeld: ermöglicht den Benutzern die Eingabe von Schlüsselwörtern, Text und bestimmten Wörtern.
- (Wenn als Suche verwendet) Suchen-Symbol: löst die Suche aus, wenn darauf geklickt wird.
- Löschen-Symbol: entfernt den gesamten Inhalt aus dem Eingabefeld.
Best Practices
- Verwenden Sie Platzhaltertext, um Benutzern Hinweise auf geeignete Begriffe für den jeweiligen Kontext zu geben.
- Beziehen Sie automatische Vorschläge ein, wo immer dies möglich ist.
- Geben Sie die Kategorien der verfügbaren Werte klar und eindeutig an.
- Verfassen Sie eine klare Leerzustandsmeldung, die den Benutzer zum nächsten Schritt leitet und Vorschläge für das weitere Vorgehen macht. (Siehe „Überlegungen zum UX-Schreiben“ unten).
- Verwenden Sie Lookups und Suchfunktionen in Ihrer Anwendung sparsam. Nicht jedes Element muss nachgeschlagen oder gesucht werden.
- Heben Sie die Begriffe hervor, die der Benutzer in die Ergebnisse eingegeben hat.
- Fügen Sie den Ergebnissen Beschreibungen hinzu, um Benutzern die Navigation und die Auswahl der richtigen Option zu erleichtern.
- Zeigen Sie die Anzahl der zurückgegebenen Ergebnisse an.
- Behalten Sie den Originaltext bei, nachdem der Benutzer die Abfrage ausgeführt hat.
- Verwenden Sie ein Verarbeitungssymbol, wenn das Abrufen von Werten mehr als 5 Sekunden dauert.
- Benutzer verstehen den Zweck eines Lookup-Felds. Verwenden Sie daher nur eine inhaltsspezifische Beschriftung (anstelle eines allgemeinen Begriffs wie „Suchen“).
Verhalten
Zustände
Die LookupField-Komponente hat als mögliche Zustände „Aktiviert“, „Deaktiviert“, „Aktiv“ und „Fokus“.
- Aktiviert: Teilt dem Benutzer mit, dass das Element für die Interaktion aktiviert ist (Standard).
- Deaktiviert: Teilt dem Benutzer mit, dass das Element nicht interaktiv ist.
- Fokus: Gibt eine Rückmeldung darüber, dass der Benutzer das Element hervorgehoben hat, in der Regel über eine Eingabemethode wie eine Tastatur oder Sprachbefehl.
- Aktiv: Gibt eine Rückmeldung darüber, dass der Benutzer auf das Element klickt oder tippt.
Interaktionen
Maus
Wenn der Benutzer in das Lookup-Feld klickt, „blinkt“ der Cursor, bis der Benutzer mit der Eingabe beginnt.
Benutzer sollten die Möglichkeit haben, den Vorgang sowohl über das Symbol als auch über die Eingabetaste zu initiieren.
Tastatur
Wenn TAB gedrückt wird, wechselt der Tastaturfokus auf das Eingabefeld. Durch Drücken der Leertaste oder der Pfeiltaste nach unten wird das Popup-Menü mit einer Liste von Werten geöffnet. Die Liste lässt sich verfeinern, indem die ersten Buchstaben des gewünschten Namens eingetippt werden.
Screenreader
Das Eingabefeld und die Beschriftung werden über das aria-labelledby-WAI-ARIA-Attribut zugeordnet. Das Feld enthält auch den Wert von aria-autocomplete="list", um anzuzeigen, dass es ein Listen-Popup mit Autovervollständigungsfunktion enthält. Während Sie tippen, füllt das Eingabefeld eine Dropdown-Liste mit Werten aus, die am ehesten dem entsprechen, was Sie in das Feld eingeben. Die Option, die mit den eingegebenen Informationen übereinstimmt, wird automatisch fokussiert und von einem Screenreader vorgelesen.
Navigation
- Wenn der Benutzer das Symbol auswählt oder die Eingabetaste drückt, werden die Ergebnisse unterhalb des Suchfelds angezeigt.
- Wie der Benutzer durch die Ergebnisse navigiert, hängt von der jeweiligen Anwendung ab.
Fehlerbedingungen
Wenn es keine Ergebnisse auf der Grundlage der Kriterien gibt, erscheint eine Meldung, die zu weiteren Schritten ermutigt, sofern möglich.
Überlegungen zum UX-Schreiben
Leerzustände
- Wenn Sie einen Leerzustände beschreiben (z. B. Suchvorgänge, die keine Ergebnisse liefern), vermeiden Sie es, dem Benutzer mitzuteilen, was nicht vorhanden ist. Nutzen Sie stattdessen die Gelegenheit, zu vermitteln, was vorhanden ist.
- Verwenden Sie KEINE Begriffe wie „System“, „Abfrage“ oder „Werte“. Zum Beispiel: „Es wurden keine Ergebnisse für die eingegebenen Werte gefunden“ oder „Die Abfrage ergab keine Ergebnisse.“
- Ein Leerzustand bei Suchergebnissen sollte den Benutzer zum nächsten Schritt leiten und ihn im Ablauf des Produkts weiterbringen.
- Erklären Sie die Situation. Teilen Sie den Benutzern mit, dass Sie nicht gefunden haben, wonach sie gesucht haben. Ihr Ton sollte einfühlsam sein.
- Schlagen Sie alternative Wege vor, um voranzukommen, die für Ihre Art von Inhalt relevant sind, zum Beispiel:
- In der Regel gibt es mehrere Möglichkeiten, nach derselben Sache zu suchen. Dazu gehören die Suche nach Kategorien, die Suche nach einem allgemeineren oder spezifischeren Begriff, die Verwendung von Synonymen und die Überprüfung der Rechtschreibung.
- Gibt es Sachen, die dem ähnlich sind, was der Benutzer gesucht hat? Sie können Artikel oder Links vorschlagen, die so ähnlich wie möglich sind. Zum Beispiel:
- Artikel desselben Herstellers (z. B. andere Ford-Fahrzeuge).
- Artikel mit ähnlichen Spezifikationen von verschiedenen Herstellern (z. B. Fahrzeuge von 2010).
- Artikel, die einen ähnlichen Typ, Stil oder eine ähnliche Ausstattung haben (z. B. Limousinen der Mittelklasse).
- Kann Ihre Suchmaschine ähnliche Begriffe finden? Wenn ja, sollten Sie diese Ergebnisse den Benutzern anbieten, um ihnen eine weitere Suche zu ersparen.
- Es ist wichtig zu verstehen, was die Benutzer mit ihrer Suche erreichen wollen. Bieten Sie den Benutzern etwas, das sie ihrem Ziel näher bringt.
- Achten Sie auf eine freundliche und umgangssprachliche Sprache, zum Beispiel: „Wir konnten keine Ergebnisse finden. Haben Sie [Link zu einem ähnlichen Begriff] gemeint? Versuchen Sie, nach etwas anderem zu suchen oder Ihre Suche zu erweitern.“
Platzhaltertext
- Verwenden Sie Platzhaltertext, um die Suche zu vereinfachen. Sie können zum Beispiel die Auswahl einschränken, indem Sie im Suchfeld Kategorien definieren. Auf diese Weise können sich die Benutzer auf die Möglichkeiten konzentrieren und sich bei der Suche orientieren.
- Alternativ können Sie den Benutzern auch eine direkte Frage (vorzugsweise mit der Anrede „Sie“) zu besonders wichtigen Feldern stellen. Das wird die Benutzer motivieren, Antworten zu finden und in die Website einzutauchen.
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.
Code
const values = [
{
displayName: 'John Doe',
id: '1',
type: 'account'
},
{
displayName: 'Marine',
id: '2',
type: 'policy'
}
]
const optionTypes = [
{
type: 'account',
icon: PersonIcon,
className: "account-icon",
displayName: "Account"
},
{
type: 'policy',
icon: DirectionsBoatIcon,
className: "policy-icon",
displayName: "Policy"
}
]
<LookupField
id="lookup"
availableValues={values}
optionTypes={optionTypes}
/>
Importanweisung
import { LookupField } 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
iderforderlich
BeschreibungUnique identifier of the component.
autoTrim
BeschreibungIf set to true, will automatically trim string values on change.
availableValues
TypLookupCodeOptionShape | LookupOptionShape[]
BeschreibungArray of choice objects to display.
className
BeschreibungCSS class name for this component.
contentContainerClassName
BeschreibungCSS class name for the content container of the component.
controlClassName
BeschreibungCSS class name for the control of the component.
createNewMessage
BeschreibungThe text to display when a new option is being created by the user.
dataPath
BeschreibungThe full path of the view model.
dataType
defaultValue
BeschreibungSets the default field value on render, if there is a default value. It needs an onValueChange function to work.
disabled
BeschreibungIf set to true, this field is disabled.
hideLabel
BeschreibungHides the label on any layout.
BeschreibungType attribute that specifies the type of element to display.
internalClassNames
BeschreibungMap of CSS class names for overriding individual parts of the component's styles.
isClearable
BeschreibungIf set to true, ClearIndicator will be shown.
isInitiallyOpen
BeschreibungIf set to true, the dropdown will be open initially.
label
BeschreibungLabel text to display; if not provided, uses id for development.
labelClassName
BeschreibungCSS class name for the label of the component.
labelContainerClassName
BeschreibungCSS class name for the label container of the component.
labelPosition
BeschreibungPosition of the label relative to the input field.
layout
BeschreibungLayout to use with this field.
messageProps
BeschreibungMessage properties for error message/aria-label.
model
BeschreibungPassed as the second argument to onValueChange.
nullable
BeschreibungIf set to true, this field returns undefined when the user deletes the data/selection on the input.
onAddNew
Typ(...args: any[]) => any
BeschreibungCallback when a new item is created.
onBlur
Typfunction (FocusEvent<HTMLInputElement>)
BeschreibungA callback called after the component is focused.
onFocus
Typfunction (FocusEvent<HTMLInputElement>)
BeschreibungA callback called after the component is focused.
onLoadValues
Typ(...args: any[]) => any
BeschreibungFunction for asynchronous data loading.
onValidationChange
BeschreibungCallback when validation is changed; receives 'isValid', (model or path) and validation message for this component.
onValueChange
Typfunction (any, object | string)
BeschreibungCallback when value is changed; receives new value and (model or path) for this component.
optionTypes
Typ{ type: string, icon: Icon, className: string, displayName: IntlMessageShape}[]classNameerforderlich
BeschreibungCSS class name to apply to the option.
displayNameerforderlich
BeschreibungDisplay name of the option type.
iconerforderlich
BeschreibungAn Icon component to render on the component. The value must be an Icon component or the icon's name. For example, CheckIcon or 'gw-check'.
typeerforderlich
BeschreibungDescription of the available option types.
path
BeschreibungPassed as the second argument to onValueChange, if model is not present.
phone
BeschreibungLookupfield properties that are overridden at 'phone' breakpoint.
phoneWide
BeschreibungLookupfield properties that are overridden at 'phoneWide' and 'phone' breakpoint.
placeholder
BeschreibungPlaceholder to display on an empty component.
readOnly
BeschreibungIf set to true, this field is readonly.
recentlyViewedMessage
BeschreibungThe text to display in the "recently viewed" bar.
required
BeschreibungIf set to true, this field is required. If used with @jutro/validation, this prop can also be used to set the custom message overwrite. This can be done by using a tuple with the first value as true and the second value as the custom message. For example: required: [true, "a custom message"].
requiredFieldValidationMessage
BeschreibungUsed to override the default required field message.
schemaRequired
BeschreibungIf set to true, this field is required by the schema.
secondaryLabel
BeschreibungSecondary label text to display; if not provided, uses '[id]' for development.
secondaryLabelClassName
BeschreibungCSS class name for the secondary label of the component.
secondaryLabelId
BeschreibungSecondary label ID. It's used for accessibility - to link the secondary label with the input element.
showErrors
BeschreibungShow errors for this field, works only when field is pristine.
showOptional
BeschreibungShow an indicator that informs the user that a value is optional in this look-up field.
showRecentlyViewed
BeschreibungIf set to true, the "recently viewed" bar will be shown.
showRequired
BeschreibungShow an indicator that informs the user that a value is required in this look-up field.
showValidationIcon
BeschreibungShows an indicator that informs the user whether the current input value is valid. Whether the input is valid depends on the object entered in the validator prop.
successMessage
BeschreibungSuccess message to apply to the component if it is valid.
tablet
BeschreibungLookupfield properties that are overridden at 'tablet', 'phoneWide' and 'phone' breakpoint.
testId
BeschreibungData attribute that specifies the data-testid used in testing. If not provided, the data attribute is set to id.
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.
validateOnUnmount
BeschreibungIf set to true, onValidationChange callback is fired with isValid = true when the component is unmounted. Works only for the old validation mechanism.
validationMessages
BeschreibungValidation messages to show for this field; only rendered if showErrors is true.
validator
BeschreibungAn object which should contain a regex pattern as string and a validation message as string. If a user's input matches the regex pattern, the value will be valid, otherwise the message will be shown.
value
BeschreibungValue to display in the control.
visible
BeschreibungIf set to true, this field is visible.
enableMultipleValidationVerworfen
BeschreibungUsed by the @jutro/validation package: Displays multiple field validation messages all at once.
registerValidationVerworfen
BeschreibungOptional callback used by the @jutro/validation package to register field validation to use the validation hook.
Hooks
Für look-up field sind keine Hooks verfügbar.
Übersetzungsschlüssel
Die LookupField-Komponente definiert drei Übersetzungsschlüssel:
| Schlüssel | Verwendet für |
|---|
| jutro-components.widgets.inputs.LookupField.addItem | Text, der angezeigt wird, wenn der Benutzer ein neues Element hinzufügt |
| jutro-components.widgets.inputs.LookupField.unknownType | Text, der angezeigt wird, wenn der Elementtyp unbekannt ist |
| jutro-components.widgets.inputs.LookupField.recentlyViewed | Text, der angezeigt wird, wenn das Element kürzlich angezeigt wurde |
Escape Hatches
Weitere Informationen finden Sie in unserer Dokumentation über Escape Hatches.
Beispiele
Im Abschnitt Verwendung finden Sie Informationen zum korrekten Design einer look-up field-Komponente und den verschiedenen von Guidewire bereitgestellten Konfigurationsoptionen.
Beispiel für eine einfache Suche
Ein look-up field besteht aus einem Textfeld, das mit einer Sammlung von Werten verbunden ist, die ein Benutzer zur Suche nach bestimmten Werten verwendet. Bei einem einfachen look-up field legen Sie die gültigen Werte mithilfe der availableValues-Eigenschaft zusammen mit einer optionTypes-Eigenschaft fest, um den Typ des Werts zu differenzieren. Im folgenden Beispiel können Sie das Konto „John Doe“ oder die Police „Marine“ nachschlagen. Sie können auf das Suchfeld klicken, um die gültigen Optionen anzuzeigen, oder Sie können durch Eingabe auf die Optionen einschränken, die die eingegebenen Zeichen enthalten.
Wenn Sie eine Option eingeben, die nicht vorhanden ist, informiert Sie look-up field, dass es keine Optionen gibt und nichts ausgewählt ist.
const values = [
{
displayName: 'John Doe',
id: '1',
type: 'account'
},
{
displayName: 'Marine',
id: '2',
type: 'policy'
}
]
const optionTypes = [
{
type: 'account',
icon: PersonIcon,
className: "account-icon",
displayName: "Account"
},
{
type: 'policy',
icon: DirectionsBoatIcon,
className: "policy-icon",
displayName: "Policy"
}
]
<LookupField
id="lookup"
availableValues={values}
optionTypes={optionTypes}
/>
Neues Beispiel hinzufügen
Mit der onAddNew-Eigenschaft können Sie eine Funktion zum Hinzufügen neuer Elemente angeben.
In diesem Beispiel verwenden wir den React-Hook useState, um neue Werte nachzuverfolgen, wenn sie hinzugefügt werden.
import React, { useState } from 'react';
import { LookupField } from '@jutro/components';
const availableValues = [
{
displayName: 'John Doe',
id: '1',
type: 'account',
},
{
displayName: 'Marine',
id: '2',
type: 'policy',
},
];
const optionTypes = [
{
type: 'account',
icon: PersonIcon,
className: 'account-icon',
displayName: 'Account',
},
{
type: 'policy',
icon: DirectionsBoatIcon,
className: 'policy-icon',
displayName: 'Policy',
},
];
const [values, setValues] = useState([...availableValues]);
const [currentValue, setCurrentValue] =
(useState < (typeof availableValues)[number]) | (null > null);
function addNewValue(value: string) {
let newValue = {
displayName: value,
id: (values.length + 1).toString(),
type: 'account',
};
setValues([...values, newValue]);
setCurrentValue(newValue);
}
<LookupField
id="lookup"
availableValues={values}
optionTypes={optionTypes}
placeholder={'Search here'}
onAddNew={(newValue) => addNewValue(newValue)}
/>;
Async-Beispiel
Sie können Werte aus einer externen Quelle laden, zum Beispiel einer API. Erstellen Sie dazu eine asynchrone Funktion und übergeben Sie sie an die Eigenschaft onLoadValues.
In diesem Beispiel definieren wir eine Funktion zum Simulieren eines asynchronen Aufrufs, der Werte etwa eine Sekunde nach der Eingabe in das Feld lädt.
const values = [
{
displayName: 'John Doe',
id: '1',
type: 'account',
},
{
displayName: 'Marine',
id: '2',
type: 'policy',
},
];
const optionTypes = [
{
type: 'account',
icon: PersonIcon,
className: 'account-icon',
displayName: 'Account',
},
{
type: 'policy',
icon: DirectionsBoatIcon,
className: 'policy-icon',
displayName: 'Policy',
},
];
async function simulateAsync(
delay: number,
exception = false
): Promise<string> {
return new Promise((resolve, reject) => {
setTimeout(
exception ? reject : resolve,
delay,
exception || 'action worked'
);
});
}
<LookupField
id="lookup"
optionTypes={optionTypes}
onLoadValues={(filterText: string) =>
simulateAsync(1000).then(() =>
availableValues.filter((lookupItem) =>
lookupItem.displayName.toLowerCase().includes(filterText.toLowerCase())
)
)
}
/>;