Entrada enmascarada

Entrada enmascarada en Storybook

Note: Hay versiones obsoletas de este componente. Consulte una versión de los documentos anterior a la 10.3.x.

Uso

Descripción general

Una máscara de entrada guía a los usuarios en la introducción de datos, restringiendo y dando forma a la información según un formato específico a medida que se la introduce.

Puede aplicar una máscara al campo de entrada de texto y al campo de entrada de teléfono.

Cuándo se debe utilizar

En campos con un formato previsto específico, como número de seguro social o código postal.

Cuándo no se debe utilizar

• Para entradas que requieren un campo de formato libre.
• Cuando el patrón de entrada es demasiado complejo para una máscara. Por ejemplo, una dirección de correo electrónico tiene muchas posibilidades para la entrada.

Formato

Anatomía

Ejemplo del campo de entrada de teléfono con una máscara de entrada.

1. Rótulo: Describe el propósito de un campo de entrada.
2. Máscara de entrada: Expresión de cadena que restringe la entrada para admitir valores de entrada válidos. La máscara de entrada aparece en foco.
3. 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.

Contenido

Para conocer los estándares de contenido, consulte las pautas de redacción de entrada de texto y entrada de teléfono.

Comportamientos

La máscara de entrada aparece apenas el campo recibe el foco. Antes de eso, la entrada está vacía o muestra texto de marcador de posición.

Ejemplo de un campo de entrada de texto habilitado (a la izquierda) y un campo de entrada de texto en foco (a la derecha).

Accesibilidad

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.3.x.

Código

Instrucción de importación

import { MaskInput } from '@jutro/components';

Contrato de componentes

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.

Propiedades

labelobligatorio

Tipo

IntlMessageShape

Descripción

Label associated with input field, also passed as a default value to aria-label.

maskobligatorio

Tipo

string

Descripción

String that formats the mask to display, for example 999-999-9999. It defines the structure of the input value, where each character represents a different type of input. For example, 9 represents a numeric character, A represents an alphabetical character, and * represents an alphanumeric character. It also defines the position of static characters, such as dashes or parentheses, and the overall input length. The component follows a fixed-length pattern, hence mask property does not allow optional characters.

className

Tipo

string

Descripción

CSS class name for this component.

disabled

Tipo

boolean

Descripción

If set to true, component is rendered in disabled state.

displayOnly

Tipo

boolean

Descripción

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.

formatChars

Tipo

object

Descripción

A map of special mask formatting characters and the corresponding regular expressions the input must satisfy.

Valor predeterminado

{9: '[0-9]', a: '[A-Za-z]', A: '[A-Z]', '*': '[A-Za-z0-9]', '&': '[0-9A-Z]'}

hideLabel

Tipo

boolean

Descripción

If set to true, the label is not visible.

initialValue

Tipo

string

Descripción

Initial value of input. If the value property is specified along with this property, this property's value is discarded.

labelPosition

Tipo

'top' | 'left'

Descripción

Allows to select label position.

Valor predeterminado

'top'

onBlur

Tipo

function (FocusEvent<HTMLInputElement>)

Descripción

A callback called after the component is focused.

onChange

Tipo

function (React.ChangeEvent<HTMLInputElement>, string)

Descripción

Callback invoked when component value is changed.

onFocus

Tipo

function (FocusEvent<HTMLInputElement>)

Descripción

A callback called after the component is focused.

placeholder

Tipo

IntlMessageShape

Descripción

Placeholder to display on an empty component.

readOnly

Tipo

boolean

Descripción

If set to true, component is rendered in a read-only state. For values in plain text, consider using displayOnly.

required

Tipo

boolean

Descripción

If set to true, sets the field as required displaying an asterisk.

secondaryLabel

Tipo

IntlMessageShape

Descripción

Secondary label text to display.

stateMessages

Tipo

{ error: string[] }

Descripción

An object with a list of error messages for the current state.

tooltip

Tipo

{ text: intlMessageShape, trigger: string } | intlMessageShape

text

Tipo

IntlMessageShape

Descripción

Text to show tooltip content.

trigger

Tipo

string

Descripción

The trigger to show the tooltip.

Descripción

Text to be displayed in the tooltip or tooltip object that includes: text - to show tooltip content, trigger - to set tooltip trigger.

value

Tipo

string

Descripción

Value of input. Takes precedence over initialValue. If this property is passed, component works in controlled mode and its value changes only if this property changes.

Ganchos

No hay ganchos para MaskInput.

Claves de traducción

No hay claves de traducción MaskInput asociadas al componente.

Escotillas de escape

Para obtener más información, consulte nuestra documentación sobre escotillas de escape.

Están disponibles las siguientes opciones:

• Tokens de diseño
• Propiedad className
• Paso de atributos HTML nativos
• Referencia con controladores imperativos
• Propiedad de evento nativa

Comportamientos personalizados

Valor enmascarado y no enmascarado

Cuando se ingresa un valor en MaskInput, recibe formato automáticamente y el valor formateado se presenta como un segundo argumento dentro del evento onChange. Si necesita acceder al valor sin formato, el componente MaskInput extiende el evento onChange para incluir un tercer parámetro. Este parámetro es un objeto que contiene la propiedad no enmascarada, que incluye el valor sin formato.

Máscara para la entrada

Un campo vacío y sin el foco MaskInput no muestra nada o muestra un marcador de posición definido, si está establecido de manera predeterminada. Cuando el campo recibe el foco, la máscara se hace visible. Los usuarios pueden ingresar valores que coincidan con la máscara, lo que hace que la máscara sea invisible. Si el valor proporcionado contiene menos caracteres que los especificados por la máscara, se ignora la entrada. Las máscaras parcialmente rellenas conservan el valor proporcionado y se les agrega los caracteres restantes de la máscara, incluso cuando el campo pierde el foco. En los modos readOnly y displayOnly, la máscara permanece oculta independientemente del estado de la entrada. En el modo disabled, la máscara permanece visible como en el modo enabled.

Copiar y pegar

Cuando se pega un valor en el campo, adopta el formato según la máscara especificada. Si el MaskInput encuentra un carácter que no coincida con los requisitos de la máscara, por ejemplo, pegar letras cuando la máscara prevé números, el carácter no coincidente y el resto del valor se ignoran. Además, si el valor proporcionado excede la longitud especificada por la máscara, el valor se trunca para que coincida con la longitud de la máscara.

Precedencia de disabled, displayOnly y readOnly

Si dos o más de las propiedades disabled, displayOnly, y readOnly se establecen en true al mismo tiempo, la prioridad es la siguiente:

displayOnly > readOnly > disabled

Validación de entradas del usuario

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:

{
  error: ['error message 1', 'error message 2', 'error message N'];
}

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.

Información heredada

¿Está utilizando el componente heredado InputMaskField?

• Para ver los documentos del componente antiguo, consulte una versión de la documentación anterior a la 10.3.
• Este componente heredado también está disponible en Storybook:

  • InputMaskField

Note: Hay versiones obsoletas de este componente. Consulte una versión de los documentos anterior a la 10.3.x.

Ejemplos

Entrada básica enmascarada

import React from 'react';
import { MaskInput } from '@jutro/components';

export const BasicMaskinput = () => {
  return (
    <MaskInput
      label="Mask input component"
      mask="(999) 999-9999"
      secondaryLabel="This is a secondary label"
      initialValue="(123) 942-4237"
    />
  );
};

Note: Si el initialValue se establece y no coincide con la máscara, este valor se descarta.

Formatchars en entrada enmascarada

Puede crear una asignación personalizada de caracteres de formato y las expresiones regulares correspondientes que la entrada debe cumplir. En este ejemplo, la máscara DDD representa cualquier letra de la “a” a la “z” en mayúsculas y 0000 representa cualquier número del 0 al 5.

import React, { useState } from 'react';
import { TextInput, MaskInput } from '@jutro/components';

export const FormatCharsMaskInput = () => {
  const [value, setValue] = useState('');

  // Define the mask format and placeholder characters
  const formatChars = {
    D: '[A-Z]',
    0: '[0-5]',
  };

  return (
    <div>
      <MaskInput
        label="Enter 3 letters in upper case"
        mask="DDD-0000"
        formatChars={formatChars}
      />
    </div>
  );
};

Entrada enmascarada controlada

Puede utilizar la propiedad valor para el caso del componente controlado:

import React, { useState } from 'react';
import { TextInput, MaskInput } from '@jutro/components';

export const ControlledMaskInput = () => {
  const [enteredValue, setEnteredValue] = useState('');

  const onChangefunc = (event) => {
    const newValue = event.target.value;
    setEnteredValue(newValue);
    console.log('Entered value:', newValue);
  };

  return (
    <div>
      <MaskInput
        label="Enter a number to be assigned to the following field"
        mask="(999) 999-9999"
        onChange={onChangefunc}
        stateMessages={{}}
        required
      />
      <TextInput
        label="The value is updated when the first field is modified"
        value={enteredValue}
      />
    </div>
  );
};

Validación

Puede validar la entrada cuando el campo se modifique o cuando pierda el foco utilizando las propiedades onChange y onBlur, respectivamente. Además, en este ejemplo, la propiedad obligatorio establece el campo como obligatoria.

import React, { useState } from 'react';
import { TextInput, MaskInput } from '@jutro/components';

export const ValidationMaskInput = () => {
  const [enteredValue, setEnteredValue] = useState('');

  const onBlurfunc = (event) => {
    const newValue = event.target.value;
    setEnteredValue(newValue);
  };

  return (
    <div>
      <MaskInput
        label="Validation onBlur example"
        mask="(999) 999-9999"
        onBlur={onBlurfunc}
        stateMessages={{}}
        required
      />
      <TextInput
        label="The value is updated when the first field loses its focus"
        value={enteredValue}
      />
    </div>
  );
};

Mensaje de error

Permite establecer un mensaje de error personalizado.

import React from 'react';
import { MaskInput } from '@jutro/components';

export const ErrorMaskInput = () => {
  return (
    <MaskInput
      label="Error field"
      mask="(999) 999-9999"
      stateMessages={{
        error: ['This is a custom error message'],
      }}
    />
  );
};

Registro de cambios

10.13.0

Se agregó una ruta de importación desde @jutro/components para el componente MaskInput.

La ruta de importación anterior desde @jutro/components/new se eliminará en una futura versión principal.

Recomendamos a los usuarios ejecutar el siguiente comando para aplicar un codemod, a fin de actualizar las rutas de importación en su código.

jutro codemod:apply --name=MigrateMaskInputImportFromNew

Para obtener más información sobre los codemods de Jutro, consulte la documentación sobre codemods.

10.3.0

Se introdujo un nuevo componente @jutro/components/new/MaskInput que reemplaza a InputMaskField.

El componente anterior InputMaskField relacionado con la máscara quedó obsoleto y se trasladó al paquete @jutro/legacy. Para ver su documentación, consulte una versión anterior.

Ubicación del componente original:

• InputMaskField: @jutro/components/InputMaskField

Ubicación del componente actualizado:

• InputMaskField: @jutro/legacy/components/InputMaskField