Asistente
Uso
Consulte las especificaciones de uso del asistente en la sección de patrones.
Código
Instrucción de importación
import { * } from '@jutro/wizard-next';
Jutro proporciona las funciones relacionadas con el asistente a través del paquete @jutro/wizard-next. Contiene los siguientes componentes:
WizardWizardPageWizardProgressWizardActionBarWizardPrompt
Wizard es el componente principal que une todas las piezas: la barra de progreso, los botones y las acciones asociadas a ellos, y el contenido del asistente en sus páginas. Al usar WizardProgress y WizardActionBar, puede personalizarles la apariencia, usar sus propios componentes en ellos o eliminarlos por completo.
Funciones del asistente
Las principales funciones del asistente son estas:
Indicador de progreso
Además del indicador de progreso predeterminado proporcionado, es posible utilizar uno personalizado. Esto le permite crear su propio indicador de progreso para cumplir con los requisitos de su proyecto, mientras utiliza las otras funciones del asistente de Jutro en su totalidad.
Barra de acciones
La barra de acciones administra las acciones del asistente. Admite los eventos onCancel, onFinish, onNext y onPrevious y las devoluciones de llamada asociadas se pueden personalizar utilizando JSX. Además, puede personalizar una página de terminación para cada acción. Dentro de cada acción, puede personalizar una página de terminación diferente según la respuesta.
Transiciones de página
Administra las transiciones de página, normalmente activadas por el usuario a través de la interacción de los botones de la barra de acciones. Admite next, previous y jump (por ejemplo, un usuario está en el paso 5 y la acción de salto lo lleva al paso 3).
Componente asistente
Utilice este componente para renderizar un asistente. Este componente es el contenedor principal del asistente. Renderiza rutas para los pasos especificados. Cada paso debe hacer referencia a un componente que encapsule o extienda <WizardPage. Cada componente de paso recibirá información del asistente y las rutas de navegación que se utilizarán en la renderización de la página.
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"
/>;
Propiedades del asistente
Esta es la lista de propiedades del componente Wizard. En las siguientes subsecciones encontrará información adicional de las propiedades layout y buttonProps y sus tipos previstos.
basePathobligatorio- Tipo
stringDescripciónBase path for the wizard; used when building step links.
baseRouteobligatorio- Tipo
stringDescripciónBase route for the wizard; used when building step routes.
locationobligatorio- Tipo
{}DescripciónCurrent path location, provided by react-router. See react-router props.
className- Tipo
stringDescripciónCSS class name for this component.
actionBarLayout- Tipo
'default' | 'spaceEvenly'DescripciónThe type of layout applied to action bar items:
default- keeps items with visual separation,spaceEvenly- distributes items evenly in available grid space. bodyClassName- Tipo
stringDescripciónCSS class name for the body of this component.
buttonProps- Tipo
{ cancel:{}, previous: {}, next: {}, finish: {} }DescripciónOverrides for action buttons.
callbackMap- Tipo
{onStartWizard: func, onFinishWizard: func, onCancelWizard: func,}DescripciónCallback map for the resolver.
cancelPath- Tipo
stringDescripciónPath to navigate on 'cancel'; if none provided, the 'cancel' button will not be displayed.
componentMap- Tipo
{}DescripciónComponent map for page component resolver.
finishPath- Tipo
stringDescripciónPath to navigate on 'finish'; if none provided, the 'finish' button will not be displayed.
history- Tipo
{}DescripciónReact-Router history object. See react-router props.
initialStepPath- Tipo
stringDescripciónPath to the initial step (will be appended to 'basePath'); if not provided, the first step will be displayed.
knockoutPath- Tipo
stringDescripciónPath to navigate on fail of 'next'; if none provided, no default failTo will be added to the 'next' button.
layout- Tipo
{desktop: layoutShape, tablet: layoutShape, phoneWide: layoutShape, phone: layoutShape}DescripciónObject to override page layout.
match- Tipo
{}DescripciónReact-Router match object. See react-router props.
onCancel- Tipo
string | funcDescripciónCallback to invoke when the 'cancel' button is clicked; returns true, false or a promise.
onFinish- Tipo
string | funcDescripciónCallback to invoke when the 'finish' button is clicked; returns true, false or a promise.
onStart- Tipo
string | funcDescripciónCallback to trigger when the Wizard mounts.
onWizardEvent- Tipo
func(info, eventName)DescripciónThe function(info, eventName) called when a page loads (invoked by WizardPage).
renderActionBar- Tipo
func | booleanDescripciónCallback to render the action bar, or hide/show it.
renderNotFound- Tipo
funcDescripciónCallback to render 'not found' content; if not provided, nothing will be rendered if a path is not found.
renderProgressBar- Tipo
funcDescripciónCallback to render a progress bar, or hide/show it.
staticContext- Tipo
{}DescripciónReact-Router static context.
steps- Tipo
{ id: string, route: string, title: string, , component: React.Node }[]DescripciónArray of steps of the wizard.
subRoutes- Tipo
{ id: string, route: string, title: string, , component: React.Node }[]DescripciónArray of routes for subwizards. If a subroute matches the current location a subwizard is active otherwise the outer wizard is active.
Composición y disposición del asistente
El asistente utiliza una estructura de cuadrícula derivada del componente Layout. También puede pasar objetos de composición y disposición personalizados para computadoras de escritorio, tablets y teléfonos a fin de personalizar la composición y disposición del asistente.
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>
);
Propiedad de disposición y composición
className- Tipo
stringDescripciónCSS class name for this component.
children- Tipo
ReactNode (preferably `GridItem`)DescripciónThe content to be displayed in the page.
id- Tipo
stringDescripciónUnique identifier for the component.
layout- Tipo
{desktop?: LayoutShape, tablet?: LayoutShape, phoneWide?: LayoutShape, phone?: LayoutShape,}colSpan- Tipo
number | stringDescripciónSpecifies how many columns an element will span across.
colStart- Tipo
number | stringDescripciónDefine column to start.
columns- Tipo
any[]DescripciónDefine explicit columns.
gap- Tipo
'auto-none' | 'small' | 'medium' | 'large'DescripciónThe gap size between rows and columns.
repeat- Tipo
'auto-fit' | 'auto-fill' | numberDescripciónAmount of columns to repeat.
DescripciónOverride the default device layout:
desktop,tablet,phoneWideandphone, all of typeLayoutShape.
Propiedades LayoutShape
El objeto LayoutShape se utiliza en la propiedad layout para definir la composición y disposición del asistente para cada uno de los posibles puntos de interrupción.
colSpan- Tipo
string | numberDescripciónspecifies how many columns an element will span across.
colStart- Tipo
string | numberDescripcióndefine column to start from.
columns- Tipo
string[] | number[]Descripcióndefine explicit columns.
gap- Tipo
'none', 'small', 'medium', 'large'DescripciónGap between rows and columns.
repeat- Tipo
'auto-fit' | 'auto-fill' | number | stringDescripciónRepeat columns patterns.
Propiedad buttonProps
Se pasan buttonProps a los botones de la barra de acciones. Esto incluye cancel, previous, next y finish. Se pueden usar para personalizar la apariencia o el comportamiento de los botones predeterminados Wizard (o WizardPage).
Puede pasar propiedades de botón tanto a Wizard como a WizardPage.
Si establece buttonProps en el componente asistente, invalida los valores predeterminados de los botones de la barra de acciones para todo el flujo del asistente.
Por ejemplo, el asistente tendrá un botón next con fullWidth establecido en true:
<Wizard
buttonProps={{
next: {
fullWidth: true,
},
}}
/>
Si establece buttonProps en un paso del asistente, invalida los valores de los botones de la barra de acciones de ese paso.
Si continuamos con el ejemplo anterior, este paso del flujo del asistente tendría un botón next con fullWidth establecido en false, lo que sobrescribiría el valor establecido al nivel del asistente para este paso en particular.
<WizardPage
buttonProps={{
// overrides of default button props, these props will have priority over the buttonProps override from the wizard.
next: {
fullWidth: false,
},
}}
/>
Propiedades buttonProps
className- Tipo
stringDescripciónCSS class name for this component.
children- Tipo
React.Node | IntlMessageShape | { pathname?: IntlMessageShape; hash?: IntlMessageShape }DescripciónThe children elements to render inside of the Button.
disabled- Tipo
booleanDescripciónIf
truethis button is disabled. failToMessage- Tipo
stringDescripciónThe message shown when the promise is rejected; shown if 'failTo' is not provided.
fullWidth- Tipo
booleanDescripciónIf
true, the button expands to the available width. icon- Tipo
string | IconDescripciónAn Icon component to render on the component. The value must be an
Iconcomponent or the icon's name. For example,CheckIconor'gw-check'. iconClassName- Tipo
stringDescripciónCSS class name for the icon.
iconPosition- Tipo
left | rightDescripciónWhere the icon is placed relative to the text.
id- Tipo
stringDescripciónUnique identifier for the component.
message- TipoDescripción
The message shown when executing the trigger/promise.
size- Tipo
small | mediumDescripciónAllows you to select the smaller or larger variant.
to- Tipo
IntlMessageShape | IntlRouterLocationDescripciónThe destination path when the promise is resolved; can be an object like
<Link to>. toMessage- Tipo
stringDescripciónThe message shown when the promise is resolved; shown if 'to' is not provided.
Componente página del asistente
El componente WizardPage define el contenido y los eventos para un paso específico del asistente.
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>
);
};
Propiedades de WizardPage
childrenobligatorio- Tipo
nodeDescripciónThe content to be displayed in the page.
idobligatorio- Tipo
stringDescripciónUnique identifier for the component.
locationobligatorio- Tipo
objectDescripciónThe location object with pathname of current URL. Usually provided from the location.pathname prop passed from the router.
className- Tipo
stringDescripciónCSS class name for this component.
buttonProps- Tipo
objectDescripciónOverrides for action buttons.
headerClass- Tipo
stringDescripciónCSS class passed to wizard page header.
knockoutPath- Tipo
stringDescripciónPath to navigate on fail of 'next'; if none is provided, no default
failTowill be added to the 'next' button'. onLoad- Tipo
functionDescripciónThe callback to invoke when page is loaded; returns true, false or a promise.
onNext- Tipo
functionDescripciónThe callback to invoke when the 'next' button is clicked; returns true, false or a promise.
onPageEventInfo- Tipo
functionDescripciónThe callback to get page event info to send with a wizard event.
onPrevious- Tipo
functionDescripciónCallback to invoke when the 'back' button is clicked; returns true, false or a promise.
pageEventInfo- Tipo
function | objectDescripciónObject or callback to get page event info to send with a wizard event.
panelClassName- Tipo
stringDescripciónAdditional class name for the panel.
renderHeader- Tipo
functionDescripciónFunction which renders a custom panel header element.
renderPanel- Tipo
functionDescripciónThe callback to the render panel method; if null then renders without a panel.
renderSubTitle- Tipo
functionDescripciónFunction to render a custom subTitle.
renderTitle- Tipo
functionDescripciónFunction to render a custom title.
resolveCallbackMap- Tipo
objectDescripciónCallback map for the resolver.
subTitle- Descripción
Default panel subtitle expression.
title- Descripción
Default panel title expression.
Aspectos que deben tenerse en cuenta sobre WizardPage y referencias
-
Devoluciones de llamada de la página del asistente:
onNext,onLoadyonPrevious. También es posible mostrar mensajes de confirmación cuando el usuario intente volver a una página anterior o desee cancelar el asistente. -
Consulte la sección Propiedades de los botones para obtener más información sobre placementOptions de
buttonProps. -
Para obtener más detalles sobre las propiedades de renderización, consulte las secciones Personalización de la barra de acciones y Personalización de la barra de progreso.
Componente barra de progreso del asistente
Hay un indicador de progreso predeterminado que puede personalizar, o bien, puede proporcionar un componente personalizado a través de la propiedad de función de renderización.
El indicador de progreso predeterminado se gestiona a través del componente WizardProgress. Depende del componente SimpleProgressBar.
Toda la lógica del componente WizardProgress se basa en la información proporcionada por el Wizard cuando está incrustado. Por ejemplo, la lista de pasos se extrae del contexto del asistente.
Consulte la sección Personalización de la barra de progreso para obtener más información.
Propiedades de WizardProgress
basePath- Tipo
stringDescripciónPath to be used when composing the steps URLs.
location- Tipo
'none' | 'small' | 'medium' | 'large'DescripciónTo look for matching subroutes.
progressBarClassNameobsoleto- Tipo
stringDescripciónClass to override progress bar step styles.
Barra de acciones del asistente
El componente WizardActionBar proporciona la funcionalidad predeterminada para mostrar y manejar las diferentes opciones disponibles en el asistente. Genera y renderiza el WizardButton a partir de acciones de pasada mediante propiedades. Combina la acción con propiedades predeterminadas para cada botón; las propiedades predeterminadas se sobrescriben cuando se proporcionan en acciones.
A continuación, se muestra un ejemplo que define lo que sucede cuando el usuario hace clic en el botón Cancelar o Siguiente:
import { WizardActionBar } from '@jutro/wizard-next';
const actions = [
{name: 'cancel', to: '/'},
{name: 'next', to: '/wizard/test/step2'}
]
<WizardActionBar actions={actions}/>
Propiedades de WizardActionBar
actionsobligatorio- Tipo
[]DescripciónThe list of actions to be rendered in the <WizardActionBar>.
className- Tipo
stringDescripciónCSS class name for this component.
layout- Tipo
'default' | 'spaceEvenly' | 'center'DescripciónType 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.
Indicaciones del asistente
Proporciona un mecanismo conveniente para dar indicaciones en el contexto de un asistente. Permite condiciones e indicaciones separadas para las ventanas “anterior” y “cancelar”.
import { <WizardPrompt } from '@jutro/wizard-next';
<WizardPrompt
cancelPrompt={{when: wizardChanged, message: 'Want to cancel?'}}
previousPrompt={{when: dataChanged, message: 'Want to go back?'}}
/>
Propiedades de WizardPrompt
basePath- Tipo
stringDescripciónPath to be used when composing the steps URLs.
previousPrompt- Tipo
{when: boolean, title: string, message: string }DescripciónProperties for the 'previous' prompt; contains 'when', 'title' and 'message'.
cancelPromptobsoleto- Tipo
{when: boolean, title: string, message: string }DescripciónProperties for the 'cancel' prompt; contains 'when', 'title' and 'message'.
Comportamientos personalizados del asistente
Cómo impedir la navegación
Si la función pasada a las propiedades onCancel, onNext o onPrevious devuelve false, la acción se interrumpe, el usuario no es redirigido a la ruta correspondiente y, en consecuencia, permanece en el paso actual.
Ejemplos
Ejemplo de asistente
En este ejemplo, se muestra el componente asistente simple con las siguientes características:
- Tres pestañas diferentes.
- Navegación mediante los botones Siguiente y Anterior.
- Validación de datos antes de salir de la primera página.
- Una opción para cancelar que redirige al usuario a la segunda página.
- Una barra de progreso simple.
En las siguientes secciones, se explican los diferentes pasos para definir un asistente básico mediante los componentes del paquete @jutro/wizard-next.
La implementación del asistente requiere lo siguiente:
- Definición de las diferentes páginas del asistente que se puedan visualizar.
- Definición de la composición y disposición del asistente: cómo se muestra el asistente, incluidas las alternativas de punto de interrupción.
- Definición de los elementos personalizados, como la barra de acciones y el indicador de progreso.
- Definición de los pasos del asistente: rutas y alternativas, por ejemplo, a dónde se dirige al usuario después de completar un paso.
- La composición del asistente utilizando todos los elementos previamente definidos.
1. Definición de las páginas del asistente
La definición de un componente encapsulador es el método recomendado para la definición de las páginas del asistente. Cada paso del asistente debe hacer referencia a un componente que encapsule o extienda WizardPage.
En el siguiente ejemplo se muestra cómo crear los componentes de página para el asistente anterior.
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>
);
};
Además de la definición de la página, el ejemplo tiene un mecanismo de validación implementado para la primera página que, en caso de datos no válidos, evita la transición a la página siguiente.
2. Definición de la composición y la disposición
Defina la estructura de la página del asistente para los diferentes puntos de interrupción.
const layout = {
desktop: { colStart: 1, colSpan: 12 },
tablet: { colStart: 1, colSpan: 10 },
phone: { colStart: 1, colSpan: 6 },
};
3. Definición de cualquier elemento personalizado
En este ejemplo, usamos componentes de la configuración base. Consulte las secciones Personalización de la barra de progreso y Personalización de la barra de acciones para obtener referencias de implementación personalizadas.
4. Definición de los pasos del asistente
Debe especificar la ruta correspondiente y el componente asignado WizardPage para cada paso.
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. Composición del asistente
Reúna todos los elementos definidos hasta el momento para componer el asistente.
La opción Cancelar se agrega definiendo una propiedad cancelPath, mientras que los botones Siguiente y Anterior utilizan el orden de definición de los pasos predeterminado.
import { Wizard } from '@jutro/wizard-next';
import { useLocation } from 'react-router-dom';
<Wizard
layout={layout}
baseRoute={'/'}
basePath={'/'}
location={useLocation}
cancelPath="secondpage"
steps={steps}
/>;
Personalización de la barra de progreso
Utilice renderProgressBar para desactivar la barra de progreso o renderizar una barra de progreso personalizada.
- Para desactivar la barra de progreso, establezca
renderProgressBarennullofalse. - Para personalizar la barra de progreso, establezca
renderProgressBaren una propiedad de renderización.
Esta propiedad de renderización prevé una función que recibe un parámetro, un objeto con la propiedad basePath y una matriz de steps, los cuales se pasan al asistente.
A continuación, se muestra un ejemplo de una barra de progreso personalizada realizada con la composición y disposición y los pasos definidos en los ejemplos anteriores:
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}
/>;
Para obtener más información acerca de las propiedades de renderización, consulte los documentos de React.
Personalización de la barra de acciones
Utilice renderActionBar para deshabilitar la barra de acciones o renderizar una barra de acciones personalizada.
- Para deshabilitar la barra de acciones, establezca
renderActionBarennullofalse. - Para personalizar la barra de acciones, establezca
renderActionBaren una propiedad de renderización.
La propiedad de renderización es una función que recibe dos parámetros:
resolvedPropsForButtons, que incluye rutas que el asistente calcula en función del flujo y el paso actual.actionBarLayout, la misma propiedad pasada al asistente para establecer la composición y disposición de la barra de acciones. Si utiliza una barra de acciones personalizada, puede usar esta propiedad de la forma que desee, ya que se pasa directamente a través del asistente a la función de la propiedad de renderización.
Este sería un ejemplo de una barra de acciones personalizada, que utiliza los pasos y la composición y disposición de ejemplos anteriores:
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}
/>
);
};
Hemos eliminado la validación de este ejemplo, pero puede agregarla en la función handleNavigation.
Registro de cambios
10.9.0
-
Se introdujo una nueva característica de opción de participación que desactiva la publicación automática de eventos para el componente Wizard. Puede habilitar esta función agregando
JUTRO_DISABLE_AUTO_EVENTS_PUBLISHING=trueal archivo.enven la raíz de su aplicación de Jutro. Cuando esta acción está habilitada, los componentes heredados ya no publican eventos de forma predeterminada. Para obtener más información sobre los eventos y cómo configurar nuevos, consulte la documentación sobre eventos.
10.2.0
- La propiedad
progressBarClassNamedel componenteWizardProgressquedó obsoleta.
10.0.0
- Se retiró de servicio el componente
ScrollToErrorque estaba expuesto a través del paquete@jutro/wizard-next. - Quedó obsoleto el uso de metadatos para definir la composición y la configuración de
Wizard.