Rótulo: Describe el propósito de un campo de entrada.
Texto de ayuda: Proporciona contexto adicional, sugerencias o información útil para ayudar al usuario. A menudo se utiliza para explicar requisitos específicos, a fin de que se complete correctamente un campo.
Campo de entrada de teléfono: Campo mejorado que permite a los usuarios ingresar su número de teléfono. Solo acepta entradas numéricas y se formatea automáticamente.
Selector de c ódigo de país (opcional): Menú desplegable que permite la selección de códigos de país de una lista. El código tiene el prefijo con la bandera del país asociada para facilitar el reconocimiento.
En todos los aspectos del diseño de las interfaces de productos de Guidewire, utilice mayúsculas como se usan en las oraciones. No use mayúsculas en todas las palabras.
Use verbos en tiempo presente y voz activa en la mayoría de las situaciones.
Use contracciones comunes para darle al texto un tono más natural e informal (pauta correspondiente al inglés).
Use un lenguaje sencillo. Evite la jerga innecesaria y el lenguaje complejo.
Use el texto de ayuda para proporcionar orientación sobre qué ingresar y cómo hacerlo. Estos son algunos ejemplos de lo que podría incluir en el texto de ayuda:
Contexto para ayudar al usuario, por ejemplo, cómo se utilizará la información.
Sugerencias sobre qué tipo de información va dentro del campo de entrada.
Ejemplos o requisitos de formato.
Utilice el texto de ayuda solo para la información pertinente. No use texto de ayuda que simplemente repita la misma información que aparece en el rótulo.
En el texto de ayuda, use mayúsculas como se usan en las oraciones. Escriba 1 o 2 oraciones cortas y completas que terminen con un punto. Al mostrar ejemplos de formato, no es necesario que termine con un punto.
Utilice texto de ayuda para proporcionar asistencia adicional o contexto al usuario.
No use texto de ayuda que simplemente repita la misma información que aparece en el rótulo.
No coloque texto de marcador de posición en el campo de entrada de teléfono. El texto de marcador de posición sobrecarga la memoria a corto plazo de los usuarios porque desaparece una vez que se ingresa un valor. También supone una carga adicional para los usuarios con discapacidades visuales y cognitivas.
En lugar de eso, coloque sugerencias e instrucciones, incluidos ejemplos y requisitos de formato, fuera del campo.
El texto del mensaje de error indica a un usuario cómo corregir el error. En el caso del campo de entrada de teléfono, los errores a menudo están relacionados con algo que debe corregirse para la validación integrada. Por ejemplo, si el usuario no completa un campo obligatorio que solicita su número de teléfono, puede usar el texto de error para guiarlo a una solución: “Escriba su número de teléfono”.
En el texto de error, use mayúsculas como se usan en las oraciones. Escriba 1 o 2 oraciones cortas y completas que terminen con un punto.
Use el texto de error para guiar al usuario y mostrarle una solución.
No escriba mensajes de error ambiguos ni deje a los usuarios pensando cómo resolver un problema.
Utilice un asterisco (*) para indicar los campos obligatorios. El asterisco precede al rótulo del campo. Esto ayuda a los usuarios a identificar fácilmente qué campos son obligatorios escaneando solo el carácter más a la izquierda del rótulo.
Además de marcar los campos obligatorios con un asterisco, se recomienda incluir instrucciones claras en la parte superior del formulario, como “Todos los campos marcados con un asterisco son obligatorios”, para garantizar que los usuarios comprendan el significado del asterisco.
Utilice un asterisco para indicar que un campo es obligatorio.
No use un asterisco para indicar algo que sea opcional.
El campo de entrada de teléfono aparece sin valor (predeterminado), texto de marcador de posición o una entrada rellena.
Ilustración
Estado
Descripción
Sin valor (predeterminado)
Indica al usuario que no se ha ingresado ningún valor y que no hay un marcador de posición.
Marcador de posición
Indica al usuario que no se ha ingresado ningún valor. El marcador de posición aparece atenuado.
Entrada rellena
Indica al usuario que la entrada está completa con datos.
Los campos de entrada de teléfono también tienen estados interactivos para habilitado, en foco, deshabilitado, error, solo lectura y solo visualización.
Estado
Descripción
Habilitado
Indica al usuario que el elemento está habilitado para la interacción.
En foco
Indica al usuario qué elemento de la interfaz de usuario del sistema está el foco.
Deshabilitado
Indica al usuario que el valor de entrada no se puede cambiar debido a factores locales. Por ejemplo, una casilla de verificación sobre el campo de entrada debe estar marcada para acceder a este campo de entrada. El usuario puede habilitarla interactuando con la página.
Error
Indica que el usuario cometió un error de validación. El texto del error proporciona información a los usuarios para solucionarlo.
Solo lectura
Indica al usuario que el valor de entrada no se puede cambiar debido a factores externos. Por ejemplo, la falta de acceso de escritura. El usuario puede hacer algo para habilitarlo, por ejemplo, ponerse en contacto con un administrador.
Solo visualización
El estado de solo visualización se utiliza en dos casos:
Un elemento de interfaz de usuario se utiliza en el modo de visualización.
Un elemento de la interfaz de usuario se muestra en el modo de edición, pero nunca se puede editar.
El usuario puede escribir el número de teléfono seleccionando o poniendo el foco en el área de entrada de teléfono. Las entradas se adaptan al formato cuando el foco pasa a otro lugar.
Este componente de Jutro ha sido validado para cumplir con las pautas de accesibilidad de WCAG 2.2 AA en su configuración base predeterminada. Esto incluye garantizar que se cumpla lo siguiente:
La relación de contraste de los elementos textuales con respecto a su fondo es superior a 4,5:1.
El contenido no textual que debe transmitir significado (como íconos e indicadores de foco) tiene una relación de contraste de al menos 3:1 con sus colores adyacentes.
El elemento se puede operar con teclado, así como con mouse.
Se puede acceder al contenido mediante lectores de pantalla, como JAWS y VoiceOver.
El cumplimiento de los criterios de accesibilidad depende, en última instancia, de cómo se implementa y personaliza este componente. Los cambios realizados por el autor del contenido pueden afectar la accesibilidad. Para obtener más información sobre nuestro modelo de responsabilidad compartida, revise nuestra declaración completa sobre accesibilidad de Jutro.
Cuando utilice este componente en su aplicación, asegúrese de que los rótulos y las instrucciones sean significativos y concisos. Proporcione instrucciones complementarias si fuera necesario.
Note: Hay versiones obsoletas de este componente. Consulte una versión de los documentos anterior a la 10.0.x.
Asegúrese de comprender la superficie de la API de componentes del sistema de diseño, así como sus implicaciones, ventajas y desventajas. Obtenga más información en nuestra introducción a la API de componentes.
If set to true, displays the component value in plain text. Consider using readonly instead, if possible, because plain text is worse for accessibility than readonly inputs.
Optional ISO 3611-1 country codes to include with the phone number.
Descripción
Initial value of input. If value prop is specified along with this prop, this prop's value is discarded. Accepts object with phoneNumber and optionally countryCode.
Value of input. Takes precedence over initialValue. If this prop is passed, component works in controlled mode and its value will change only if this prop changes. Accepts object with phoneNumber and optionally countryCode.
Existen varias claves de traducción asociadas al componente PhoneInput, pero se pueden diferenciar en dos grupos: marcadores de posición predeterminados y nombres de países.
Nombre del país asociado al código de país específico.
Esta es la lista de códigos de país que puede usar con la clave de traducción anterior:
ac ad ae af ag ai al am ao ar as at au aw ax az ba bb be bf bg bh bi bj bl bm bn bo bq br bs bt bw by bz ca cc cd cf cg ch ci ck cl cm cn co cr cu cv cw cx cy cz de dj dk dm do dz ec ee eg eh er es et fi fj fk fm fo fr ga gb gd ge gf gg gh gi gl gm gn gp gq gr gt gu gw gy hk hn hr ht hu id ie il im in io iq ir is it je jm jo jp ke kg kh ki km kn kp kr kw ky kz la lb lc li lk lr ls lt lu lv ly ma mc md me mf mg mh mk ml mm mn mo mp mq mr ms mt mu mv mw mx my mz na nc ne nf ng ni nl no np nr nu nz om pa pe pf pg ph pk pl pm pr ps pt pw py qa re ro rs ru rw sa sb sc sd se sg sh si sj sk sl sm sn so sr ss st sv sx sy sz tc td tg th tj tk tl tm tn to tr tt tv tw tz ua ug us uy uz va vc ve vg vi vn vu wf ws xk ye yt za zm zw
Las entradas de Jutro han implementado controladores imperativos como mecanismo para proporcionar acceso a algunas características nativas comunes que podrían ser útiles para usted. Puede utilizar las siguientes características:
Establecer el foco para que usted establezca el foco del usuario en un componente específico.
Desenfocar para eliminar el foco del componente.
Desplazarse hasta el componente para poder llevar al usuario a un área específica de la página.
Estas características se proporcionan a través de la propiedad ref, que las expone de la siguiente manera:
La validación y el formato de los números de teléfono están en constante evolución para adaptarlos a las nuevas reglas definidas por cada país. PhoneNumberInput está diseñado para ser compatible con estos estándares y se actualiza para reflejar las nuevas reglas a medida que aparecen. Estas actualizaciones pueden modificar el comportamiento del componente para que admita los requisitos específicos de la regla.
Marcador de posición automático para el país seleccionado
A menos que se establezca la propiedad placeholder, PhoneNumberInput establecerá automáticamente el marcador de posición de entrada en un número de ejemplo para el país seleccionado.
Cuando se ingresa el código de país en la entrada de número de teléfono, se lo utilizará automáticamente para establecer el valor del selector de país y el código se eliminará de la entrada del número. Si se utiliza un código no válido, no se aplicará el cambio automático.
Aunque usted es responsable del manejo de los errores, el componente PhoneNumberInput tiene ciertos mecanismos internos de validación y transformación, y sus resultados están disponibles para que usted asista el proceso de validación.
El evento onChange proporciona un tercer parámetro con el resultado de la validación realizada, un objeto que contiene un valor numérico errorCode que identifica el problema para que pueda asignarlo a un mensaje de error personalizado.
La lógica de validación errorCode se realiza pasando el código a la biblioteca intl-tel-input, que se puede actualizar de forma independiente.
Este es el resumen de los códigos de error:
Código
Tipo de error
-99
Error desconocido
-1
Número de teléfono no válido para el país seleccionado
1
Código de país no válido
2
El número de teléfono es demasiado corto
3
El número de teléfono es demasiado largo
4
Solo se permite un número local
5
Longitud no válida
Consulte la sección Ejemplos para ver el código de ejemplo.
Aunque algunos componentes de Jutro pueden proporcionar características complementarias o una función de ayuda para facilitar el proceso de validación, es su responsabilidad, como desarrollador, manejar la validación de cualquier entrada del usuario (con o sin ayudantes complementarios) y decidir qué mensajes de error se mostrarán.
Los componentes de Jutro se comportan en función de la implementación del desarrollador.
¿Cuándo se muestran los mensajes de error?
Los mensajes de error solo se muestran cuando los pasa al componente a través de la propiedad stateMessages. Esta propiedad recibe un objeto con el siguiente contenido:
El componente muestra cada mensaje de error proporcionado en el mismo orden que en la matriz.
¿Cuándo se produce la validación?
Esta decisión es suya, en calidad de desarrollador. Dado que los componentes no determinan cuándo se realiza la validación ni cuándo se debe mostrar el error, debe implementar la lógica para manejarla de acuerdo con los requisitos del proyecto, por ejemplo, mientras el usuario edita el contenido, cuando el componente pierde el foco y en el envío de formularios.
Aunque no es necesario pasar un código de país a PhoneNumberInput, el componente no se comportará como una entrada de número de teléfono sin un código de país. Existen 3 opciones diferentes para proporcionarlo:
Con la propiedad countries. Puede pasar un único código de país ISO que se utilizará como predeterminado y se mostrará el código numérico del país.
<PhoneNumberInput label="Phone input component with US set as default" countries={['US']} />
Con la propiedad initialValue. Esto inicializa el componente de entrada y no mostrará el código numérico del país. Sin embargo, las funciones relacionadas con el teléfono funcionarán normalmente.
Con la propiedad value. Esto hace que el componente sea controlado. El componente se inicializa y no mostrará el código numérico del país. Sin embargo, las funciones relacionadas con el teléfono funcionarán normalmente.
Entrada de teléfono con múltiples códigos de país
El componente PhoneNumberInput muestra un selector de menú desplegable para los códigos de país cuando especifica más de un código de país ISO en la propiedad countries. Si no proporciona un initialValue, el primer código de país en la matriz es el valor inicial que se muestra en el menú desplegable.
Número de teléfono básico con marcador de posición personalizado
El componente PhoneNumberInput gestiona el marcador de posición que se mostrará en función del país seleccionado. Sin embargo, puede invalidarlo y establecer un marcador de posición personalizado.
<PhoneNumberInput label="Phone input component with a custom placeholder" countries={['PL','US']} placeholder="this is a custom placeholder" />
El componente PhoneNumberInput no proporciona una lógica de validación específica, pero sí la forma de incluir la validación del desarrollador y usar la propiedad stateMessages para mostrar cualquier mensaje de error necesario.
Este es un ejemplo de manejo de validación cuando se activa un evento onChange.
exportfunctionPhoneNumberInputValidation(){ const[validationMessages, setValidationMessages]=useState({}); const onChange =useCallback((e, newValue, errorCode)=>{ const componentPhoneNumber = newValue.phoneNumber; const componentCountryCode = newValue.countryCode; const componentErrorCode = errorCode?.errorCode; setValidationMessages({}); if(componentErrorCode && componentErrorCode !=0){ setValidationMessages({ error:['The phone number is not correct'], }); }else{ if( componentPhoneNumber && componentCountryCode && componentCountryCode =='ES'&& componentPhoneNumber.indexOf('6')==0 ){ setValidationMessages({ error:['Only landline numbers are accepted for Spain'], }); } } },[]); return( <PhoneNumberInput countries={['ES','US']} label="Accepts any US number but accepts only landline numbers for Spain" secondaryLabel="Landline numbers cannot start by 6" stateMessages={validationMessages} onChange={onChange} /> ); }
Uso de ref para establecer el foco (controlador imperativo)
PhoneNumberInput y otras entradas permiten el uso de una propiedad ref para acceder a algunos comportamientos nativos. Sin embargo, solo se exponen ciertas características. En este ejemplo, al hacer clic en el botón, el foco se establecerá automáticamente en la entrada que aparezca a continuación.
exportfunctionPhoneNumberRef(){ const inputRef =useRef(null); constsetFocus=(e)=>{ inputRef?.current?.focus(); }; return( <div> <Button label="Set the focus on input" onClick={setFocus}></Button> <PhoneNumberInput label="Get the focus from the button" countries={['ES','US']} ref={inputRef} /> </div> ); }
Se introdujo un nuevo componente @jutro/components/PhoneNumberInput que reemplaza a PhoneNumberField y IntlPhoneNumberField.
Los componentes anteriores relacionados con los teléfonos PhoneNumberField y IntlPhoneNumberField quedaron obsoletos y se trasladaron al paquete @jutro/legacy. Para ver su documentación, consulte una versión de la documentación anterior a la 10.0.
