Zum Hauptinhalt springen

Assistent

Assistent in Storybook
Warning: Die Verwendung von Metadaten wurde verworfen. Sie können die assistentenbezogenen Komponenten zwar weiterhin mithilfe von Metadaten definieren, es wird jedoch empfohlen, stattdessen JSX zu verwenden.

Beispiele​

Beispiel eines Assistenten​

Dieses Beispiel zeigt eine einfache Assistentenkomponente mit den folgenden Funktionen:

  • Drei verschiedene Registerkarten
  • Navigation mit den Schaltflächen Weiter und Zurück
  • Validierung der Daten vor dem Verlassen der ersten Seite
  • Eine Abbruchoption, die den Benutzer zur zweiten Seite weiterleitet
  • Ein einfacher Fortschrittsbalken

In den folgenden Abschnitten werden die verschiedenen Schritte zum Definieren eines einfachen Assistenten mit den Komponenten aus dem Paket @jutro/wizard-next erläutert.

Für die Implementierung des Assistenten sind erforderlich:

  1. Definition der verschiedenen Assistentenseiten, die angezeigt werden können
  2. Definition des Assistentenlayouts: wie der Assistent angezeigt wird, einschließlich Messpunktalternativen
  3. Definition der benutzerdefinierten Elemente wie Aktionsleiste und Fortschrittsanzeige
  4. Definition der Assistentenschritte: Routen und Alternativen, z. B. wohin der Benutzer nach Abschluss eines Schrittes geleitet wird
  5. Die Zusammensetzung des Assistenten unter Verwendung aller zuvor definierten Elemente

1. Definieren der Assistentenseiten​

Das Definieren einer Wrapper-Komponente ist der empfohlene Ansatz für die Definition der Assistentenseiten. Jeder Assistentenschritt muss auf eine Komponente verweisen, die WizardPage entweder umschließt oder erweitert.

Das folgende Beispiel zeigt, wie die Seitenkomponenten für den oben genannten Assistenten erstellt werden.

import { useState } from 'react';
import { WizardPage } from '@jutro/wizard-next';
import { Checkbox } from '@jutro/components';
import { useLocation } from 'react-router-dom';

const TheFirstPage = ({ id, wizardPageProps }) => {
  const location = useLocation();
  const [valid, setValid] = useState(false);
  const [stateMessages, setStateMessages] = useState(null);
  const firstStepCheckboxChanged = (e, value) => {
    setValid(value);
  };
  const wizardPageOnNext = () => {
    if (!valid) {
      setStateMessages({
        error: ['Select this checkbox to go to the next page'],
      });
    }
    // if false is returned, the default next event does not continue
    return valid;
  };

  return (
    <WizardPage
      id={id}
      {...wizardPageProps}
      onNext={wizardPageOnNext}
      location={location}
      title="First page">
      <span>Here you can add your content</span>
      <Checkbox
        label="This is mandatory to continue"
        required={true}
        stateMessages={stateMessages}
        onChange={firstStepCheckboxChanged}
      />
    </WizardPage>
  );
};

const AnotherWizardPage = ({ id, wizardPageProps }) => {
  const location = useLocation();
  return (
    <WizardPage
      id={id}
      {...wizardPageProps}
      location={location}
      title="Second page">
      <span>Another wizard page</span>
    </WizardPage>
  );
};

const LastWizardPage = ({ id, wizardPageProps }) => {
  const location = useLocation();
  return (
    <WizardPage
      id={id}
      {...wizardPageProps}
      location={location}
      title="The last page">
      <span>The last wizard page</span>
    </WizardPage>
  );
};

Neben der Seitendefinition enthält das Beispiel einen Validierungsmechanismus für die erste Seite, der im Falle ungültiger Daten die Weiterleitung zur nächsten Seite verhindert.

2. Definieren des Layouts​

Definieren Sie die Seitenstruktur des Assistenten für die verschiedenen Messpunkte.

const layout = {
  desktop: { colStart: 1, colSpan: 12 },
  tablet: { colStart: 1, colSpan: 10 },
  phone: { colStart: 1, colSpan: 6 },
};

3. Definieren benutzerdefinierter Elemente​

In diesem Beispiel werden Komponenten aus der Basiskonfiguration verwendet. Weitere Informationen zu benutzerdefinierten Implementierungsreferenzen finden Sie in den Abschnitten Anpassung des Fortschrittsbalkens und Anpassung der Aktionsleiste.

4. Definieren der Schritte des Assistenten​

Sie müssen für jeden Schritt die entsprechende Route und die zugewiesene WizardPage-Komponente angeben.

const steps = [
  {
    id: 'wizard.firstpage',
    route: 'firstpage',
    title: 'First page',
    component: TheFirstPage,
  },
  {
    id: 'wizard.secondpage',
    route: 'secondpage',
    title: 'Second page',
    component: AnotherWizardPage,
  },
  {
    id: 'wizard.lastpage',
    route: 'lastpage',
    title: 'Last page',
    component: LastWizardPage,
  },
];

5. Erstellen des Assistenten​

Führen Sie alle bisher definierten Elemente zusammen, um den Assistenten zu erstellen.

Die Option Abbrechen wird durch Definieren einer cancelPath-Eigenschaft hinzugefügt, während die Schaltflächen Weiter und Zurück standardmäßig die Definitionsreihenfolge der Schritte verwenden.

import { Wizard } from '@jutro/wizard-next';
import { useLocation } from 'react-router-dom';

<Wizard
  layout={layout}
  baseRoute={'/'}
  basePath={'/'}
  location={useLocation}
  cancelPath="secondpage"
  steps={steps}
/>;

Anpassung des Fortschrittsbalkens​

Verwenden Sie renderProgressBar, um den Fortschrittsbalken zu deaktivieren oder einen eigenen Fortschrittsbalken zu erstellen.

  • Um den Fortschrittsbalken zu deaktivieren, setzen Sie renderProgressBar auf null oder false.
  • Um den Fortschrittsbalken anzupassen, setzen Sie renderProgressBar auf eine render-Eigenschaft.

Diese render-Eigenschaft erwartet eine Funktion, die einen Parameter, ein Objekt mit der basePath-Eigenschaft und ein Array der steps empfängt, die beide an den Assistenten übergeben werden.

Es folgt ein Beispiel für einen benutzerdefinierten Fortschrittsbalken, der mit dem Layout und den in den vorherigen Beispielen definierten Schritten erstellt wurde:

import { useLocation } from 'react-router-dom';
import { Wizard } from '@jutro/wizard-next';
import { StepProgressBar } from '@jutro/components';

const customProgressBar = ({ basePath, steps }) => {
  const { pathname } = useLocation(); // calc if the subroute a match
  const stepRoutes = steps.map((step) => step?.route);
  const currentStep = stepRoutes.indexOf(pathname.replace(`${basePath}/`, ''));

  const barSteps = steps.map((step) => {
    step.active = false;
    return step;
  });
  if (currentStep >= 0) barSteps[currentStep].active = true;
  return <StepProgressBar steps={barSteps} />;
};

<Wizard
  layout={layout}
  baseRoute={'/'}
  basePath={'/'}
  location={useLocation}
  cancelPath="firstpage"
  steps={steps}
  renderProgressBar={customProgressBar}
/>;

Weitere Informationen zu render-Eigenschaften finden Sie in der React-Dokumentation.

Anpassung der Aktionsleiste​

Verwenden Sie renderActionBar, um die Aktionsleiste zu deaktivieren oder eine eigene Aktionsleiste zu erstellen.

  • Um die Aktionsleiste zu deaktivieren, setzen Sie renderActionBar auf null oder false.
  • Um die Aktionsleiste anzupassen, setzen Sie renderActionBar auf eine render-Eigenschaft.

Die render-Eigenschaft ist eine Funktion, die zwei Parameter empfängt:

  1. resolvedPropsForButtons – Dazu gehören auch Routenpfade, die vom Assistenten auf der Grundlage des Ablaufs und des aktuellen Schritts berechnet werden.
  2. actionBarLayout – Die gleiche Eigenschaft wurde an den Assistenten übergeben, um das Layout der Aktionsleiste festzulegen. Wenn Sie eine benutzerdefinierte Aktionsleiste verwenden, können Sie diese Eigenschaft auf beliebige Weise verwenden, da sie direkt über den Assistenten an die Funktion der render-Eigenschaft übergeben wird.

Ein Beispiel für eine benutzerdefinierte Aktionsleiste unter Verwendung der Schritte und des Layouts aus den vorherigen Beispielen wäre:

export const WizardWithCustomActionBar = () => {
  const location = useLocation();
  const history = useHistory();

  const customActionBar = (resolvedPropsForButtons, actionBarLayout) => {
    const selectedFlexDirection =
      actionBarLayout === 'column' ? 'column' : 'row';
    return (
      <div
        style={{
          border: 'solid 1px yellow',
          display: 'flex',
          flexDirection: selectedFlexDirection,
        }}>
        {resolvedPropsForButtons.map((propForButton) =>
          ('next' == propForButton.name || 'previous' == propForButton.name) &&
          propForButton.to != undefined ? (
            <Button
              label={propForButton.name}
              fullWidth={true}
              onClick={(e, to: propForButton.to) => handleNavigation(e, to)}
            />
          ) : (
            ''
          )
        )}
      </div>
    );
  };

  const handleNavigation = (event, to) => {
    history.replace(`//${to}`);
  };

  return (
    <Wizard
      layout={layout}
      baseRoute={'/'}
      basePath={'/'}
      location={location}
      steps={steps}
      renderActionBar={customActionBar}
    />
  );
};

Wir haben die Validierung aus diesem Beispiel entfernt, aber Sie können sie in der handleNavigation-Funktion hinzufügen.