El componente entrada de texto permite a los usuarios ingresar texto y números en los campos de entrada de datos. Las entradas de texto se encuentran entre los componentes de la interfaz más importantes y utilizados con los que interactúan los usuarios. Permiten a los usuarios proporcionar la información necesaria que un sistema requiere para cumplir con una tarea o un conjunto de tareas específicas.
Cuando el usuario necesita buscar algo. Utilice el componente de búsqueda en su lugar.
Si el usuario solo puede ingresar una opción de una lista predefinida. Considere la posibilidad de utilizar un control de selección, como el menú desplegable o el grupo de selección.
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.
Campo de entrada de texto: Contenedor del campo de texto, que consiste en un relleno y un contorno, donde los usuarios ingresan texto.
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 texto. 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 texto, 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 dirección de correo electrónico, puede usar el texto de error para guiarlo a una solución: “Escriba su dirección de correo electrónico”.
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 texto 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 texto 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 rótulo y la entrada se asocian entre sí mediante programación. De forma predeterminada, las descripciones emergentes se colocan junto al rótulo. Incluye el atributo WAI-ARIA de aria-label="Show tooltip"y también aria-expanded="false", que cambia a "true" cuando se activa la descripción emergente. El contenido dentro de la descripción emergente es expresado por los lectores de pantalla por medio del rol WAI-ARIA de 'alert'. Cuando se marca la casilla de verificación obligatoria en Storybook, el atributo 'required' se agrega a la marca y el valor de aria-required cambia de 'true' a 'false'.
Si el contenido dentro de la entrada de texto se desborda, el usuario debe poder desplazarse horizontalmente de un extremo al otro utilizando Shift+Scroll. También puede utilizar las teclas Left Arrow y Right Arrow para mover el cursor de un lado a otro.
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.
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.
El resultado de pasar estas propiedades id y maxLength es que formará parte del input HTML que se crea en el DOM HTML. En el caso de maxLength, evita que el usuario escriba más de 10 caracteres. Esto solo se puede hacer pegando directamente el valor.
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.
El componente TextInput solo necesita que la propiedad label se muestre. Otras propiedades como placeholder, secondaryLabely onChange se pueden usar para complementar su comportamiento.
<TextInput label="Text input component" placeholder="Write what you want here" secondaryLabel="Free text input" />
TextInput, junto con las otras entradas, proporcionan la opción de configurar el componente como display only. Cuando la propiedad displayOnly está establecida en true, el componente se muestra como texto, sin el aspecto y estilo de entrada específico.
<TextInput label="Text input component" placeholder="Write what you want here" secondaryLabel="Free text input" value="this is the value" displayOnly={true} />
La propiedad tooltip hará que el componente muestre el ícono de descripción emergente. Cuando el usuario interactúa con él, también muestra información complementaria. Esta propiedad puede recibir texto para mostrar: {text: "this will be displayed when tooltip is opened"}. También puede controlar qué acción específica hace que aparezca la descripción emergente pasando un segundo atributo trigger. Acepta los eventos HTML estándares como pointerover, focus y blur. De forma predeterminada, la descripción emergente se abre al hacer clic en el ícono correspondiente.
En este ejemplo, la descripción emergente se muestra cuando el cursor está sobre su ícono.
<TextInput label="Text input component" placeholder="Write what you want here" secondaryLabel="Free text input" tooltip={{text:'tooltip text',trigger:'pointerover'}} />
TextInput no proporciona una lógica de validación específica, pero sí un método para incluir la validación del desarrollador y usa la propiedad stateMessages para mostrar cualquier mensaje de error necesario.
Este es un ejemplo de manejo de validación cuando se activa el evento onChange.
functionTextInputValidation(){ const[validationMessages, setValidationMessages]=useState({}); const onChange =useCallback((e, newValue)=>{ if(!newValue || newValue.indexOf('a')==-1){ setValidationMessages({}); }else{ setValidationMessages({ error:['The text cannot contain `a` character'], }); } },[]); return( <TextInput label="Do not accept words with 'a'" secondaryLabel="Will raise an error if contains 'a' character" stateMessages={validationMessages} onChange={onChange} /> ); }
La propiedad value se puede utilizar para el caso del componente controlado:
exportfunctionInputControlled(){ const[updatedValue, setNewValue]=useState('first given value'); constonChange=(e, newValue)=>{ setNewValue(newValue); }; return( <div> <TextInput label="Enter here the value to be assigned input below" onChange={onChange} /> <br/> <TextInput label="Changes with the above" secondaryLabel="This cannot be manually modified" value={updatedValue} /> </div> ); }
TextInput, junto con otras entradas, permiten el uso de una propiedad ref para acceder a algunos comportamientos nativos. Sin embargo, solo se exponen algunas características. En este caso, cuando se hace clic en el botón, el foco se establece automáticamente en la siguiente entrada:
exportfunctionInputRef(){ const inputRef =useRef(null); constsetFocus=(e)=>{ inputRef?.current?.focus(); }; return( <div> <Button label="Set focus on text input" onClick={setFocus}></Button> <TextInput label="Get the focus from the button" ref={inputRef} /> </div> ); }
Se introdujo un nuevo componente @jutro/components/TextInput que sustituye a InputField.
El componente anterior InputField quedó obsoleto y se trasladó al paquete @jutro/legacy. Para ver su documentación, consulte la versión de la documentación anterior a la 10.0.
Componente
Ubicación antigua
Ubicación nueva
InputField
@jutro/components/InputField
@jutro/legacy/components/InputField
Los codemods están disponibles para cambiar automáticamente el nombre de las importaciones existentes.
