Share via

Editor

  • Artigo

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:

Captura de tela de um Editor básico 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 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.

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

Observação

Um Editor não se ajustará automaticamente se a propriedade HeightRequest estiver configurada.

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" />

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:

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

É 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" />

Observação

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