Editor

OEditor .NET Multi-Platform App UI (.NET MAUI) permite que você insira e edite várias linhas de texto.

Editor define as propriedades a seguir:

• AutoSize, do tipo EditorAutoSizeOption, define se o editor irá alterar o tamanho para se adaptar à entrada dos usuários. Por padrão, o editor não faz o dimensionamento automático.
• HorizontalTextAlignment, do tipo TextAlignment, define o alinhamento horizontal do texto.
• 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, Editor define um evento Completed, que é gerado quando os usuários finaliza, o texto no Editor com a chave de retorno.

Editor é 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 Editor 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 Editor, consulte Fontes.

Criar um Editor

O seguinte exemplo mostra como criar um Editor:

<Editor x:Name="editor"
        Placeholder="Enter your response here"
        HeightRequest="250"
        TextChanged="OnEditorTextChanged"
        Completed="OnEditorCompleted" />

Este é o código C# equivalente:

Editor editor = new Editor { Placeholder = "Enter text", HeightRequest = 250 };
editor.TextChanged += OnEditorTextChanged;
editor.Completed += OnEditorCompleted;

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

É 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 Editor muda, e o evento TextChangedEventArgs fornece o texto antes e depois da alteração por meio das propriedades OldTextValue e NewTextValue:

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

O evento Completed só é gerado no Windows quando os usuários e finalizam a entrada pressionando a tecla Tab no teclado ou focando em outro controle. O manipulador do evento é um manipulador de eventos genérico:

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

Definir o espaçamento entre caracteres

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

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

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

Limitar comprimento da entrada

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

<Editor ... 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 Editor, significa que não há um limite efetivo para a quantidade de caracteres que podem ser inseridos.

Dimensionar automaticamente um Editor

Um Editor pode ser configurado para dimensionar automaticamente seu conteúdo definindo a propriedade Editor.AutoSize como TextChanges, que é um valor da enumeração EditorAutoSizeOption. Essa enumeração possui dois valores:

• Disabled indica que o redimensionamento automático está desabilitado, sendo o valor padrão.
• TextChanges indica que o redimensionamento automático está habilitado.

Isso pode ser feito da seguinte maneira:

<Editor Text="Enter text here"
        AutoSize="TextChanges" />

Quando o redimensionamento automático estiver habilitado, a altura do Editor aumentará conforme os usuários preencherem com texto e diminuirá à medida que os usuários excluírem o texto. Isso pode ser usado para garantir que os objetos Editor em um DataTemplate com um tamanho de CollectionView corretamente.

Texto de transformação

Um Editor 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:

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

Personalizar o teclado

O teclado que aparece quando os usuários interagem com um Editor 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:

<Editor 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:

<Editor>
    <Editor.Keyboard>
        <Keyboard x:FactoryMethod="Create">
            <x:Arguments>
                <KeyboardFlags>Suggestions,CapitalizeCharacter</KeyboardFlags>
            </x:Arguments>
        </Keyboard>
    </Editor.Keyboard>
</Editor>

Este é o código C# equivalente:

Editor editor = new Editor();
editor.Keyboard = Keyboard.Create(KeyboardFlags.Suggestions | KeyboardFlags.CapitalizeCharacter);

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 Editor chamado editor, caso esteja visível:

if (editor.IsSoftInputShowing())
    await editor.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, portanto, deve ser desabilitada definindo a propriedade IsSpellCheckEnabled como false:

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

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:

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

Impedir a entrada de texto

É possível impedir que os usuários modifiquem o texto em um Editor configurando a propriedade IsReadOnly, cujo valor padrão é false, para true:

<Editor Text="This is a read-only Editor"
        IsReadOnly="true" />