React Select

Diese React-Komponente ermöglicht die Erzeugung eines dynamischen 'select'-Feldes mit integrierter Suche, Asynchroner-Datenabfrage uvm.

Instalation

$ npm install --save @boewa-software/react-select

Select

Die Nutzung erfolgt als klassische React-Komponente. Wie auch bei den klassischen React Formular-Komponenten, gibt es das Select in der Variante einer normalen Komponente und einer Controlled Component.

import React from 'react';
import {createRoot} from "react-dom/client";

import {Select} from '@boewa-software/react-select';

// target ist das DOM-Element, für das die React-Komponente eingesetzt wird
const target = getElementById('my-target');

const choices = ['First Choice', 'Second Choice', 'Last Choice'];

const root = createRoot(target);
root.render(<Select choices={choices} />);

Das Select bietet eine Standard-Implementierung zur Handhabung einfacher Werte als Array.

Sollen komplexere Daten (z.B. Objekte) gehandhabt werden, ist dies möglich. Dafür muss allerdings die Behandlung in der Ausgabe angepasst werden:

import React from 'react';
import {createRoot} from "react-dom/client";

import {Select} from '@boewa-software/react-select';

// target ist das DOM-Element, für das die React-Komponente eingesetzt wird
const target = getElementById('my-target');

const choices = [
    { id: 1, name: 'First Choice' },
    { id: 2, name: 'Second Choice' },
    { id: 3, name: 'Last Choice' }
];

// Komponente zur Anzeige des ausgewählten Werts übeschreiben
const ValueLabel = ({ value }) => `${value.name} (ID: ${value.id})`;

// Komponente zur Anzeige eines Listeneintrags zur Auswahl überschreiben
const ChoiceItem = ({ choice }) => choice.name;

const root = createRoot(target);
root.render(
    <Select choices={choices}
            valueLabelComponent={ValueLabel}
            choiceListProps={{
                choiceItemComponent: ChoiceItem
            }} />
);

Hinweis: Das ChoiceItem muss in das choiceListProps-Property übergeben werden, da die Auswahlliste intern eine eigene, ebenfalls vollständig überschreibbare Komponente ist.

Attribute

• choices: array

  Array mit auswählbaren Listen-Einträgen.

• onChange: function(any: newValue): void (optional)

  Callback-Methode die bei einer Werte-Änderung aufgerufen wird.

• value: any (optional)

  Aktueller Value-Wert. Wenn dieser übergeben wird, wird diese Komponente wie eine Controlled Component behandelt! Die Aktualisierung des Value-Werts muss dann über einen eigenen onChange-Handler erfolgen.

• initialValue: any (optional)

  Initialer Value-Wert, wenn es sich nicht um eine Controlled Component handelt.

• disabled: bool (default: false, optional)

  Attribut zum Deaktivieren.

• multiple: bool (default: false, optional)

  Ermöglicht die Auswahl mehrerer Werte. intialValue bzw. value müssen dann vom Typ array sein.

• compareTo: function(choice, selectedValue): bool (optional)

  Falls multiple auf true gesetzt ist, vergleicht diese Methode die übergebenen Optionen mit der Auswahl auf deren gleichheit. Diese Methode soll true zurückgeben, bei allen Optionen die gleich der Auswahl sind, ansonsten false.

  Wird die Methode nicht gesetzt, während multiple auf true ist, kann es zu undefinierten Verhalten kommen.

• showSearchBar: bool (default: true, optional)

  Anzeige der Suchleiste steuern.

• showResetButton: bool (default: true, optional)

  Anzeige des Reset-Buttons steuern.

• className string (optional)

  Klassen-Bezeichner für das äußerste Element.

• valueFieldClassName string (optional)

  Klassen-Bezeichner für das Element zur Anzeige der Ausgewählten Werte.

• filterChoice: function(any: choice, string: searchString): bool (optional)

  Zur Client-Seitigen Filterung der Choices anhand der Such-Eingabe (searchString).

• onSearchStringChange function(string: searchString): void (optional)

  Callback zur Nachverfolgung, wenn sich die Sucheingabe ändert.

• onOpenMenu function (optional)

  Callback zur Nachverfolgung, wenn sich das Menü offnet.

• onCloseMenu function (optional)

  Callback zur Nachverfolgung, wenn sich das Menü schließt.

• valueLabelComponent: function|React.Component (optional)

  Komponente zur Anzeige der Auswahl-Werte. Muss bei der Nutzung von Objekten oder anderen Datentypen als Value-Werte überschrieben werden.

• placeholderComponent: function|React.Component|null (optional)

  Platzhalter-Komponente.

• placeholderProps: object (optional)

  Properties der Placeholder-Komponente.

  HINWEIS: Wenn die Standard-Komponente genutzt wird, kann der Platzhalter-Text über placeholderProps: { text: "Eigener Placeholder" } überschrieben werden.

  Callback zur Nachverfolgung, wenn sich das Menü schließt.

• choiceListComponent: function|React.Component (optional)

  Komponente zur Anzeige der Auswahl-Optionen (Liste). Der Komponente stehen u.a. folgende props zur Verfügung:

  • choices: array
  • toggleChoice: function(choice, bool: closeMenu): bool
  • showResetButton bool
  • isChoiceSelected bool
  • isChoiceActive bool

• choiceListProps: object (optional)

  Properties der choiceListComponent-Komponente.

• searchBarComponent: function|React.Component (optional)

  Komponente zur Anzeige der Suchleiste.

• searchBarProps: object (optional)

  Properties der searchBarComponent-Komponente.

• footerComponent: function|React.Component (optional)

  Footer-Komponente in dem Auswahl-Menü.

• footerProps: object (optional)

  Properties der footerComponent-Komponente.

AsyncSelect

Diese Komponente kapselt die select-Komponente und ermöglicht die asynchrone Abfrage von Ergebnissen:

import React from 'react';
import {createRoot} from "react-dom/client";

import {AsyncSelect} from '@boewa-software/react-select';

// target ist das DOM-Element, für das die React-Komponente eingesetzt wird
const target = getElementById('my-target');

const urlGenerator = (searchString) => `/my-api-route?search=${searchString}`;

const root = createRoot(target);
root.render(<AsyncSelect generateRequestUrl={urlGenerator} />);

Attribute

Die AsyncSelect-Komponente unterstützt abgesehen von choices alle Konfigurations-Attribute wie auch das select. Außerdem gibt es die folgenden zusätzlichen Attribute:

• generateRequestUrl: function(string: searchString): string

  Generator-Methode zur Generierung des Pfads für die Abfrage der Suchergebnisse je nach Eingabe im Suchfeld.

• responseToChoices: function(response): array (optional)

  Callback-Methode zur Generierung der Auswahl-Elemente aus der Antwort vom Server.

• intialChoices: array (optional)

  Initiale Auswahl-Optionen

• triggerRequestTimeout int (default: 500, optional)

  Wartezeit bei der Eingabe eines Suchbegriffs in Millisekunden, bis die Abfrage ausgeführt wird.

• clearOnRequestStart bool (default: true, optional)

  Flag, ob die aktuellen Optionen bereits beim Abschicken der Such-Anfrage resettet werden sollen.

• clearOnMenuOpen bool (default: false, optional)

  Zusätzliches Flag was steuert ob beim Öffnen des Menüs eine neue Suchanfrage gesendet werden soll.
  Dieses Flag wird als Vorschlag verwendet. Das Menü kann also eine Suchanfrage starten,
  auch wenn dieser Parameter auf false gesetzt ist, wie z.B. für einen initialen Request,
  oder wenn sich der Suchstring ändert. Andersherum, falls dieses prop auf true gesetzt wird,
  wird die Liste immer neu geladen.

Beispiele

• Einfaches Select
• Filterung der Listenelemente bei der Eingabe
• Objekte statt einfache Werte
• Asynchrone Abfrage der Ergebnisse
• Elemente innerhalb des Selects erstellen
• Mehrere Elemente auswählen