Assistant
Utilisation
Reportez-vous aux spécifications d'utilisation de l'assistant dans la section Modèles.
Code
Instruction d'importation
import { * } from '@jutro/wizard-next';
Jutro fournit les fonctionnalités liées à l'assistant via le package @jutro/wizard-next. Il contient les composants suivants :
WizardWizardPageWizardProgressWizardActionBarWizardPrompt
Wizard est le composant principal qui assemble tous les éléments : la barre de progression, les boutons et les actions qui leur sont associés, ainsi que le contenu des pages de l'assistant. Lorsque vous utilisez WizardProgress et WizardActionBar, vous pouvez personnaliser leur apparence et leur convivialité, utiliser vos propres composants ou les supprimer complètement.
Fonctionnalités de l'assistant
Les principales fonctionnalités de l'assistant sont les suivantes :
Indicateur de progression
En dehors de l'indicateur de progression par défaut fourni, il est possible d'utiliser un indicateur personnalisé. Cela vous permet de créer votre propre indicateur de progression pour répondre aux exigences de votre projet, tout en utilisant pleinement les autres fonctionnalités de l'assistant Jutro.
Barre d'actions
La barre d'actions gère les actions de l'assistant. Elle prend en charge les événements onCancel, onFinish, onNext et onPrevious, et les rappels associés peuvent être personnalisés à l'aide de JSX. De plus, vous pouvez personnaliser une page d'interruption pour chaque action. Dans chaque action, vous pouvez personnaliser une page d'interruption différente en fonction de la réponse.
Transitions de page
Gère les transitions de page, normalement déclenchées par l'utilisateur via l'interaction avec les boutons de la barre d'actions. Prend en charge next, previous et jump (par exemple, un utilisateur se trouve à l'étape 5 et l'action de saut l'amène à l'étape 3).
Composant Assistant
Utilisez ce composant pour afficher un assistant. Ce composant est le conteneur principal de l'assistant. Il affiche les routes pour les étapes spécifiées. Chaque étape doit faire référence à un composant qui englobe ou étend <WizardPage. Chaque composant d'étape recevra des informations de l'assistant et des chemins de navigation à utiliser pour l'affichage de la page.
import { Wizard } from '@jutro/wizard-next';
const steps = [
{
key: 'one',
route: 'step1',
component: PageOne,
},
{
key: 'two',
route: 'step2',
component: PageTwo,
},
{
key: 'three',
route: 'step3',
component: PageThree,
},
];
<Wizard
baseRoute="/wizard/:zipCode"
basePath="/wizard/90210"
steps={steps}
cancelPath="/home"
finishPath="/home"
/>;
Propriétés de l'assistant
Il s'agit de la liste des propriétés du composant Wizard. Dans les sous-sections suivantes, vous trouverez des informations supplémentaires sur les propriétés layout et buttonProps et leurs types attendus.
basePathobligatoire- Type
stringDescriptionBase path for the wizard; used when building step links.
baseRouteobligatoire- Type
stringDescriptionBase route for the wizard; used when building step routes.
locationobligatoire- Type
{}DescriptionCurrent path location, provided by react-router. See react-router props.
className- Type
stringDescriptionCSS class name for this component.
actionBarLayout- Type
'default' | 'spaceEvenly'DescriptionThe type of layout applied to action bar items:
default- keeps items with visual separation,spaceEvenly- distributes items evenly in available grid space. bodyClassName- Type
stringDescriptionCSS class name for the body of this component.
buttonProps- Type
{ cancel:{}, previous: {}, next: {}, finish: {} }DescriptionOverrides for action buttons.
callbackMap- Type
{onStartWizard: func, onFinishWizard: func, onCancelWizard: func,}DescriptionCallback map for the resolver.
cancelPath- Type
stringDescriptionPath to navigate on 'cancel'; if none provided, the 'cancel' button will not be displayed.
componentMap- Type
{}DescriptionComponent map for page component resolver.
finishPath- Type
stringDescriptionPath to navigate on 'finish'; if none provided, the 'finish' button will not be displayed.
history- Type
{}DescriptionReact-Router history object. See react-router props.
initialStepPath- Type
stringDescriptionPath to the initial step (will be appended to 'basePath'); if not provided, the first step will be displayed.
knockoutPath- Type
stringDescriptionPath to navigate on fail of 'next'; if none provided, no default failTo will be added to the 'next' button.
layout- Type
{desktop: layoutShape, tablet: layoutShape, phoneWide: layoutShape, phone: layoutShape}DescriptionObject to override page layout.
match- Type
{}DescriptionReact-Router match object. See react-router props.
onCancel- Type
string | funcDescriptionCallback to invoke when the 'cancel' button is clicked; returns true, false or a promise.
onFinish- Type
string | funcDescriptionCallback to invoke when the 'finish' button is clicked; returns true, false or a promise.
onStart- Type
string | funcDescriptionCallback to trigger when the Wizard mounts.
onWizardEvent- Type
func(info, eventName)DescriptionThe function(info, eventName) called when a page loads (invoked by WizardPage).
renderActionBar- Type
func | booleanDescriptionCallback to render the action bar, or hide/show it.
renderNotFound- Type
funcDescriptionCallback to render 'not found' content; if not provided, nothing will be rendered if a path is not found.
renderProgressBar- Type
funcDescriptionCallback to render a progress bar, or hide/show it.
staticContext- Type
{}DescriptionReact-Router static context.
steps- Type
{ id: string, route: string, title: string, , component: React.Node }[]DescriptionArray of steps of the wizard.
subRoutes- Type
{ id: string, route: string, title: string, , component: React.Node }[]DescriptionArray of routes for subwizards. If a subroute matches the current location a subwizard is active otherwise the outer wizard is active.
Mises en page de l'assistant
L'assistant utilise une structure de grille dérivée du composant Layout. Vous pouvez également copier des objets de mise en page personnalisés pour les ordinateurs de bureau, les tablettes et les téléphones afin de personnaliser la mise en page de l'assistant.
return (
<WizardExampleContext.Provider value={exampleContext}>
<Wizard
baseRoute={route}
layout={{
desktop: {
columns: ['1fr'],
repeat: '4',
gap: 'large',
colStart: '2',
colSpan: '1',
},
tablet: {
repeat: '4',
...
},
phone: {
repeat: '4',
...
},
}}
basePath={path}
steps={steps}
.......
/>
</WizardExampleContext.Provider>
);
Propriété de mise en page
className- Type
stringDescriptionCSS class name for this component.
children- Type
ReactNode (preferably `GridItem`)DescriptionThe content to be displayed in the page.
id- Type
stringDescriptionUnique identifier for the component.
layout- Type
{desktop?: LayoutShape, tablet?: LayoutShape, phoneWide?: LayoutShape, phone?: LayoutShape,}colSpan- Type
number | stringDescriptionSpecifies how many columns an element will span across.
colStart- Type
number | stringDescriptionDefine column to start.
columns- Type
any[]DescriptionDefine explicit columns.
gap- Type
'auto-none' | 'small' | 'medium' | 'large'DescriptionThe gap size between rows and columns.
repeat- Type
'auto-fit' | 'auto-fill' | numberDescriptionAmount of columns to repeat.
DescriptionOverride the default device layout:
desktop,tablet,phoneWideandphone, all of typeLayoutShape.
Propriétés LayoutShape
L'objet LayoutShape est utilisé dans la propriété layout pour définir la mise en page de l'assistant pour chacun des points d'arrêt possibles.
colSpan- Type
string | numberDescriptionspecifies how many columns an element will span across.
colStart- Type
string | numberDescriptiondefine column to start from.
columns- Type
string[] | number[]Descriptiondefine explicit columns.
gap- Type
'none', 'small', 'medium', 'large'DescriptionGap between rows and columns.
repeat- Type
'auto-fit' | 'auto-fill' | number | stringDescriptionRepeat columns patterns.
Propriété buttonProps
Les buttonProps sont transmises aux boutons de la barre d'actions. Cela inclut cancel, previous, next et finish. Elles peuvent être utilisées pour personnaliser l'apparence ou le comportement des boutons par défaut Wizard (ou WizardPage).
Vous pouvez transmettre des propriétés de bouton à Wizard et WizardPage.
Si vous définissez buttonProps dans le composant Assistant, vous remplacez les valeurs par défaut des boutons de la barre d'actions pour l'ensemble du flux de l'assistant.
Par exemple, l'assistant aura un bouton next avec fullWidth défini sur true :
<Wizard
buttonProps={{
next: {
fullWidth: true,
},
}}
/>
Si vous définissez buttonProps dans une étape de l'assistant, vous remplacez les valeurs des boutons de la barre d'actions pour cette étape.
Dans la continuité de l'exemple précédent, cette étape du flux de l'assistant comporterait alors un bouton next avec fullWidthdéfini sur false, remplaçant la valeur définie au niveau de l'assistant pour cette étape particulière.
<WizardPage
buttonProps={{
// overrides of default button props, these props will have priority over the buttonProps override from the wizard.
next: {
fullWidth: false,
},
}}
/>
Propriétés buttonProps
className- Type
stringDescriptionCSS class name for this component.
children- Type
React.Node | IntlMessageShape | { pathname?: IntlMessageShape; hash?: IntlMessageShape }DescriptionThe children elements to render inside of the Button.
disabled- Type
booleanDescriptionIf
truethis button is disabled. failToMessage- Type
stringDescriptionThe message shown when the promise is rejected; shown if 'failTo' is not provided.
fullWidth- Type
booleanDescriptionIf
true, the button expands to the available width. icon- Type
string | IconDescriptionAn Icon component to render on the component. The value must be an
Iconcomponent or the icon's name. For example,CheckIconor'gw-check'. iconClassName- Type
stringDescriptionCSS class name for the icon.
iconPosition- Type
left | rightDescriptionWhere the icon is placed relative to the text.
id- Type
stringDescriptionUnique identifier for the component.
message- TypeDescription
The message shown when executing the trigger/promise.
size- Type
small | mediumDescriptionAllows you to select the smaller or larger variant.
to- Type
IntlMessageShape | IntlRouterLocationDescriptionThe destination path when the promise is resolved; can be an object like
<Link to>. toMessage- Type
stringDescriptionThe message shown when the promise is resolved; shown if 'to' is not provided.
Composant de la page de l'assistant
Le composant WizardPage définit le contenu et les événements d'une étape spécifique de l'assistant.
import { WizardPage } from '@jutro/wizard-next';
import { useLocation } from 'react-router-dom';
const myWizardPage = () => {
const location = useLocation();
return (
<WizardPage
{
cancelPath="/"
finishPath="/offer"
knockoutPath="/knockoutPage"
} location={location}>
<span>Account wizard page</span>
</WizardPage>
);
};
Propriétés WizardPage
childrenobligatoire- Type
nodeDescriptionThe content to be displayed in the page.
idobligatoire- Type
stringDescriptionUnique identifier for the component.
locationobligatoire- Type
objectDescriptionThe location object with pathname of current URL. Usually provided from the location.pathname prop passed from the router.
className- Type
stringDescriptionCSS class name for this component.
buttonProps- Type
objectDescriptionOverrides for action buttons.
headerClass- Type
stringDescriptionCSS class passed to wizard page header.
knockoutPath- Type
stringDescriptionPath to navigate on fail of 'next'; if none is provided, no default
failTowill be added to the 'next' button'. onLoad- Type
functionDescriptionThe callback to invoke when page is loaded; returns true, false or a promise.
onNext- Type
functionDescriptionThe callback to invoke when the 'next' button is clicked; returns true, false or a promise.
onPageEventInfo- Type
functionDescriptionThe callback to get page event info to send with a wizard event.
onPrevious- Type
functionDescriptionCallback to invoke when the 'back' button is clicked; returns true, false or a promise.
pageEventInfo- Type
function | objectDescriptionObject or callback to get page event info to send with a wizard event.
panelClassName- Type
stringDescriptionAdditional class name for the panel.
renderHeader- Type
functionDescriptionFunction which renders a custom panel header element.
renderPanel- Type
functionDescriptionThe callback to the render panel method; if null then renders without a panel.
renderSubTitle- Type
functionDescriptionFunction to render a custom subTitle.
renderTitle- Type
functionDescriptionFunction to render a custom title.
resolveCallbackMap- Type
objectDescriptionCallback map for the resolver.
subTitle- Description
Default panel subtitle expression.
title- Description
Default panel title expression.
Considérations et références relatives à WizardPage
-
Rappels de la page de l'assistant :
onNext,onLoadetonPrevious. Vous pouvez également afficher des invites lorsque l'utilisateur tente de revenir à une page précédente ou souhaite annuler l'assistant. -
Reportez-vous à la section Propriétés des boutons pour en savoir plus sur les placementOptions
buttonProps. -
Pour en savoir plus sur les propriétés de rendu, reportez-vous aux sections Personnalisation de la barre d'actions et Personnalisation de la barre de progression.
Composant de la barre de progression de l'assistant
Il existe un indicateur de progression par défaut que vous pouvez personnaliser ou vous pouvez fournir un composant personnalisé via la propriété de la fonction de rendu.
L'indicateur de progression par défaut est géré via le composant WizardProgress. Il repose sur le composant SimpleProgressBar.
Toute la logique du composant WizardProgress est basée sur les informations fournies par Wizard où il est intégré. Par exemple, la liste des étapes est extraite du contexte de l'assistant.
Reportez-vous à la section Personnalisation de la barre de progression pour en savoir plus.
Propriétés WizardProgress
basePath- Type
stringDescriptionPath to be used when composing the steps URLs.
location- Type
'none' | 'small' | 'medium' | 'large'DescriptionTo look for matching subroutes.
progressBarClassNameobsolète- Type
stringDescriptionClass to override progress bar step styles.
Barre d'actions de l'assistant
Le composant WizardActionBar fournit la fonctionnalité par défaut pour afficher et gérer les différentes options disponibles dans l'assistant. Il génère et affiche le WizardButton à partir des actions transmises à l'aide de propriétés. Il combine l'action avec les propriétés par défaut de chaque bouton ; les propriétés par défaut sont écrasées lorsqu'elles sont fournies dans des actions.
Vous trouverez ci-dessous un exemple définissant ce qui se passe lorsque l'utilisateur clique sur le bouton Annuler ou Suivant :
import { WizardActionBar } from '@jutro/wizard-next';
const actions = [
{name: 'cancel', to: '/'},
{name: 'next', to: '/wizard/test/step2'}
]
<WizardActionBar actions={actions}/>
Propriétés WizardActionBar
actionsobligatoire- Type
[]DescriptionThe list of actions to be rendered in the <WizardActionBar>.
className- Type
stringDescriptionCSS class name for this component.
layout- Type
'default' | 'spaceEvenly' | 'center'DescriptionType of layout applied to action bar items:
default- keeps items with visual separation,spaceEvenly- distributes items evenly in available grid space,center- center button horizontally, will vertically stack multiple buttons.
Invite de l'assistant
Fournit un mécanisme d'invite pratique pour le contexte d'un assistant. Il autorise des conditions et des invites distinctes pour les fenêtres « précédent » et « annuler ».
import { <WizardPrompt } from '@jutro/wizard-next';
<WizardPrompt
cancelPrompt={{when: wizardChanged, message: 'Want to cancel?'}}
previousPrompt={{when: dataChanged, message: 'Want to go back?'}}
/>
Propriétés WizardPrompt
basePath- Type
stringDescriptionPath to be used when composing the steps URLs.
previousPrompt- Type
{when: boolean, title: string, message: string }DescriptionProperties for the 'previous' prompt; contains 'when', 'title' and 'message'.
cancelPromptobsolète- Type
{when: boolean, title: string, message: string }DescriptionProperties for the 'cancel' prompt; contains 'when', 'title' and 'message'.
Comportements personnalisés de l'assistant
Empêcher la navigation
Si la fonction transmise aux propriétés onCancel, onNext ou onPrevious renvoie false, l'action est arrêtée et l'utilisateur n'est pas redirigé vers le chemin correspondant ; il reste à l'étape en cours.
Exemples
Exemple d'assistant
Cet exemple montre un composant Assistant simple avec les fonctionnalités suivantes :
- Trois onglets différents
- Navigation à l'aide des boutons Suivant et Précédent
- Validation des données avant de quitter la première page
- Une option d'annulation qui redirige l'utilisateur vers la deuxième page
- Barre de progression simple
Les sections suivantes expliquent les différentes étapes de définition d'un assistant de base à l'aide des composants du package @jutro/wizard-next.
L'implémentation de l'assistant nécessite :
- Définition des différentes pages de l'assistant qui peuvent être affichées
- Définition de la mise en page de l'assistant : affichage de l'assistant, y compris les alternatives aux points d'arrêt
- Définition des éléments personnalisés comme la barre d'actions et l'indicateur de progression
- Définition des étapes de l'assistant : routes et alternatives, par exemple lorsque l'utilisateur est dirigé après avoir terminé une étape
- La composition de l'assistant en utilisant tous les éléments précédemment définis
1. Définir les pages de l'assistant
La définition d'un composant de wrapper est l'approche recommandée pour la définition des pages de l'assistant. Chaque étape de l'assistant doit faire référence à un composant qui englobe ou étend WizardPage.
L'exemple suivant montre comment créer les composants de page pour l'assistant précédent.
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>
);
};
Outre la définition de la page, l'exemple comporte un mécanisme de validation implémenté pour la première page qui, en cas de données non valides, empêche le passage à la page suivante.
2. Définir la mise en page
Définissez la structure des pages de l'assistant pour les différents points d'arrêt.
const layout = {
desktop: { colStart: 1, colSpan: 12 },
tablet: { colStart: 1, colSpan: 10 },
phone: { colStart: 1, colSpan: 6 },
};
3. Définir des éléments personnalisés
Dans cet exemple, nous utilisons des composants de la configuration de base. Reportez-vous aux sections Personnalisation de la barre de progression et Personnalisation de la barre d'actions pour obtenir des références à l'implémentation personnalisée.
4. Définir les étapes de l'assistant
Vous devez spécifier la route correspondante et le composant attribué WizardPage pour chaque étape.
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. Composer l'assistant
Rassemblez tous les éléments définis jusqu'à présent pour composer l'assistant.
L'option Annuler est ajoutée en définissant une propriété cancelPath, tandis que les boutons Suivant et Précédent utilisent l'ordre de définition des étapes par défaut.
import { Wizard } from '@jutro/wizard-next';
import { useLocation } from 'react-router-dom';
<Wizard
layout={layout}
baseRoute={'/'}
basePath={'/'}
location={useLocation}
cancelPath="secondpage"
steps={steps}
/>;
Personnalisation de la barre de progression
Utilisez renderProgressBar pour désactiver la barre de progression ou afficher une barre de progression personnalisée.
- Pour désactiver la barre de progression, définissez
renderProgressBarsurnulloufalse. - Pour personnaliser la barre de progression, définissez
renderProgressBarsur une propriété de rendu.
Cette propriété de rendu attend une fonction qui reçoit un paramètre, un objet avec la propriété basePath et une série des steps qui sont tous deux transmis à l'assistant.
Voici un exemple de barre de progression personnalisée réalisée à l'aide de la disposition et des étapes définies dans les exemples précédents :
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}
/>;
Pour en savoir plus sur les propriétés de rendu, reportez-vous à la documentation React.
Personnalisation de la barre d'actions
Utilisez renderActionBar pour désactiver la barre d'actions ou afficher une barre d'actions personnalisée.
- Pour désactiver la barre d'actions, définissez
renderActionBarsurnulloufalse. - Pour personnaliser la barre d'actions, définissez
renderActionBarsur une propriété de rendu.
La propriété de rendu est une fonction qui reçoit deux paramètres :
resolvedPropsForButtons: inclut les chemins d'accès qui sont calculés par l'assistant en fonction du flux et de l'étape en cours.actionBarLayout: la même propriété que celle transmise à l'assistant pour définir la disposition de la barre d'actions. Si vous utilisez une barre d'actions personnalisée, vous pouvez utiliser cette propriété comme vous le souhaitez, car elle est transmise directement par l'assistant à la fonction de propriété de rendu.
Voici un exemple de barre d'actions personnalisée, utilisant les étapes et la disposition des exemples précédents :
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}
/>
);
};
Nous avons supprimé la validation de cet exemple, mais vous pouvez l'ajouter dans la fonction handleNavigation.
Journal des modifications
10.9.0
-
Une nouvelle fonctionnalité d'opt-in a été introduite pour désactiver la publication automatique des événements pour le composant Wizard. Vous pouvez activer cette fonctionnalité en ajoutant
JUTRO_DISABLE_AUTO_EVENTS_PUBLISHING=trueau fichier.envdans la racine de votre application Jutro. Lorsque cette option est activée, les composants hérités ne publient plus d'événements par défaut. Pour en savoir plus sur les événements et sur la façon d'en créer de nouveaux, reportez-vous à la documentation relative aux événements.
10.2.0
- La propriété
progressBarClassNamedu composantWizardProgressest obsolète.
10.0.0
- Le composant
ScrollToErrorexposé via le package@jutro/wizard-nextest mis hors service. - L'utilisation des métadonnées pour définir la composition et la configuration de
Wizardest obsolète.