Usar maxLengthEnforcement en lugar de maxLengthEnforced

Para controlar el comportamiento de maxLength en el LengthLimitingTextInputFormatter, usa maxLengthEnforcement en lugar de la ahora obsoleta (deprecated) maxLengthEnforced.

El parámetro maxLengthEnforced se utilizaba para decidir si los campos de texto debían truncar el valor de entrada cuando alcanza el límite maxLength, o si (para TextField y TextFormField) se debía mostrar en su lugar un mensaje de advertencia en el contador de caracteres cuando la longitud de la entrada del usuario superaba maxLength.

Sin embargo, para introducir caracteres CJK, algunos métodos de entrada requieren que el usuario ingrese una secuencia de caracteres latinos en el campo de texto y luego convierta esta secuencia en los caracteres CJK deseados (un proceso conocido como composición de texto). La secuencia latina suele ser más larga que los caracteres CJK resultantes, por lo que establecer un límite estricto de caracteres en un campo de texto puede significar que el usuario no pueda finalizar la composición de texto normalmente debido al límite de caracteres maxLength.

La composición de texto también se utiliza en algunos métodos de entrada para indicar que el texto dentro de la región de composición resaltada se está editando activamente, incluso al ingresar caracteres latinos. Por ejemplo, el teclado en inglés Gboard en Android (al igual que muchos otros métodos de entrada en Android) coloca la palabra actual en una región de composición.

Para mejorar la experiencia de entrada en estos escenarios, se introdujo un nuevo enum de tres estados, MaxLengthEnforcement. Sus valores describen las estrategias admitidas para manejar regiones de composición activas al aplicar un LengthLimitingTextInputFormatter. Se ha añadido un nuevo parámetro maxLengthEnforcement que utiliza este enum a los campos de texto para reemplazar el parámetro booleano maxLengthEnforced. Con el nuevo parámetro enum, los desarrolladores pueden elegir diferentes estrategias según el tipo de contenido que espere el campo de texto.

Para más información, consulta la documentación de maxLength y MaxLengthEnforcement.

El valor predeterminado del parámetro maxLengthEnforcement se infiere del TargetPlatform de la aplicación, para adaptarse a las convenciones de la plataforma:

• Se ha añadido un parámetro maxLengthEnforcement utilizando el nuevo tipo enum MaxLengthEnforcement, como reemplazo del ahora obsoleto parámetro booleano maxLengthEnforced en las clases TextField, TextFormField, CupertinoTextField y LengthLimitingTextInputFormatter.

Se recomienda utilizar el comportamiento predeterminado de la plataforma actual, ya que este será el comportamiento más familiar para el usuario.

• Android, Windows: MaxLengthEnforcement.enforced. Se hace cumplir el comportamiento nativo de estas plataformas. El valor ingresado se truncará independientemente de si el usuario está escribiendo con composición o no.
• iOS, macOS: MaxLengthEnforcement.truncateAfterCompositionEnds. Estas plataformas no tienen una característica de "longitud máxima" y, por lo tanto, requieren que los desarrolladores implementen el comportamiento ellos mismos. No parece haber evolucionado una convención estándar en estas plataformas. Hemos elegido permitir que la composición supere la longitud máxima para evitar romper la entrada CJK.
• Web y Linux: MaxLengthEnforcement.truncateAfterCompositionEnds. Aunque no existe un estándar en estas plataformas (y existen muchas implementaciones con comportamientos conflictivos), la convención común parece ser permitir que la composición supere la longitud máxima de forma predeterminada.
• Fuchsia: MaxLengthEnforcement.truncateAfterCompositionEnds. Aún no existe una convención de plataforma en esta plataforma, por lo que hemos elegido establecer de forma predeterminada la convención que tiene menos probabilidades de provocar pérdida de datos.

Para hacer cumplir el límite que siempre trunca el valor cuando alcanza el límite (por ejemplo, al ingresar un código de verificación), usa MaxLengthEnforcement.enforced en campos de texto editables.

Esta opción puede proporcionar una experiencia de usuario subóptima cuando se utiliza con métodos de entrada que dependen de la composición de texto. Considera usar la opción truncateAfterCompositionEnds cuando el campo de texto espere una entrada de usuario arbitraria que pueda contener caracteres CJK. Consulta la sección Context para más información.

Código antes de la migración:

TextField(maxLength: 6)

o:

TextField(
  maxLength: 6,
  maxLengthEnforced: true,
)

Código después de la migración:

TextField(
  maxLength: 6,
  maxLengthEnforcement: MaxLengthEnforcement.enforced,
)

Para mostrar un error de longitud máxima en TextField, pero no truncar cuando se supera el límite, usa MaxLengthEnforcement.none en lugar de maxLengthEnforced: false.

Código antes de la migración:

TextField(
  maxLength: 6,
  maxLengthEnforced: false,
)

Código después de la migración:

TextField(
  maxLength: 6,
  maxLengthEnforcement: MaxLengthEnforcement.none,
)

Para CupertinoTextField, que no puede mostrar un mensaje de error, simplemente no establezcas el valor de maxLength.

Código antes de la migración:

CupertinoTextField(
  maxLength: 6,
  maxLengthEnforced: false,
)

Código después de la migración:

CupertinoTextField()

Para evitar truncar el texto mientras el usuario escribe usando composición, especifica MaxLengthEnforcement.truncateAfterCompositionEnds. Este comportamiento permite que los métodos de entrada que utilizan regiones de composición más grandes que el texto resultante, como es común por ejemplo con el texto en chino, japonés y coreano (CJK), ignoren temporalmente el límite hasta que se complete la edición.

El teclado en inglés de Gboard en Android (y muchos otros métodos de entrada de Android) crea una región de composición para la palabra que se está ingresando. Cuando se usa en un campo de texto con truncateAfterCompositionEnds, el usuario no se detendrá de inmediato en el límite maxLength. Considera la opción enforced si tienes la seguridad de que el campo de texto no se utilizará con métodos de entrada que empleen regiones de composición temporalmente largas, como el texto CJK.

Código para la implementación:

TextField(
  maxLength: 6,
  maxLengthEnforcement: MaxLengthEnforcement.truncateAfterCompositionEnds, // Temporarily lifts the limit.
)

Cuando te diriges a una configuración regional (locale) específica, es tentador asumir que todos los usuarios estarán satisfechos con la entrada de esa configuración regional. Por ejemplo, se podría asumir que el software de un foro dirigido a una comunidad de habla inglesa solo necesita manejar texto en inglés. Sin embargo, este tipo de asunción suele ser incorrecta. Por ejemplo, tal vez los participantes del foro en inglés quieran hablar sobre anime japonés o cocina vietnamita. Tal vez uno de los participantes sea coreano y prefiera expresar su nombre en sus ideogramas nativos. Por esta razón, los campos de formato libre rara vez deberían usar el valor enforced y en su lugar deberían preferir el valor truncateAfterCompositionEnds si es posible.

Introducido en la versión: v1.26.0-1.0.pre
En la versión estable: 2.0.0

Doc de diseño:

• Documento de diseño de MaxLengthEnforcement

Documentación de la API:

• MaxLengthEnforcement
• LengthLimitingTextInputFormatter
• maxLength

Issues relevantes:

• Issue 63753
• Issue 67898

PR relevante:

• PR 63754: Fix TextField crashed with composing and maxLength set
• PR 68086: Introduce MaxLengthEnforcement