Entry

O .NET Multi-Platform App UI (.NET MAUI) Entry permite que você insira e edite uma única linha de texto. Além disso, o Entry pode ser usado como um campo de senha.

Entry define as propriedades a seguir:

• ClearButtonVisibility, do tipo ClearButtonVisibility, controla se um botão Limpar é exibido, o que permite que o usuário limpe o texto. O valor padrão dessa propriedade garante que um botão Limpar não seja exibido.
• HorizontalTextAlignment, do tipo TextAlignment, define o alinhamento horizontal do texto.
• IsPassword, do tipo bool, especifica se a entrada deve obscurecer visualmente o texto digitado.
• ReturnCommand, do tipo ICommand, define o comando a ser executado quando a tecla de retorno é pressionada.
• ReturnCommandParameter, do tipo object, especifica o parâmetro para ReturnCommand.
• ReturnType, do tipo ReturnType, especifica a aparência do botão de retorno.
• VerticalTextAlignment, do tipo TextAlignment, define o alinhamento vertical do texto.

Essas propriedades são apoiadas por objetos BindableProperty, o que significa que podem ser alvos de associações de dados e ser estilizada.

Além disso, Entry define um evento Completed, que é gerado quando os usuários finaliza, o texto no Entry com a chave de retorno.

Entry é derivado da classe InputView, da qual herda as seguintes propriedades:

• CharacterSpacing, do tipo double, define o espaçamento entre os caracteres no texto inserido.
• CursorPosition, do tipo int, define a posição do cursor dentro do editor.
• FontAttributes, do tipo FontAttributes, determina o estilo de texto.
• FontAutoScalingEnabled, do tipo bool, define se o texto refletirá as preferências de escala definidas no sistema operacional. O valor padrão dessa propriedade é true.
• FontFamily, do tipo string, define a família da fonte.
• FontSize, do tipo double, define o tamanho da fonte.
• IsReadOnly, do tipo bool, define se os usuários serão impedidos de modificar o texto. O valor padrão dessa propriedade é false.
• IsSpellCheckEnabled, do tipo bool, controla se a verificação ortográfica está habilitada.
• IsTextPredictionEnabled, do tipo bool, controla se a previsão de texto e a correção automática de texto estão habilitadas.
• Keyboard, do tipo Keyboard, especifica o teclado de entrada tátil exibido ao inserir texto.
• MaxLength, do tipo int, define o comprimento máximo de entrada.
• Placeholder, do tipo string, define o texto que é exibido quando o controle está vazio.
• PlaceholderColor, do tipo Color, define a cor do texto do espaço reservado.
• SelectionLength, do tipo int, representa o comprimento do texto selecionado no controle.
• Text, do tipo string, define o texto inserido no controle.
• TextColor, do tipo Color, define a cor do texto inserido.
• TextTransform, do tipo TextTransform, especifica a o uso de letras maiúsculas e minúsculas do texto inserido.

Essas propriedades são apoiadas por objetos BindableProperty, o que significa que podem ser alvos de associações de dados e ser estilizada.

Além disso, InputView define um evento TextChanged, que é gerado quando o texto no Entry muda. O objeto TextChangedEventArgs que acompanha o evento TextChanged possui as propriedades NewTextValue e OldTextValue, que especificam o texto novo e antigo, respectivamente.

Para obter informações sobre como especificar fontes em um Entry, consulte Fontes.

Criar uma entrada

O seguinte exemplo mostra como criar um Entry:

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

Este é o código C# equivalente:

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

A captura de tela a seguir mostra o Entry resultante no Android:

Observação

No iOS, o teclado de entrada tátil pode encobrir um campo de entrada de texto quando o campo estiver próximo da parte inferior da tela, dificultando a inserção de texto. No entanto, em um aplicativo .NET MAUI para iOS, as páginas rolam automaticamente quando o teclado de entrada tátil cobre um campo de entrada de texto, de modo que o campo permanece acima do teclado de entrada tátil. O método KeyboardAutoManagerScroll.Disconnect, no namespace Microsoft.Maui.Platform, pode ser chamado para desabilitar esse comportamento padrão. O método KeyboardAutoManagerScroll.Connect pode ser chamado para reabilitar o comportamento depois de desabilitado.

É possível acessar o texto inserido lendo a propriedade Text e os eventos TextChanged e Completed sinalizam que o texto foi alterado ou finalizado.

O evento TextChanged é gerado quando o texto no Entry muda, e o evento TextChangedEventArgs fornece o texto antes e depois da alteração por meio das propriedades OldTextValue e NewTextValue:

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

O evento Completed é gerado quando o usuário encerra a entrada pressionando a tecla Return no teclado ou pressionando a tecla Tab no Windows. O manipulador do evento é um manipulador de eventos genérico:

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

Depois que o evento Completed é acionado, qualquer ICommand especificado pela propriedade ReturnCommand é executado, com o object especificado pela propriedade ReturnCommandParameter sendo passado para o ReturnCommand.

Observação

A classe VisualElement, que está na hierarquia de herança Entry, também tem eventos Focused e Unfocused.

Definir o espaçamento entre caracteres

O espaçamento de caracteres pode ser aplicado a um Entry definindo a propriedade CharacterSpacing como um valor double:

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

O resultado é que os caracteres no texto exibido pelo Entry são unidades CharacterSpacing independentes do dispositivo separadas e espaçadas.

Observação

O valor da propriedade CharacterSpacing é aplicado ao texto exibido pelas propriedades Text e Placeholder.

Limitar comprimento da entrada

A propriedade MaxLength pode ser usada para limitar o comprimento de entrada permitido para o Entry. Essa propriedade deve ser definida como um número inteiro positivo:

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

Um valor de propriedade MaxLength igual a 0 indica que nenhuma entrada será permitida, e um valor de int.MaxValue, que é o valor padrão de um Entry, significa que não há um limite efetivo para a quantidade de caracteres que podem ser inseridos.

Definir a posição do cursor e o comprimento da seleção de texto

A propriedade CursorPosition pode ser usada para retornar ou definir a posição na qual o próximo caractere será inserido na cadeia de caracteres armazenada na propriedade Text:

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

O valor padrão da propriedade é 0, o CursorPosition que indica que o texto será inserido no início do Entry.

Além disso, a propriedade SelectionLength pode ser usada para retornar ou definir o comprimento da seleção de texto dentro do Entry:

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

O valor padrão da propriedade SelectionLength é 0, o que indica que nenhum texto está selecionado.

Exibir um botão limpar

A propriedade ClearButtonVisibility pode ser usada para controlar se um Entry exibe um botão Limpar, o que permite que o usuário limpe o texto. Essa propriedade deve ser definida como um membro de enumeração ClearButtonVisibility:

• Never indica que um botão Limpar nunca será exibido. Este é o valor padrão para a propriedade de ClearButtonVisibility .
• WhileEditing indica que um botão Limpar será exibido no Entry, enquanto ele tem foco e texto.

O exemplo a seguir mostra a configuração da propriedade:

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

A captura de tela a seguir mostra um Entry no Android com o botão Limpar habilitado:

Texto de transformação

Um Entry pode transformar o uso de letras maiúsculas e minúsculas do seu texto, armazenada na propriedade Text, definindo a propriedade TextTransform como um valor da enumeraçãoTextTransform. Essa enumeração tem quatro valores:

• None indica que o texto não será transformado.
• Default indica que o comportamento padrão da plataforma será usado. Este é o valor padrão da propriedade TextTransform.
• Lowercase indica que o texto será transformado em minúsculas.
• Uppercase indica que o texto será transformado em maiúscula.

O exemplo a seguir mostra a transformação de texto em letras maiúsculas:

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

Obscurecer entrada de texto

Entry fornece a propriedade IsPassword que obscurece visualmente o texto inserido quando ele é definido como true:

<Entry IsPassword="true" />

A captura de tela a seguir mostra um Entry cuja entrada foi obscurecida:

Personalizar o teclado

O teclado de entrada tátil que aparece quando os usuários interagem com um Entry pode ser programado por meio da propriedade Keyboard, para uma das seguintes propriedades da classeKeyboard:

• Chat – usado para mensagens de texto e lugares em que os emojis são úteis.
• Default – o teclado padrão.
• Email – usado ao inserir endereços de email.
• Numeric – usado ao inserir números.
• Plain – usado ao inserir texto, sem nenhum KeyboardFlags especificado.
• Telephone – usado ao inserir números de telefone.
• Text – usado ao inserir texto.
• Url – usado para inserir caminhos de arquivos e endereços web.

O exemplo a seguir mostra a configuração da propriedade Keyboard:

<Entry Keyboard="Chat" />

A classe Keyboard também tem um método de fábrica Create que pode ser usado para personalizar um teclado especificando o comportamento de capitalização, de verificação ortográfica e de sugestão. Os valores de enumeração KeyboardFlags são especificados como argumentos para o método, e um Keyboard personalizado é retornado. A enumeração KeyboardFlags contém os seguintes valores:

• None – nenhum recurso é adicionado ao teclado.
• CapitalizeSentence – indica que as primeiras letras das primeiras palavras de cada frase serão automaticamente maiúsculas.
• Spellcheck – indica que a verificação ortográfica será executada no texto digitado.
• Suggestions – indica que os preenchimentos de palavra sugerida será realizado no texto digitado.
• CapitalizeWord – indica que a primeira letra de cada palavra será automaticamente maiúscula.
• CapitalizeCharacter – indica que todos os caracteres serão automaticamente colocados em maiúsculas.
• CapitalizeNone – indica que não ocorrerá nenhuma capitalização automática ocorrerá.
• All – indica que a verificação ortográfica, os preenchimentos de palavra sugerida e a capitalização de frases ocorrerão no texto digitado.

O seguinte exemplo de código XAML mostra como personalizar o Keyboard padrão para oferecer preenchimentos de palavra sugerida e capitalizar todos os caracteres inseridos:

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

Este é o código C# equivalente:

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

Personalizar a tecla de retorno

A aparência da chave de retorno no teclado de entrada tátil, que é exibida quando um Entry tem foco, pode ser personalizada definindo a propriedade ReturnType como um valor da enumeração ReturnType:

• Default – indica que nenhuma chave de retorno específica é necessária e que o padrão da plataforma será usado.
• Done – indica uma chave de retorno “Concluído”.
• Go – indica uma tecla de retorno “Go”.
• Next – indica uma chave de retorno “Avançar”.
• Search – indica uma chave de retorno “Pesquisar”.
• Send – indica uma chave de retorno “Enviar”.

O exemplo XAML a seguir mostra como definir a chave de retorno:

<Entry ReturnType="Send" />

Observação

A aparência exata da chave de retorno depende da plataforma. No iOS, a chave de retorno é um botão baseado em texto. No entanto, no Android e no Windows, a chave de retorno é um botão baseado em ícone.

Quando a tecla Returné pressionada, o evento Completed é acionado e qualquer ICommand especificado pela propriedade ReturnCommand é executado. Além disso, qualquer object especificada pela propriedade ReturnCommandParameter será passada para o ICommand como um parâmetro. Para obter mais informações sobre comandos, consulte Comando.

Ocultar e mostrar o teclado de entrada tátil

A classe SoftInputExtensions, no namespace Microsoft.Maui, oferece uma série de métodos de extensão que facilitam a interação com o teclado de entrada tátil em controles dão surporte à entrada de texto. A classe define os métodos a seguir:

• IsSoftInputShowing, que verifica se o dispositivo está mostrando o teclado de entrada tátil.
• HideSoftInputAsync, que tentará ocultar o teclado de entrada tátil se ele estiver visível.
• ShowSoftInputAsync, que tentará mostra o teclado de entrada tátil se ele estiver oculto.

O exemplo a seguir mostra como ocultar o teclado de entrada tátil em um Entry chamado entry, caso esteja visível:

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

Habilitar e desabilitar a verificação ortográfica

A propriedade IsSpellCheckEnabled controla se a verificação ortográfica está habilitada. Por padrão, essa propriedade é definida como true. À medida que os usuários inserem o texto, os erros ortográficos são destacados.

No entanto, em alguns cenários de entrada de texto, como ao inserir um nome de usuário, a verificação ortográfica fornece uma experiência negativa e deve ser desabilitada definindo a propriedade IsSpellCheckEnabled como false:

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

Observação

Quando a propriedade IsSpellCheckEnabled estiver definida como false, e um teclado personalizado não está em uso, o corretor ortográfico nativo será desabilitado. No entanto, se um Keyboard que desabilita a verificação ortográfica, como Keyboard.Chat, estiver definido, a propriedade IsSpellCheckEnabled será ignorada. Assim, a propriedade não pode ser usada para habilitar o corretor ortográfico em um Keyboard que o desabilite explicitamente.

Habilitar e desabilitar a previsão de texto

A propriedade IsTextPredictionEnabled controla se a previsão de texto e a correção automática de texto estão habilitadas. Por padrão, essa propriedade é definida como true. À medida que os usuários inserem texto, as previsões de palavras são apresentadas.

Entretanto, em alguns cenários de entrada de texto, como ao inserir um nome de usuário, a previsão de texto e a correção automática do texto podem causar uma experiência negativa e, portanto, devem ser desabilitadas definindo a propriedade IsTextPredictionEnabled como false:

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

Observação

Quando a propriedade IsTextPredictionEnabled é definida como false e um teclado personalizado não está em uso, a previsão de texto e a correção automática de texto são desabilitadas. No entanto, se um Keyboard foi configurado para desabilitar a previsão de texto, a propriedade IsTextPredictionEnabled será ignorada. Assim, a propriedade não pode ser usada para habilitar a previsão de texto em um Keyboard que o desabilite explicitamente.

Impedir a entrada de texto

Os usuários podem ser impedidos de modificar o texto em um Entry definindo a propriedade IsReadOnly como true:

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

Observação

A propriedade IsReadonly não modifica a aparência visual de um Entry, diferentemente da propriedade IsEnabled, que também altera a aparência visual do Entry para a cor cinza.