Modales Fenster

Modales Fenster in Storybook

Verwendung

Überblick

Modale lenken die Aufmerksamkeit des Benutzers über ein Fenster, das oben auf der Seite angezeigt wird, auf eine Aufgabe. Sie präsentieren wichtige Informationen, die eine Benutzereingabe erfordern können oder auch nicht, bevor der Workflow fortgesetzt wird.

Modale unterbrechen den Workflow des Benutzers. Modale deaktivieren den Hauptinhaltsbereich und verhindern, dass der Benutzer zu seinem vorherigen Workflow zurückkehrt, bis er die modale Aufgabe abgeschlossen oder das Modal geschlossen hat.

Modale werden meist für Fehlerhinweise verwendet (ursprünglicher Zweck), können aber auch für Warnungen, Bestätigungen und benutzerdefinierte Anforderungen genutzt werden.

Eine ausführliche Orientierungshilfe zur Verwendung der Modalkomponente finden Sie im folgenden Entscheidungsbaum für UI-Komponenten.

Zu verwenden

• Zur Anforderung wichtiger Eingaben oder Entscheidungen, die den Benutzer daran hindern, einen Prozess oder eine Aufgabe fortzusetzen.
• Zur Übermittlung dringender Informationen, kritischer Fehler oder wichtiger Warnungen, die die sofortige Aufmerksamkeit und Bestätigung des Benutzers erfordern.
• Zur Bestätigung bedeutsamer Benutzeraktionen, insbesondere solcher mit erheblichen Auswirkungen (z. B. Löschen von Daten).

Nicht zu verwenden

• Für nicht kritische Meldungen, Statusaktualisierungen oder Informationen, die keine unmittelbare Benutzeraktion oder Unterbrechung des Workflows erfordern.
• Zur Unterbrechung von anspruchsvollen oder komplizierten Benutzeraufgaben (z. B. ein Checkout-Prozess oder eine komplexe Dateneingabe), es sei denn, dies ist unbedingt erforderlich, um einen kritischen Fehler zu verhindern.
• Wenn die Entscheidung oder Aufgabe im Modal den Zugriff von Benutzern auf andere Informationen auf der Seite oder an anderer Stelle in der Anwendung erforderlich macht.

Formatierung

Aufbau

Modale haben eine Kopfzeile, einen Hauptteil und eine Fußzeile.

1. Kopfzeile: Die Kopfzeile enthält den Titel des modalen Fensters und teilt dessen Zweck mit.
2. Hauptteil: Enthält unterstützenden Text, der notwendig ist, damit der Benutzer die Aufgabe des Modals erfüllen kann. Modale können auch andere Komponenten innerhalb des Hauptteils enthalten.
3. Schaltflächen: Die wichtigsten Aktionen, die der Benutzer benötigt, um die Aufgabe des Modals abzuschließen oder abzubrechen.
4. Schließen-Symbol: Schließt das modale Fenster, ohne Daten zu übermitteln.
5. Overlay: Deckt den Hauptseiteninhalt ab und macht ihn inaktiv, bis die Aufgabe des Modals abgeschlossen oder verworfen wurde.

Fehler

Fehlermeldungen müssen den Richtlinien für Fehlermeldungen entsprechen. Weitere Informationen finden Sie im folgenden Abschnitt:

• Validierungs- und Benachrichtigungsmechanismen
• Schreiben effektiver Meldungen

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.

Kopfzeile

• Kopfzeilen müssen eine einzige, klare Frage stellen oder eine einzige prägnante Botschaft vermitteln. Wenn das Modal informativ oder lehrreich ist und keine Entscheidung erfordert, kann der Titel eine Aussage darstellen.
• Vermeiden Sie die Verwendung von „Sind Sie sicher“ als Titel eines Modals. Er ist vage und Benutzer wissen möglicherweise nicht, was die eigentliche Frage ist. Stellen Sie den Benutzern stattdessen die Frage, die mit einer bestimmten Aktion beantwortet werden soll, z. B. „Zahlung senden?“

Hauptteil

• Der Text im Hauptteil muss alle Konsequenzen aufzeigen und die Optionen in einfachen Worten erklären.
• Stellen Sie sicher, dass das Modal alle Informationen enthält, die für eine einzige Entscheidung erforderlich sind.
• Vermeiden Sie Informationen, die mit der Entscheidung nichts zu tun haben, oder komplizierte Beschreibungen von seltenen Situationen.
• Verwenden Sie bei informativen Modalen den richtigen Ton, der der Art der Nachricht entspricht. Wenn zum Beispiel ein Fehler vermieden werden soll, muss der UX-Text klar und einfach sein.

Schaltflächen

• Der Text der primären Schaltfläche muss eine eindeutige Aktion angeben, die die in der Kopfzeile gestellte Frage beantwortet.
• Achten Sie darauf, dass in der Frage und in den Aktionen die gleichen Wörter verwendet werden. Vermeiden Sie unzusammenhängende Formulierungen. Wenn zum Beispiel in der Kopfzeile gefragt wird: „Portfolio löschen?“, muss die Handlungsaufforderung der primären Schaltfläche auch „Löschen“ lauten.
• Primäre Aktionen werden auf der rechten Seite, abweisende oder sekundäre Handlungen auf der linken Seite aufgeführt.
• Bei Modalen, die eine Entscheidung erfordern, sollten Sie Wörter verwenden, die die eigentliche Handlung beschreiben, und nicht etwas Vages wie „Ja“, „OK“ oder „Sicher“.
• Reservieren Sie „OK“ für Situationen wie Bestätigungsmodale, in denen Sie den Benutzer lediglich auffordern, die präsentierten Informationen zu bestätigen.

Dieses Modal fragt klar nach der konkreten Aktion, informiert den Benutzer über eine wichtige mögliche Konsequenz und enthält eindeutige, handlungsorientierte Schaltflächen.

Dieses Modal verwendet eine vage Frage, erwähnt keine wichtigen Konsequenzen und enthält unklare „Ja/Nein“-Schaltflächenoptionen.

Verhalten

Zustände

Wenn ein Modal ausgelöst wird, haben bestimmte Elemente wie z. B. Schaltflächen einen Status aktiv, fokussiert und schwebend.

• Fokussiert: Zeigt an, dass das Element mit der Tastatur oder der Maus hervorgehoben ist.
• Aktiv: Gibt eine Rückmeldung darüber, dass der Benutzer auf das Element klickt oder tippt.
• Schwebend: Zeigt an, dass der Benutzer den Mauszeiger über dem Element platziert hat (nur Desktop).

Wenn das Modal geschlossen wird, kehrt der Benutzer zum Inhalt der Seite und zu seinem vorherigen Workflow zurück.

Interaktionen

Maus

Durch Klicken auf das Schließen-Symbol oben rechts wird das Modal geschlossen, ohne dass die Benutzerdaten übermittelt werden.

Durch Klicken auf die primäre Aktionsschaltfläche wird die Aufgabe abgeschlossen und das Modal geschlossen.

Die sekundäre Aktion bietet dem Benutzer die Möglichkeit, sich zurückzuziehen und nichts zu unternehmen. Durch Klicken auf die sekundäre Schaltfläche wird das Modal geschlossen und der Benutzer kehrt zum vorherigen Kontext zurück.

Tastatur

Wenn sie ausgelöst wird, ist die Tabulatorfolge enthalten und der Tastaturfokus wird im Modal gehalten. Das primäre Fenster ist inaktiv und ermöglicht keine Interaktion, bis das Modal geschlossen wird.

Screenreader

Die modalen Komponenten enthalten eine WAI-ARIA role="dialog" und aria-modal="true", um unterstützenden Technologien anzuzeigen, dass das darunter liegende Fenster derzeit inaktiv ist. Die Fokusreihenfolge, die zugänglichen Namen und die programmatischen Beziehungen hängen von den jeweiligen Inhalten innerhalb der einzelnen Modale ab. Das Element mit ARIA role="dialog" enthält eine aria-labelledby- und eine aria-describedby-Referenz, die sich jeweils auf den primären Modaltitel und den Modalinhalt beziehen.

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.

Beachten Sie die WAI-ARIA Authoring Practices for Modals und überprüfen Sie dies in Ihrer Anwendung:

• Beim Auslösen wird der Tastaturfokus auf das erste fokussierbare Element innerhalb des modalen Dialogs gelegt.
• Beim Verwerfen kehrt der Tastaturfokus zu der Komponente zurück, die den modalen Dialog ausgelöst hat.
• Der Fokus sollte sich nicht außerhalb des Modals bewegen, bis es geschlossen wird.

Code

Warning: Micro Frontends

Wenn Sie die Modalkomponente in einem Micro Frontend verwenden, verwenden Sie ModalNextContext. showModal funktioniert nicht in eingebetteten Anwendungen aufgrund von Einschränkungen beim Übergeben von benutzerdefinierten React-Elementen.

ModalNext rendert die untergeordneten Komponenten eines Overlays. Es bietet die folgenden Möglichkeiten:

• Blockiert die Interaktion unterhalb des Modals
• Deaktiviert das Scrollen, wenn es geöffnet ist
• Verwaltet den Fokus gemäß den Best Practices für die Barrierefreiheit (siehe Barrierefreiheit)

Grundlegende Implementierung

import React, { useState } from 'react';
import {
  Button,
  ModalBody,
  ModalFooter,
  ModalHeader,
  ModalNext,
} from '@jutro/components';

const MyModal = ({ isOpen, onResolve }) =>
  isOpen ? (
    <ModalNext isOpen>
      <ModalHeader onClose={() => onResolve()} />
      <ModalBody>
        <p>You can put anything you want here!</p>
      </ModalBody>
      <ModalFooter>
        <Button onClick={() => onResolve('Cancel')}>Cancel</Button>
        <Button onClick={() => onResolve('OK')}>OK</Button>
        <Button onClick={() => onResolve('More')}>More options</Button>
      </ModalFooter>
    </ModalNext>
  ) : null;

export const MyComponent = () => {
  const [isOpen, setIsOpen] = useState(false);

  const handleOpen = () => setIsOpen(true);

  const handleModalResult = (result) => {
    switch (result) {
      case 'Cancel':
        alert('Cancelled');
        break;
      case 'OK':
        alert("So you're okay with this?");
        break;
      case 'More':
        alert('Your other options');
        break;

      default:
        alert('The default thing happened.');
        break;
    }
    setIsOpen(false);
  };

  const handleClose = () => {
    alert('Closed with the X button');
  };

  return (
    <div>
      <MyModal
        isOpen={isOpen}
        onResolve={handleModalResult}
      />
      <Button onClick={handleOpen}>Show Modal</Button>
    </div>
  );
};

Die einfachste Art, ein Modal anzuzeigen, besteht darin, <ModalNext> und die untergeordneten Komponenten zu importieren und sie mit Hilfe des Status in der übergeordneten Komponente anzuzeigen.

Um die Geschäftslogik zu implementieren, richten Sie einen Handler ein und übergeben ihn als onResolve. In dem obigen Beispiel lösen wir mit jeder Schaltfläche verschiedene Aktionen aus. Sie können mehrere Operationen in der Callback-Funktion ausführen und das Modal schließen, wenn Sie fertig sind.

Beachten Sie, dass <ModalHeader> einen onClose-Callback ausführt, wenn der Benutzer auf die Schaltfläche X (Schließen) klickt.

Eigenschaften

ModalNext

Eigenschaft	Typ	Beschreibung
contentLayout	{component: string, componentProps: object}, LayoutShape	Definiert das zu verwendende Layout mit der Eigenschaft „Komponente“, die entweder auf Flex oder Grid eingestellt ist, und componentProperties, um Eigenschaften für diese Layoutkomponente festzulegen.
isOpen	bool	Optionales Flag, das angibt, ob das Modal derzeit geöffnet ist
onAfterOpen	func	Callback-Funktion, die, falls vorhanden, aufgerufen wird, wenn der modale Dialog geöffnet wurde und für den Benutzer sichtbar ist
onAfterClose	func	Callback-Funktion, die, falls angegeben, aufgerufen wird, wenn der modale Dialog geschlossen und für den Benutzer ausgeblendet wurde
onRequestClose	func	Callback-Funktion, die, falls vorhanden, aufgerufen wird, wenn der modale Dialog geschlossen werden soll (entweder durch Klicken auf das Overlay oder durch Drücken von ESC)
closeTimeoutMS	number	Zahl, die die Millisekunden angibt, die vor dem Schließen des Modals gewartet werden sollen.
contentLabel	IntlMessageShape	Zeichenfolge, die angibt, wie der Inhaltscontainer für Screenreader angezeigt werden soll
overlayClassName	string	Die optionale CSS-Klasse für das Overlay für den modalen Dialog
className	string	Die optionale CSS-Klasse für den modalen Dialog
shouldFocusAfterRender	bool	Optionales Flag, das angibt, ob das Modal beim Öffnen automatisch auf sich selbst fokussieren soll
shouldCloseOnOverlayClick	bool	Bei false wird der Dialog nicht geschlossen, wenn das Overlay angeklickt wird.
shouldCloseOnEsc	bool	Optionales Flag, das angibt, ob Tastaturunterstützung zum Schließen des Modals verfügbar ist (über die ESC-Taste)
shouldReturnFocusAfterClose	bool	Optionales Flag, das angibt, ob das Modal den Fokus wieder auf das Element setzen soll, das vor seiner Anzeige den Fokus hatte.
parentSelector	func	Funktion, die aufgerufen wird, um das übergeordnete Element zu ermitteln, an das das Modal angehängt werden soll.

Die Komponente ModalNext ist die Basiskomponente, die die nachfolgenden Komponenten umhüllen sollte und einige der übergreifenden Verhaltensweisen des Modals bestimmt.

ModalHeader

Eigenschaft	Typ	Beschreibung
contentLayout	{component: string, componentProps: object}, LayoutShape	Definiert das zu verwendende Inhaltslayout mit der Eigenschaft „Komponente“, die entweder auf Flex oder Grid eingestellt ist, und componentProps, um Eigenschaften für diese Layoutkomponente festzulegen.
titleLayout	{component: string, componentProps: object}, LayoutShape	Definiert das zu verwendende Kopfzeilenlayout mit der Eigenschaft „Komponente“, die entweder auf Flex oder Grid eingestellt ist, und componentProps, um Eigenschaften für diese Layoutkomponente festzulegen.
status	success, info, warning, error	Der Status dieses Modals. Entweder ein „Erfolg“, „Info“, „Warnung“, „Fehler“. Standardmäßig kein Status
icon	string	Siehe Symbol
title	IntlMessageShape	Text zur Anzeige für den Titel
subtitle	IntlMessageShape	Text zur Anzeige für den Untertitel
onClose	func	Die Funktion, die aufgerufen wird, wenn die Schaltfläche „Schließen“ angeklickt wird. Wenn Sie diese Funktion nicht festlegen, wird das Modal keine Schaltfläche „Schließen“ (x) in der Ecke haben.

Die Komponente ModalHeader sollte verwendet werden, um den oberen Teil des Modals anzuzeigen – die Statusfarbleiste, das optionale Symbol links vom Titel und den Titel selbst.

ModalBody

Eigenschaft	Typ	Beschreibung
id	string	Dient zur Identifizierung der modalen Hauptteilkomponente.
contentLayout	{component: string, componentProps: object}, LayoutShape	Definiert das zu verwendende Layout mit der Eigenschaft „Komponente“, die entweder auf Flex oder Grid eingestellt ist, und der Eigenschaft componentProps, um Eigenschaften für diese Layoutkomponente festzulegen.
autoFocus	bool	Bewirkt, dass der Fokus beider Bereitstellung des Modals auf den Haupttext gelenkt wird. Die Standardeinstellung ist true.

Die Komponente ModalBody ist eine einfache Komponente, die dazu dient, den Inhalt des Modals zu umhüllen und sollte nach ModalHeader platziert werden

ModalFooter

Eigenschaft	Typ	Beschreibung
contentLayout	{component: string, componentProps: object}, LayoutShape	Definiert das zu verwendende Layout mit der Eigenschaft „Komponente“, die entweder auf Flex oder Grid (andernfalls wird standardmäßig ein div verwendet) eingestellt ist, und componentProperties, um Eigenschaften für diese Layoutkomponente festzulegen.

Die Komponente ModalFooter ist eine einfache Komponente, die dazu dient, den Inhalt der Fußzeile des Modals zu umschließen, und sollte als letzte Komponente platziert werden, die von ModalNext umschlossen wird. Normalerweise werden Schaltflächen in diese Komponente eingebunden, aber davon nicht eingeschränkt, wenn andere Komponenten für die Implementierung erforderlich sind.

Async-Beispiel

const MyModal = ({ isOpen, onResolve }) =>
  isOpen ? (
    <ModalNext isOpen>
      <ModalHeader onClose={() => onResolve()} />
      <ModalBody>
        <p>You can put anything you want here!</p>
      </ModalBody>
      <ModalFooter>
        <Button onClick={() => onResolve('Cancel')}>Cancel</Button>
        <Button onClick={() => onResolve('Process request')}>
          Process request
        </Button>
      </ModalFooter>
    </ModalNext>
  ) : null;

export const MyComponent = () => {
  const [isOpen, setIsOpen] = useState(false);
  const [processing, setProcessing] = useState(false);

  const handleOpen = () => setIsOpen(true);

  const processRequest = async () => {
    return new Promise((resolve) => {
      setTimeout(() => {
        alert('Request successful');
        resolve();
      }, [3000]);
    });
  };

  const handleModalResult = async (result) => {
    if (result === 'Process request') {
      if (!processing) {
        setProcessing(true);
        await processRequest();
        setProcessing(false);
        setIsOpen(false);
      }
    } else {
      setIsOpen(false);
    }
  };

  return (
    <div>
      <MyModal
        isOpen={isOpen}
        onResolve={handleModalResult}
      />
      <Button onClick={handleOpen}>Show Modal</Button>
    </div>
  );
};

ModalNextContext

ModalNextContext (Modal Provider) ist die einzige Möglichkeit, ein Modal in einem Micro Frontend zu erstellen.

import React, { useContext } from 'react';
import { ModalNextContext } from '@jutro/components';

// . . . create the callback function
const { showAlert } = useContext(ModalNextContext);

const showSomething = (msg) => {
  showAlert({
    status: 'success',
    title: messages.genericSuccessMessage,
    message: msg,
  });
};

// . . . and eventually
<button onClick={() => showSomething('Surprise!')}>
  Click here to get a surprise
</button>;

Generische Modale

Warnung

Das Warnmodal ist ein generisches Modal, das ein Modal mit einer Statusfarbe, einem optionalen Symbol, einem Titel, einer Meldung und einer Bestätigungsschaltfläche anzeigt. Die Ergebnisse des Warnmodals können ebenfalls erfasst werden (bestätigen oder schließen (als Ablehnung)).

import React, { useState, useContext } from 'react';
import { ModalNextContext } from '@jutro/components';

const AlertModalExample = () => {
  const [result, setResult] = useState(null);
  const { showAlert } = useContext(ModalNextContext);

  async function triggerAlert() {
    const results = await showAlert({
      status: 'info' /* status - 'info', 'warning', 'error', or 'success' */,
      icon: 'gw-error-outline' /* icon - optional icon class name for the icon to display to the left of the title */,
      title:
        'Test Alert' /* title - string/IntlMessageShape for the title of the alert */,
      message:
        'Just testing an Alert!' /* message - string/IntlMessageShape for the message to display within the alert */,
      confirmButtonText:
        'OK' /* confirmButtonText - string/IntlMessageShape for the text to appear on the confirm button */,
    });
    setResult(`modal result was: ${results}`);
  }

  return (
    <div>
      <button onClick={triggerAlert}>Show Alert Modal</button>
      <div>{result}</div>
    </div>
  );
};

Bestätigung

Das Bestätigungsmodal ist ein generisches Modal, das ein Modal mit einer Statusfarbe, einem optionalen Symbol, einem Titel, einer Meldung und einer Bestätigungs- und Abbruchschaltfläche anzeigt. Die Ergebnisse des Bestätigungsmodals können ebenfalls erfasst werden (bestätigen, abbrechen oder schließen (als Ablehnung)).

import React, { useState, useContext } from 'react';
import { ModalNextContext } from '@jutro/components';

const ConfirmationModalExample = () => {
  const [result, setResult] = useState(null);
  const { showConfirm } = useContext(ModalNextContext);

  async function triggerConfirmation() {
    const results = await showConfirm({
      status: 'info' /* status - 'info', 'warning', 'error', or 'success' */,
      icon: 'gw-error-outline' /* icon - optional icon class name for the icon to display to the left of the title */,
      title:
        'Test Confirm Modal' /* title - string/IntlMessageShape for the title of the confirm modal */,
      message:
        'Just testing a Confirmation Modal!' /* message - string/IntlMessageShape for the message to display within the confirm modal */,
      confirmButtonText:
        'OK' /* confirmButtonText - string/IntlMessageShape for the text to appear on the confirm button */,
      cancelButtonText:
        'Cancel' /* cancelButtonText - string/IntlMessageShape for the text to appear on the cancel button */,
    });
    setResult(`modal result was: ${results}`);
  }

  return (
    <div>
      <button onClick={triggerConfirmation}>Show Confirmation Modal</button>
      <div>{result}</div>
    </div>
  );
};

Benutzerdefinierte Modale

Benutzerdefinierte Modale können mit den Komponenten ModalNext, ModalHeader, ModalBody und ModalFooter implementiert und mit showModal aus ModalNextContext angezeigt werden, ähnlich wie oben bei den generischen Modalen.

Änderungsprotokoll

10.10.1

Für diese Komponente wurden zusätzliche Design-Token hinzugefügt.

10.9.0

• Es wurde eine neue Opt-in-Funktion eingeführt, die die automatische Ereignisveröffentlichung für die Komponente Modal deaktiviert. Sie können diese Funktion aktivieren, indem Sie der .env-Datei im Stammverzeichnis Ihrer Jutro-Anwendung JUTRO_DISABLE_AUTO_EVENTS_PUBLISHING=true hinzufügen. Wenn diese Option aktiviert ist, veröffentlichen ältere Komponenten standardmäßig keine Ereignisse mehr. Weitere Informationen zu Ereignissen und zum Einrichten neuer Ereignisse finden Sie in der Dokumentation zu Ereignissen.

icon-Eigenschaftstyp erweitert

Der Typ der Eigenschaft icon in den folgenden Komponenten wurde erweitert:

Komponente	Eigenschaft	Alter Typ	Neuer Typ
AlertModal	icon	string	string/React.ComponentType
ConfirmationModal	icon	string	string/React.ComponentType
ModalHeader	icon	string	string/React.ComponentType

Abkündigungen

Die Übergabe von string als Wert an die Eigenschaft icon wird in den folgenden Komponenten abgekündigt:

Komponente	Eigenschaft
AlertModal	icon
ConfirmationModal	icon
ModalHeader	icon