Editor

Interfejs użytkownika aplikacji wieloplatformowej platformy .NET (.NET MAUI) Editor umożliwia wprowadzanie i edytowanie wielu wierszy tekstu.

Editor definiuje następujące właściwości:

• AutoSize, typu EditorAutoSizeOption, określa, czy edytor zmieni rozmiar, aby uwzględnić dane wejściowe użytkownika. Domyślnie edytor nie ma automatycznego rozmiaru.
• HorizontalTextAlignment, typu TextAlignment, definiuje wyrównanie poziome tekstu.
• VerticalTextAlignment, typu TextAlignment, definiuje wyrównanie pionowe tekstu.

Te właściwości są wspierane przez BindableProperty obiekty, co oznacza, że mogą być celami powiązań danych oraz mogą być stylizowane.

Ponadto Editor definiuje zdarzenie Completed, które jest wywoływane, gdy użytkownik finalizuje tekst w obiekcie Editor za pomocą klawisza Enter.

Editor pochodzi z InputView klasy, z której dziedziczy następujące właściwości:

• CharacterSpacing, typu double, ustawia odstępy między znakami w zawartości tekstowej, w tym wprowadzony przez użytkownika lub wyświetlany tekst i tekst zastępczy.
• CursorPosition, typu int, definiuje pozycję kursora w edytorze.
• FontAttributes, typu FontAttributes, określa styl tekstu.
•   , typu , określa, czy tekst będzie odzwierciedlać preferencje skalowania ustawione w systemie operacyjnym. Wartość domyślna tej właściwości to true.
• , typu , definiuje rodzinę czcionek.
• FontSize, typu double, definiuje rozmiar czcionki.
• IsReadOnly, typu bool, określa, czy użytkownik powinien być uniemożliwiony w modyfikacji tekstu. Wartość domyślna tej właściwości to false.
• IsSpellCheckEnabled, typu bool, steruje, czy sprawdzanie pisowni jest włączone.
• IsTextPredictionEnabled, typu bool, określa, czy jest włączone przewidywanie i automatyczna korekta tekstu.
• Keyboard, określa typ Keyboard, miękkiej klawiatury wejściowej wyświetlanej podczas wprowadzania tekstu.
• MaxLength, typu int, definiuje maksymalną długość wejścia.
• Placeholder typu string definiuje tekst wyświetlany, gdy element sterujący jest pusty.
• PlaceholderColor, typu Color, definiuje kolor tekstu zastępczego.
• SelectionLength, typu int, reprezentuje długość zaznaczonego tekstu w kontroli.
• Text, typu string, definiuje tekst wprowadzany do kontrolki.
• , typu , definiuje kolor wprowadzonego tekstu.
• TextTransform, typu TextTransform, określa sposób zapisu wielkich i małych liter wprowadzonego tekstu.

Te właściwości są wspierane przez BindableProperty obiekty, co oznacza, że mogą być celami powiązań danych oraz mogą być stylizowane.

Ponadto InputView definiuje TextChanged zdarzenie Editor, które jest wywoływane, gdy tekst w się zmienia. Obiekt towarzyszący zdarzeniu TextChangedEventArgs ma właściwości TextChanged i NewTextValue, które określają odpowiednio nowy i stary tekst.

Aby uzyskać informacje na temat określania czcionek na Editor, zobacz Czcionki.

Wskazówka

W systemie Android, .NET 10 przełącza widok natywny dla Editor na MauiAppCompatEditText, co umożliwia śledzenie zmian wyboru. Gdy zaznaczenie się zmienia, CursorPosition i SelectionLength są aktualizowane, aby można było reagować na zmiany zaznaczenia.

Aby obserwować aktualizacje wyboru, monitoruj zmiany właściwości dla CursorPosition i SelectionLength:

editor.PropertyChanged += (s, e) =>
{
    if (e.PropertyName == nameof(Editor.CursorPosition) ||
        e.PropertyName == nameof(Editor.SelectionLength))
    {
        var start = editor.CursorPosition;
        var length = editor.SelectionLength;
        // Respond to selection change (Android .NET 10+)
    }
};

Alternatywnie dane wiążą właściwości i reagują na model widoku.

Tworzenie edytora

W poniższym przykładzie pokazano, jak utworzyć Editor:

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

Równoważny kod języka C# to:

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

Poniższy zrzut ekranu przedstawia wynikowy element w systemie Android:

Note

W systemie iOS klawiatura ekranowa może zasłaniać pole wprowadzania tekstu, kiedy pole znajduje się blisko dolnej krawędzi ekranu, co utrudnia wprowadzanie tekstu. Jednak w aplikacji .NET MAUI dla systemu iOS strony automatycznie przewijają się, gdy klawiatura ekranowa zasłania pole wprowadzania tekstu, aby było ono powyżej klawiatury. Metodę KeyboardAutoManagerScroll.Disconnect w przestrzeni nazw Microsoft.Maui.Platform można wywołać, aby wyłączyć to domyślne zachowanie. Metodę KeyboardAutoManagerScroll.Connect można wywołać, aby ponownie włączyć zachowanie po jego wyłączeniu.

Dostęp do wprowadzonego tekstu można uzyskać, odczytując właściwość Text, a zdarzenia TextChanged i Completed sygnalizują, że tekst został zmieniony lub ukończony.

Zdarzenie TextChanged jest wywoływane, gdy tekst w Editor zmienia się, a TextChangedEventArgs podaje tekst przed i po zmianie za pomocą właściwości OldTextValue i NewTextValue:

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

The Completed zdarzenie jest wywoływane tylko w systemie Windows, gdy użytkownik zakończył wprowadzanie, naciskając Tab na klawiaturze lub przenosząc fokus na inną kontrolkę. Procedura obsługi zdarzenia to ogólny program obsługi zdarzeń:

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

Ustawianie odstępów między znakami

Odstępy między znakami można zastosować do elementu Editor przez ustawienie właściwości CharacterSpacing na wartość double:

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

Wynik jest taki, że znaki w tekście wyświetlanym przez Editor są oddzielone od siebie o CharacterSpacing jednostki niezależne od urządzenia.

Note

Wartość właściwości CharacterSpacing jest stosowana do tekstu wyświetlanego przez właściwości Text i Placeholder.

Ogranicz długość danych wejściowych

Właściwość MaxLength może być użyta do ograniczenia długości wejściowej dozwolonej dla Editor. Ta właściwość powinna być ustawiona na dodatnią liczbę całkowitą:

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

Wartość właściwości równa 0 wskazuje, że żadne dane wejściowe nie będą dozwolone, a wartość int.MaxValue, która jest wartością domyślną elementu Editor, wskazuje, że nie ma obowiązującego limitu liczby znaków, które mogą zostać wprowadzone.

Automatyczne ustawianie rozmiaru edytora

Element Editor można ustawić tak, aby dostosowywał rozmiar do swojej zawartości, ustawiając właściwość Editor.AutoSize na wartość TextChanges, która jest wartością wyliczenia EditorAutoSizeOption. To wyliczenie ma dwie wartości:

• Disabled wskazuje, że automatyczna zmiana rozmiaru jest wyłączona i jest wartością domyślną.
• TextChanges wskazuje, że włączono automatyczną zmianę rozmiaru.

Można to zrobić w następujący sposób:

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

Po włączeniu automatycznego zmieniania rozmiaru wysokość Editor zwiększy się, gdy użytkownik wypełni go tekstem, a wysokość zmniejszy się, gdy użytkownik usunie tekst. Może to służyć do zapewnienia, że obiekty w Editor są prawidłowo rozmiarowane w DataTemplate o CollectionView.

Important

Jeśli właściwość Editor zostanie ustawiona, element HeightRequest nie będzie automatycznie zmieniać rozmiaru.

Przekształcanie tekstu

Obiekt Editor może przekształcić wielkość liter tekstu przechowywanego we właściwości Text, ustawiając właściwość TextTransform na wartość z wyliczenia TextTransform. Ta wyliczenie ma cztery wartości:

• None wskazuje, że tekst nie będzie przekształcony.
• Default wskazuje, że będzie używane domyślne zachowanie platformy. Jest to wartość domyślna właściwości TextTransform.
• Lowercase wskazuje, że tekst zostanie przekształcony na małe litery.
• Uppercase oznacza, że tekst zostanie przekształcony na drukowane litery.

W poniższym przykładzie pokazano przekształcanie tekstu na wielkie litery:

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

Dostosowywanie klawiatury

Klawiatura, która jest prezentowana, gdy użytkownicy wchodzą w interakcję z `Editor`, może być ustawiona programowo przy użyciu właściwości `Keyboard`, na jedną z następujących właściwości klasy `Keyboard`.

• Chat — używany do pisania wiadomości tekstowych i miejsc, w których emoji są przydatne.
• Default – klawiatura domyślna.
• Email — używane podczas wprowadzania adresów e-mail.
• Numeric — używane podczas wprowadzania liczb.
• Plain — używany podczas wprowadzania tekstu bez żadnego określonego KeyboardFlags.
• Telephone – używane podczas wprowadzania numerów telefonicznych.
• Text – używany podczas wprowadzania tekstu.
• Url — służy do wprowadzania ścieżek plików i adresów internetowych.

W poniższym przykładzie pokazano ustawienie właściwości Keyboard.

<Editor Keyboard="Chat" />

Klasa Keyboard ma również metodę fabryczną Create, która może być użyta do dostosowania klawiatury przez określenie kapitalizacji, sprawdzania pisowni i sposobu działania sugestii. KeyboardFlags Wartości wyliczenia są określane jako argumenty metody, z czego zwracana jest niestandardowa Keyboard. Wyliczenie KeyboardFlags zawiera następujące wartości:

• None — do klawiatury nie dodano żadnych funkcji.
• CapitalizeSentence – wskazuje, że pierwsza litera pierwszego wyrazu każdego wprowadzonego zdania zostanie automatycznie zamieniona na wielką.
• Spellcheck — wskazuje, że sprawdzanie pisowni będzie wykonywane na wprowadzonym tekście.
• Suggestions – wskazuje, że autouzupełnianie będzie oferowane dla wprowadzonego tekstu.
• CapitalizeWord — wskazuje, że pierwsza litera każdego wyrazu będzie automatycznie wielką literą.
• CapitalizeCharacter — wskazuje, że każdy znak będzie automatycznie wielką literą.
• CapitalizeNone — wskazuje, że nie nastąpi automatyczna kapitalizacja.
• All — wskazuje, że w wprowadzonym tekście zostanie zastosowane sprawdzanie pisowni, uzupełnianie wyrazów oraz rozpoczynanie zdań wielką literą.

Poniższy przykład kodu XAML pokazuje, jak dostosować domyślny Keyboard, aby oferować uzupełnianie wyrazów i pisać wielką literą każdy wprowadzony znak:

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

Równoważny kod języka C# to:

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

Ukryj i pokaż miękką klawiaturę wejściową

Klasa SoftInputExtensions w przestrzeni nazw Microsoft.Maui udostępnia szereg metod rozszerzeń, które wspierają interakcję z klawiaturą programową na kontrolkach obsługujących wprowadzanie tekstu. Klasa definiuje następujące metody:

• IsSoftInputShowing, który sprawdza, czy na urządzeniu jest aktualnie wyświetlana klawiatura ekranowa.
• HideSoftInputAsync, który podejmie próbę ukrycia miękkiej klawiatury wejściowej, jeśli jest ona obecnie wyświetlana.
• ShowSoftInputAsync, który podejmie próbę wyświetlenia klawiatury ekranowej, jeśli jest obecnie ukryta.

W poniższym przykładzie pokazano, jak ukryć klawiaturę wprowadzania tekstu dla kontrolki typu Editor, nazwanej editor, jeśli jest ona obecnie wyświetlana.

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

Włączanie i wyłączanie sprawdzania pisowni

Właściwość IsSpellCheckEnabled określa, czy sprawdzanie pisowni jest włączone. Domyślnie właściwość jest ustawiona na true. Gdy użytkownik wprowadza tekst, wskazywane są błędy pisowni.

Jednak w przypadku niektórych scenariuszy wprowadzania tekstu, takich jak wprowadzenie nazwy użytkownika, sprawdzanie pisowni powoduje negatywne doświadczenia i dlatego należy je wyłączyć, ustawiając IsSpellCheckEnabled na false:

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

Note

Gdy właściwość IsSpellCheckEnabled jest ustawiona na false, a niestandardowa klawiatura nie jest używana, natywny moduł sprawdzania pisowni zostanie wyłączony. Jeśli jednak ustawiono Keyboard, które wyłącza sprawdzanie pisowni, takie jak Keyboard.Chat, właściwość IsSpellCheckEnabled jest ignorowana. W związku z tym nie można użyć właściwości w celu włączenia sprawdzania pisowni dla Keyboard, które jawnie wyłącza tę funkcję.

Włączanie i wyłączanie przewidywania tekstu

Właściwość IsTextPredictionEnabled określa, czy włączono przewidywanie tekstu i automatyczną korektę tekstu. Domyślnie właściwość jest ustawiona na true. Gdy użytkownik wprowadza tekst, wyświetlane są przewidywania wyrazów.

Jednak w przypadku niektórych scenariuszy wprowadzania tekstu, takich jak wprowadzanie nazwy użytkownika, przewidywanie tekstu i automatyczna korekta tekstu mogą powodować negatywne doświadczenia i powinny być wyłączone przez ustawienie właściwości IsTextPredictionEnabled na false.

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

Note

Gdy właściwość IsTextPredictionEnabled jest ustawiona na false, a niestandardowa klawiatura nie jest używana, przewidywanie tekstu i automatyczna korekta tekstu są wyłączone. Jeśli jednak ustawiono Keyboard, które wyłącza przewidywanie tekstu, właściwość IsTextPredictionEnabled jest ignorowana. W związku z tym nie można użyć właściwości do włączenia przewidywania tekstu dla Keyboard, który jawnie to wyłącza.

Zapobieganie wpisowi tekstowemu

Użytkownikom można uniemożliwić modyfikowanie tekstu w Editor przez ustawienie właściwości IsReadOnly, która ma domyślną wartość false, na true.

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

Note

Właściwość IsReadOnly nie zmienia wyglądu wizualnego Editor, w przeciwieństwie do właściwości IsEnabled, która zmienia również wygląd wizualny Editor na szary.

Zakończenia linii (tylko w systemie Windows)

Gdy użytkownik dodaje wiele wierszy w kontrolce, Text właściwość będzie zawierać tylko "\r" dla zakończenia wiersza, a nie "\r\n", co jest normalne w systemie Windows. Nie ma właściwości, aby zmienić to zachowanie, ale tekst można zmienić w celu dodania tego specyficznego zakończenia linii w razie potrzeby.

#if WINDOWS
if (EditorText.Text.Contains("\r"))
{
    var textWithWindowsLineBreaks = EditorText.Text.Replace("\r", Environment.NewLine);

    // Do something with the text that has Windows line breaks
}
#endif

Note

Nie przypisuj zaktualizowanego tekstu do Text właściwości kontrolki. Jeśli tak się stanie, oryginalne zakończenie wiersza ("\r") zostanie przywrócone.