Xamarin.Forms Editor

Artigo
07/21/2020

O Editor controle é usado para aceitar entrada de várias linhas.

Definir e ler texto

O Editor, como outras exibições de apresentação de texto, expõe a Text propriedade. Essa propriedade pode ser usada para definir e ler o texto apresentado pelo Editor. O exemplo a seguir demonstra a configuração da Text propriedade em XAML:

<Editor x:Name="editor" Text="I am an Editor" />

No C#:

var editor = new Editor { Text = "I am an Editor" };

Para ler texto, acesse a Text propriedade em C#:

var text = editor.Text;

Definir texto de espaço reservado

O Editor pode ser definido para mostrar texto de espaço reservado quando ele não está armazenando a entrada do usuário. Isso é feito definindo a Placeholder propriedade como um string, e geralmente é usado para indicar o tipo de conteúdo apropriado para o Editor. Além disso, a cor do texto do espaço reservado pode ser controlada definindo a PlaceholderColor propriedade como :Color

<Editor Placeholder="Enter text here" PlaceholderColor="Olive" />

var editor = new Editor { Placeholder = "Enter text here", PlaceholderColor = Color.Olive };

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

var editor = new 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.

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

Este é o código C# equivalente:

Editor editor = new Editor
{
    Text = "This text will be displayed in uppercase.",
    TextTransform = TextTransform.Uppercase
};

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

var editor = new 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.

Espaçamento de caracteres

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

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

Este é o código C# equivalente:

Editor editor = new 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.

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 no código da seguinte maneira:

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

var editor = new Editor { Text = "Enter text here", AutoSize = EditorAutoSizeOption.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.

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.

Isso pode ser feito no XAML da seguinte maneira:

<Editor Keyboard="Chat" />

Este é o código C# equivalente:

var editor = new Editor { Keyboard = Keyboard.Chat };

Exemplos de cada teclado podem ser encontrados em nosso repositório de receitas .

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:

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

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

var editor = new 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" />

var editor = new 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.

Cores

Editor pode ser definido para usar uma cor de plano de fundo personalizada por meio da BackgroundColor propriedade. É necessário um cuidado especial para garantir que as cores sejam utilizáveis em cada plataforma. Como cada plataforma tem padrões diferentes para a cor do texto, talvez seja necessário definir uma cor de plano de fundo personalizada para cada plataforma. Consulte Trabalhando com ajustes de plataforma para obter mais informações sobre como otimizar a interface do usuário para cada plataforma.

No C#:

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        //dark blue on UWP & Android, light blue on iOS
        var editor = new Editor { BackgroundColor = Device.RuntimePlatform == Device.iOS ? Color.FromHex("#A4EAFF") : Color.FromHex("#2c3e50") };
        layout.Children.Add(editor);
    }
}

Em XAML:

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    x:Class="TextSample.EditorPage"
    Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor>
                <Editor.BackgroundColor>
                    <OnPlatform x:TypeArguments="x:Color">
                        <On Platform="iOS" Value="#a4eaff" />
                        <On Platform="Android, UWP" Value="#2c3e50" />
                    </OnPlatform>
                </Editor.BackgroundColor>
            </Editor>
        </StackLayout>
    </ContentPage.Content>
</ContentPage>

Editor com exemplo de BackgroundColor

Certifique-se de que as cores de fundo e texto escolhidas são utilizáveis em cada plataforma e não obscurecem nenhum texto de espaço reservado.

Eventos e interatividade

Editor expõe dois eventos:

TextChanged – gerado quando o texto é alterado no editor. Fornece o texto antes e depois da alteração.
Concluído – gerado quando o usuário tiver terminado a entrada pressionando a tecla return no teclado.

Observação

A VisualElement classe, da qual Entry herda, também tem Focused e Unfocused eventos.

Concluído(a)

O Completed evento é usado para reagir à conclusão de uma interação com um Editorarquivo . Completed é gerado quando o usuário termina a entrada com um campo inserindo a tecla de retorno no teclado (ou pressionando a tecla Tab na UWP). O manipulador para o evento é um manipulador de eventos genérico, levando o remetente e EventArgs:

void EditorCompleted (object sender, EventArgs e)
{
    var text = ((Editor)sender).Text; // sender is cast to an Editor to enable reading the `Text` property of the view.
}

O evento concluído pode ser inscrito em código e XAML:

No C#:

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        var editor = new Editor ();
        editor.Completed += EditorCompleted;
        layout.Children.Add(editor);
    }
}

Em XAML:

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TextSample.EditorPage"
Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor Completed="EditorCompleted" />
        </StackLayout>
    </ContentPage.Content>
</Contentpage>

TextChanged

O TextChanged evento é usado para reagir a uma alteração no conteúdo de um campo.

TextChanged é levantado sempre que o Text das Editor mudanças. O manipulador do evento usa uma instância de TextChangedEventArgs. TextChangedEventArgs fornece acesso aos valores antigos e novos do EditorText via e OldTextValueNewTextValue propriedades:

void EditorTextChanged (object sender, TextChangedEventArgs e)
{
    var oldText = e.OldTextValue;
    var newText = e.NewTextValue;
}

O evento concluído pode ser inscrito em código e XAML:

No código:

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        var editor = new Editor ();
        editor.TextChanged += EditorTextChanged;
        layout.Children.Add(editor);
    }
}

Em XAML:

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TextSample.EditorPage"
Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor TextChanged="EditorTextChanged" />
        </StackLayout>
    </ContentPage.Content>
</ContentPage>

API de Editor

Xamarin.Forms Editor

Definir e ler texto

Definir texto de espaço reservado

Impedir a entrada de texto

Texto de transformação

Limitar comprimento da entrada

Espaçamento de caracteres

Dimensionar automaticamente um Editor

Personalizar o teclado

Habilitar e desabilitar a verificação ortográfica

Habilitar e desabilitar a previsão de texto

Cores

Eventos e interatividade

Concluído(a)

TextChanged

Links relacionados

Recursos adicionais