Entrada

El Entry de .NET Multi-platform App UI (.NET MAUI) permite escribir y editar una sola línea de texto. Además, Entry se puede usar como un campo de contraseña.

Entry define las siguientes propiedades:

• ClearButtonVisibility, de tipo ClearButtonVisibility, controla si se muestra un botón borrar, lo que permite al usuario borrar el texto. El valor predeterminado de esta propiedad garantiza que no se muestre un botón borrar.
• HorizontalTextAlignment, del tipo TextAlignment, define la alineación horizontal del texto.
• IsPassword, de tipo bool, especifica si la entrada debe ocultar visualmente el texto con tipo.
• ReturnCommand, de tipo ICommand, define el comando que se va a ejecutar cuando se presiona la tecla de retorno.
• }ReturnCommandParameter, de tipo object, especifica el parámetro para ReturnCommand.
• ReturnType, de tipo ReturnType, especifica la apariencia del botón de retorno.
• VerticalTextAlignment, del tipo TextAlignment, define la alineación vertical del texto.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y que se les puede aplicar un estilo.

Además, Entry define un evento Completed, que se genera cuando el usuario finaliza el texto en Entry con la clave de retorno.

Entry se deriva de la clase InputView, de la que hereda las propiedades siguientes:

• CharacterSpacing, del tipo double, es el espaciado entre los caracteres del texto introducidos.
• CursorPosition, de tipo int, define la posición del cursor dentro del editor.
• FontAttributes, de tipo FontAttributes, determina el estilo de texto.
• FontAutoScalingEnabled, de tipo bool, define si el texto reflejará las preferencias de escalado establecidas en el sistema operativo. El valor predeterminado de esta propiedad es true.
• FontFamily, del tipo string, define la familia de fuentes.
• FontSize, de tipo double, define el tamaño de fuente.
• IsReadOnly, de tipo bool, define si se debe impedir que el usuario modifique el texto. El valor predeterminado de esta propiedad es false.
• IsSpellCheckEnabled, de tipo bool, controla si la revisión ortográfica está habilitada.
• IsTextPredictionEnabled, de tipo bool, controla si la predicción de texto y la corrección automática de texto están habilitadas.
• Keyboard, de tipo Keyboard, especifica el teclado de entrada temporal que se muestra al escribir texto.
• MaxLength, de tipo int, define la longitud máxima de entrada.
• Placeholder, de tipo string, define el texto que se muestra cuando el control está vacío.
• PlaceholderColor, del tipo Color, define el color del texto del cuadro de búsqueda del marcador de posición.
• SelectionLength, de tipo int, representa la longitud del texto seleccionado dentro del control.
• Text, de tipo string, define el texto escrito en el control.
• TextColor, de tipo Color, define el color del texto especificado.
• TextTransform, de tipo TextTransform, especifica el uso de mayúsculas y minúsculas del texto especificado.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y que se les puede aplicar un estilo.

Además, InputView define un evento TextChanged, que se genera cuando cambia el texto de Entry. El objeto TextChangedEventArgs que acompaña al evento TextChanged tiene propiedades NewTextValue y OldTextValue, que especifican el texto nuevo y antiguo, respectivamente.

Para obtener información sobre cómo especificar fuentes en un Entry, consulta Fuentes.

Creación de una entrada

En el siguiente ejemplo se muestra cómo crear un Entry:

<Entry x:Name="entry"
       Placeholder="Enter text"
       TextChanged="OnEntryTextChanged"
       Completed="OnEntryCompleted" />

El código de C# equivalente es el siguiente:

Entry entry = new Entry { Placeholder = "Enter text" };
entry.TextChanged += OnEntryTextChanged;
entry.Completed += OnEntryCompleted;

En la siguiente captura de pantalla se muestra el resultado de Entry en Android:

Nota:

En iOS, el teclado de entrada temporal puede cubrir un campo de entrada de texto cuando el campo está cerca de la parte inferior de la pantalla, lo que dificulta la entrada de texto. Sin embargo, en una aplicación .NET MAUI iOS, las páginas se desplazan automáticamente cuando el teclado de entrada temporal cubriría un campo de entrada de texto, de modo que el campo esté por encima del teclado de entrada temporal. Puede llamarse el método KeyboardAutoManagerScroll.Disconnect, en el espacio de nombres Microsoft.Maui.Platform, para deshabilitar este comportamiento predeterminado. Puede llamarse al método KeyboardAutoManagerScroll.Connect para volver a habilitar el comportamiento después de deshabilitarlo.

Se puede acceder al texto escrito leyendo la propiedad Texty los eventos TextChanged y Completed indican que el texto ha cambiado o se ha completado.

El evento TextChanged se genera cuando cambia el texto en el Entry, y el TextChangedEventArgs proporciona el texto antes y después del cambio a través de las propiedades OldTextValue y NewTextValue:

void OnEntryTextChanged(object sender, TextChangedEventArgs e)
{
    string oldText = e.OldTextValue;
    string newText = e.NewTextValue;
    string myText = entry.Text;
}

El evento Completed se genera cuando el usuario ha finalizado la entrada presionando la tecla Return en el teclado o presionando la tecla Tab en Windows. El controlador del evento es un controlador de eventos genérico:

void OnEntryCompleted(object sender, EventArgs e)
{
   string text = ((Entry)sender).Text;
}

Una vez desencadenado el evento Completed, se ejecuta cualquier ICommand especificado por la propiedad ReturnCommand, con el object especificado por la propiedad ReturnCommandParameter que se pasa a ReturnCommand.

Nota:

La clase VisualElement, que se encuentra en la jerarquía de herencia Entry, también tiene eventos Focused y Unfocused.

Espaciado entre caracteres

El espaciado de caracteres se puede aplicar a mediante un Entry estableciendo la propiedad CharacterSpacing en un valor double:

<Entry ...
       CharacterSpacing="10" />

El resultado es que los caracteres del texto mostrado por el Entry están separados por unidades independientes del dispositivo espaciadas CharacterSpacing.

Nota:

El valor de propiedad CharacterSpacing se aplica al texto mostrado por las propiedades Text y Placeholder.

Limitación de las longitudes de entrada

La propiedad MaxLength puede utilizarse para limitar la longitud de entrada que se acepta para el Entry. Esta propiedad debe establecerse en un entero positivo:

<Entry ...
       MaxLength="10" />

Un valor de propiedad MaxLength de 0 indica que no se permitirá ninguna entrada y un valor de int.MaxValue, que es el valor predeterminado de un Entry, indica que no hay ningún límite efectivo en el número de caracteres que se pueden escribir.

Establecer la posición del cursor y la longitud de la selección de texto

La propiedad CursorPosition se puede usar para devolver o establecer la posición en la que se insertará el siguiente carácter en la cadena almacenada en la propiedad Text:

<Entry Text="Cursor position set"
       CursorPosition="5" />

El valor predeterminado de la propiedad CursorPosition es de 0, que indica que el texto se insertará al principio de Entry.

Además, la propiedad SelectionLength se puede usar para devolver o establecer la longitud de la selección de texto dentro del Entry:

<Entry Text="Cursor position and selection length set"
       CursorPosition="2"
       SelectionLength="10" />

El valor predeterminado de esta propiedad SelectionLength es de 1, que indica que no se ha seleccionado texto.

mostrar un botón borrar

La propiedad ClearButtonVisibility se puede usar para controlar si un Entry muestra un botón de borrar, lo que permite al usuario borrar el texto. Esta propiedad se debe establecer en un miembro de enumeración ClearButtonVisibility:

• Never indica que nunca se mostrará un botón de borrar. Se trata del valor predeterminado de la propiedad ClearButtonVisibility.
• WhileEditing indica que se mostrará un botón de borrar en Entry, mientras que tiene el foco y el texto.

En el siguiente ejemplo se muestra cómo se establece la propiedad:

<Entry Text=".NET MAUI"
       ClearButtonVisibility="WhileEditing" />

En la captura de pantalla siguiente se muestra un Entry en Android con el botón de borrar habilitado:

Transformar texto

Un objeto Entry puede transformar el uso de mayúsculas y minúsculas de su texto, almacenado en la propiedad Text, estableciendo la propiedad TextTransform en un valor de la enumeración TextTransform. Esta enumeración tiene cuatro valores:

• None indica que el texto no se transformará.
• Default: indica que se usará el comportamiento predeterminado para la plataforma. Se trata del valor predeterminado de la propiedad TextTransform.
• Lowercase indica que el texto se transformará en minúsculas.
• Uppercase indica que el texto se transformará en mayúsculas.

En el ejemplo siguiente se muestra cómo transformar texto en mayúsculas:

<Entry Text="This text will be displayed in uppercase."
       TextTransform="Uppercase" />

Ocultar entrada de texto

Entry proporciona la propiedad IsPassword que oculta visualmente el texto escrito cuando se establece en true:

<Entry IsPassword="true" />

En la captura de pantalla siguiente se muestra un Entry cuya entrada se ha ocultado:

Personalizar el teclado

El teclado que aparece cuando los usuarios interactúan con Entry se puede establecer mediante programación a través de la propiedad Keyboard en una de las siguientes propiedades de la clase Keyboard:

• Chat: se usa para el texto y los lugares donde los emoji son útiles.
• Default: el teclado predeterminado.
• Email: se usa al especificar direcciones de correo electrónico.
• Numeric: se usa al escribir números.
• Plain: se usa al escribir texto, sin ningún KeyboardFlags especificado.
• Telephone: se usa al escribir números de teléfono.
• Text: se usa al escribir texto.
• Url : se usa para especificar las rutas de acceso de archivo y direcciones web.

En el siguiente ejemplo se muestra cómo establecer la propiedad Keyboard:

<Entry Keyboard="Chat" />

La clase Keyboard tiene también un patrón de diseño Factory Method Create que puede usarse para personalizar un teclado mediante la especificación del comportamiento de las mayúsculas y minúsculas, el corrector ortográfico y las sugerencias. Los valores de enumeración KeyboardFlags se especifican como argumentos para el método, con la devolución de un Keyboard personalizado. La enumeración KeyboardFlags contiene los valores siguientes:

• None: no se agregan características al teclado.
• CapitalizeSentence: indica que la primera letra de la primera palabra de cada frase se escribirá automáticamente en mayúsculas.
• Spellcheck: indica que se pasará el corrector ortográfico al texto especificado.
• Suggestions: indica que se ofrecerán finalizaciones de palabra para el texto especificado.
• CapitalizeWord: indica que las primeras letras de todas las palabras se escribirán automáticamente en mayúsculas.
• CapitalizeCharacter: indica que todos los caracteres se escribirán automáticamente en mayúsculas.
• CapitalizeNone: indica que no se producirá ningún uso automático de mayúsculas.
• All: indica que se pasará el corrector automático, se ofrecerán finalizaciones de palabras y las frases empezarán en mayúsculas en el texto especificado.

El ejemplo de código XAML siguiente muestra cómo personalizar el Keyboard predeterminado para ofrecer finalizaciones de palabras y poner en mayúsculas todos los caracteres especificados:

<Entry Placeholder="Enter text here">
    <Entry.Keyboard>
        <Keyboard x:FactoryMethod="Create">
            <x:Arguments>
                <KeyboardFlags>Suggestions,CapitalizeCharacter</KeyboardFlags>
            </x:Arguments>
        </Keyboard>
    </Entry.Keyboard>
</Entry>

El código de C# equivalente es el siguiente:

Entry entry = new Entry { Placeholder = "Enter text here" };
entry.Keyboard = Keyboard.Create(KeyboardFlags.Suggestions | KeyboardFlags.CapitalizeCharacter);

Personalización de la clave de retorno

La apariencia de la tecla de retorno en la entrada de teclado en pantalla, que se muestra cuando un elemento Entry tiene el foco, se puede personalizar estableciendo la propiedad ReturnType en un valor de la enumeración ReturnType:

• Default : indica que no se requiere ninguna clave de devolución específica y que se usará el valor predeterminado de la plataforma.
• Done : indica una clave de retorno "Done".
• Go : indica una clave de retorno "Go".
• Next : indica una clave de retorno "Next".
• Search : indica una clave de retorno "Search".
• Send : indica una clave de retorno "Send".

El ejemplo de XAML siguiente muestra cómo establecer el valor de retorno:

<Entry ReturnType="Send" />

Nota:

La apariencia exacta de la clave de retorno dependiente de la plataforma. En iOS, la clave de retorno es un botón basado en texto. Sin embargo, en Android y Windows, la clave de retorno es un botón basado en iconos.

Cuando se presiona la tecla Return, se desencadena el Completed evento y se ejecuta cualquier ICommand especificado por la ReturnCommand propiedad. Además, cualquier object especificado por la propiedad ReturnCommandParameter se pasará a ICommand como parámetro. Para obtener más información sobre los comandos, consulta Commanding.

Ocultar y mostrar la entrada de teclado en pantalla

La clase SoftInputExtensions, en el espacio de nombres Microsoft.Maui, proporciona una serie de métodos de extensión que admiten la interacción con la entrada de teclado en pantalla en los controles que admiten la entrada de texto. La clase define los métodos siguientes:

• IsSoftInputShowing, que comprueba si el dispositivo muestra actualmente en la entrada de teclado en pantalla.
• HideSoftInputAsync, que intentará ocultar la entrada de teclado en pantalla si se muestra actualmente.
• ShowSoftInputAsync, que intentará mostrar la entrada de teclado en pantalla si está oculto actualmente.

En el ejemplo siguiente se muestra cómo ocultar la entrada de teclado en pantalla en un objeto Entry denominado entry, si se muestra actualmente:

if (entry.IsSoftInputShowing())
    await entry.HideSoftInputAsync(System.Threading.CancellationToken.None);

Habilitar y deshabilitar la revisión ortográfica

La propiedad IsSpellCheckEnabled controla si la revisión ortográfica está habilitada. De forma predeterminada, la propiedad se establece en true. A medida que el usuario escribe texto, se indican errores ortográficos.

Sin embargo, para algunos escenarios de entrada de texto, como escribir un nombre de usuario, la revisión ortográfica proporciona una experiencia negativa y debe deshabilitarse estableciendo la IsSpellCheckEnabled propiedad false en:

<Entry ... IsSpellCheckEnabled="false" />

Nota:

Cuando la propiedad IsSpellCheckEnabled se establece en false y no se usa un teclado personalizado, se deshabilitará el corrector ortográfico nativo. Sin embargo, si se ha establecido un objeto Keyboard que deshabilita la revisión ortográfica, como Keyboard.Chat, se omite la propiedad IsSpellCheckEnabled. Por lo tanto, la propiedad no se puede usar para habilitar la revisión ortográfica de un Keyboard que la deshabilita explícitamente.

Habilitación y deshabilitación de la predicción de texto

La propiedad IsTextPredictionEnabled controla si la predicción de texto y la corrección automática de texto están habilitadas. De forma predeterminada, la propiedad se establece en true. A medida que el usuario escribe texto, se presentan predicciones de palabras.

Sin embargo, para algunos escenarios de entrada de texto, como escribir un nombre de usuario, una predicción de texto y una corrección automática de texto proporcionan una experiencia negativa y deben deshabilitarse estableciendo la propiedad IsTextPredictionEnabled en false:

<Entry ... IsTextPredictionEnabled="false" />

Nota:

Cuando la propiedad IsTextPredictionEnabled se establece en false y no se usa un teclado personalizado, se deshabilita la predicción de texto y la corrección automática de texto. Sin embargo, si se ha establecido un Keyboard que deshabilita la predicción de texto, se omite la propiedad IsTextPredictionEnabled. Por lo tanto, no se puede usar la propiedad para habilitar la predicción de texto para un Keyboard que la deshabilite explícitamente.

Impedir la entrada de texto

Se puede impedir que los usuarios modifiquen el texto de un Entry mediante el establecimiento de la propiedad IsReadOnly en true:

<Entry Text="User input won't be accepted."
       IsReadOnly="true" />

Nota:

La propiedad IsReadonly no modifica la apariencia visual de un objeto Entry, a diferencia de la propiedad IsEnabled que también cambia la apariencia visual de Entry a gris.