La entrada de número permite a los usuarios ingresar o seleccionar valores numéricos dentro de un intervalo predeterminado. Incluye controles para aumentar o disminuir gradualmente el valor. Los usuarios también pueden escribir valores numéricos directamente en el campo de entrada.
No utilice este componente cuando al usuario no le importe el valor preciso, sino solo el intervalo aproximado. Considere la posibilidad de usar el componente de control deslizante en su lugar.
Rótulo: Describe el propósito de un campo de entrada.
Texto de ayuda (opcional): 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.
Valor numérico: Cambia cuando el usuario ingresa un valor en el campo o usa las dos flechas al final de la entrada para aumentar o disminuir el valor.
Campo de entrada de número: Contenedor, que consta de un relleno y un contorno, en el que el usuario ingresa datos.
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 número. 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 número, 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 el millaje anual estimado, puede usar el texto de error para guiarlo a una solución: “Ingrese su millaje anual estimado”.
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 número 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 número 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.
Para activar una entrada de número, los usuarios deben hacer clic en el área dentro del borde. Cuando recibe el foco, aparecen dos flechas al final de la entrada. Estos controles permiten a los usuarios aumentar o disminuir gradualmente el valor.
El componente entrada de número deriva su nombre accesible de un atributo aria-label. Cambiar el valor de texto del elemento rótulo también cambia el valor del nombre accesible. El atributo predeterminado aria-required='true' cambia a 'false' cuando la casilla de verificación requerida está marcada en Storybook.
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.
The number of decimal places to display in the value. If it is set, the user is prevented from entering too many digits after the decimal point. If the value or initialValue props have too many digits after the decimal point, the displayed figure is rounded to the closest valid value.
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.
Initial value of the input. If the value prop is specified along with this prop, this prop's value is discarded. If the decimalPlaces prop is specified along with this prop, the displayed value is rounded to the closest valid value.
Maximum value of the input. If this prop is passed, the component does not allow entering values higher than the specified value when using the Up Arrow key.
Minimum value of the input. If this prop is passed, the component does not allow entering values lower than the specified value when using the Down Arrow key.
Step increment for value changes. If this prop is passed, the component will increase or decrease its value by the specified step when the Up Arrow or Down Arrow keys are pressed.
Value of the input. Takes precedence over initialValue. If this prop is passed, the component works in controlled mode and its value will change only if this prop changes. If the decimalPlaces prop is specified along with this prop, the displayed value is rounded to the closest valid value.
Puede utilizar atributos de entrada HTML, excepto cualquiera de los que Jutro invalida. Estos atributos se asignarán al elemento HTML input.
Tenga en cuenta que la mayoría de los atributos específicos de entrada de número (step, min y max) se incluyen como parte de la API del componente y pueden tener alguna lógica específica de Jutro relacionada.
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:
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.
Puede utilizar los estados de React para controlar el valor de una NumberInput, pero existen algunas limitaciones a la hora de hacerlo.
El evento onChange solo se activa si la entrada tiene el foco. Si el valor se actualiza como un componente controlado, la devolución de llamada de onChange no se ejecuta.
Si NumberInput tiene una propiedad decimalPlaces y recibe un valor de una actualización de estado de React, el valor mostrado se redondea al valor válido más cercano.
Por ejemplo, en el siguiente código puede usar la primera entrada para cambiar el valor de la segunda entrada. Al hacerlo, observará los siguientes dos comportamientos:
Si se ingresa un valor mayor que 100 o menor que 0 en la primera entrada, los mensajes de validación no se muestran en la segunda entrada porque su devolución de llamada no se ejecuta.
Si se introducen más de dos decimales, el valor que aparece en la segunda entrada se redondea al valor válido más cercano.
exportfunctionNumberInputDecimalPlacesControlledExample(){ const[firstInputValue, setFirstInputValue]=useState(); const[secondInputValue, setSecondInputValue]=useState(); const[validationMessages, setValidationMessages]=useState({}); const max =100; const min =0; const handleFirstInputChange =useCallback((event, newValue)=>{ console.log(newValue) setFirstInputValue(newValue ||0); },[]); const handleSecondInputChange =useCallback((e, newValue)=>{ setValidationMessages({}); if(newValue &&(newValue > max || newValue < min)){ setValidationMessages({ error:['Value must be between 0 and 100'], }); } },[]); return( <NumberInput label="Number input" secondaryLabel="Change this value to see the second input update" onChange={handleFirstInputChange} /> <NumberInput label="Second number input" secondaryLabel="Value controlled by the first input" value={firstInputValue} decimalPlaces={2} onChange={handleSecondInputChange} stateMessages={validationMessages} min={min} max={max} readOnly /> ); }
El componente básico entrada numérica solo necesita que se muestre la propiedad label. Otras propiedades se pueden utilizar para complementar su comportamiento: placeholder, secondaryLabel, onChange o los números específicos.
<NumberInput label="Number input component" placeholder="Write what you want here" secondaryLabel="Free text input" />
El componente entrada de número permite configurar los valores máx. y mín. Sin embargo, esto no está relacionado con una función de validación, sino con el comportamiento de los componentes. Al establecer cualquiera de estas dos propiedades, no será posible utilizar el componente flecha para establecer un valor que sea menor que la propiedad min o un valor que sea más alto que la propiedad max.
<NumberInput label="Number input component with min and max" placeholder="Enter a value" secondaryLabel="Test the limits with using the arrows" min={20} max={40} />
El componente entrada de número 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.
exportfunctionNumberInputValidation(){ const[validationMessages, setValidationMessages]=useState({}); const max =100; const min =0; const onChange =useCallback((e, newValue)=>{ setValidationMessages({}); if(newValue &&(newValue > max || newValue < min)){ setValidationMessages({ error:['Value must be between 0 and 100'], }); } },[]); return( <NumberInput label="Enter value" secondaryLabel="Min = 0. Max = 100" stateMessages={validationMessages} min={min} max={max} onChange={onChange} /> ); }
La propiedad decimalPlaces especifica la cantidad de decimales que se mostrarán. Limita a los usuarios el ingreso de demasiados dígitos después de la coma decimal, pero si se establecen las propiedades initialValue o value, el número se redondea al valor válido más cercano.
Por ejemplo, si decimalPlaces se establece en 2, el usuario no puede ingresar más de dos dígitos decimales. Sin embargo, las propiedades initialValue o value pueden tener tres o más dígitos decimales.
<NumberInput label="Number input component limited decimals" placeholder="Enter a value" secondaryLabel="Try to add an additional decimal" decimalPlaces={2} /> <NumberInput label="Number input with initial value" secondaryLabel="Rounded up from 5.666" initialValue={5.666} decimalPlaces={2} readOnly /> <NumberInput label="Number input with value" secondaryLabel="Rounded up from 5.666" value={5.666} decimalPlaces={2} readOnly />
Se ha modificado el comportamiento de la propiedad decimalPlaces. Ahora se impide que el usuario ingrese dígitos adicionales después del límite decimalPlaces. Por ejemplo, si decimalPlaces es 2, el usuario no puede ingresar un tercer dígito después de la coma decimal.
Las propiedades initialValue o value pueden tener dígitos adicionales después de la coma decimal, pero el valor mostrado se redondea al valor válido más cercano.
Se introdujo un nuevo componente @jutro/components/NumberInput que reemplaza a InputNumberField.
El componente anterior InputNumberField relacionado con un número quedó obsoleto y se trasladó al paquete @jutro/legacy. Para ver su documentación, consulte una versión anterior.
