Entry

Interfejs użytkownika aplikacji wieloplatformowej platformy .NET (.NET MAUI) Entry umożliwia wprowadzenie i edycję pojedynczej linii tekstu. Ponadto Entry może być używany jako pole hasła.

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

• ClearButtonVisibility, typu ClearButtonVisibility, określa, czy wyświetlany jest przycisk do czyszczenia, co umożliwia użytkownikowi wyczyszczenie tekstu. Wartość domyślna tej właściwości gwarantuje, że nie jest wyświetlany przycisk czyszczenia.
• HorizontalTextAlignment, typu TextAlignment, definiuje wyrównanie poziome tekstu.
• IsPassword, typu bool, określa, czy wpis powinien wizualnie zaciemniać wpisany tekst.
• ReturnCommand, typu ICommand, definiuje polecenie do wykonania po naciśnięciu klawisza Return.
• ReturnCommandParameter, typu object, określa parametr dla ReturnCommand.
• ReturnType, typu ReturnType, określa wygląd przycisku powrotu.
• VerticalTextAlignment, typu TextAlignment, definiuje wyrównanie pionowe tekstu.

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

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

Entry 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 obiekty typu BindableProperty, co oznacza, że mogą być obiektami docelowymi powiązań danych i stylizowane.

Ponadto InputView definiuje zdarzenie TextChanged, które jest zgłaszane, gdy tekst w Entry 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 , zobacz .

Wskazówka

System Android dodaje obsługę powiadomień o zmianie wyboru na platformie .NET 10. W systemie Android kontrolka natywna przełącza się z AppCompatEditText na MauiAppCompatEditText, umożliwiając śledzenie zmian wyboru dla elementu Entry. W miarę zmiany zaznaczenia właściwości 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:

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

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

Tworzenie wpisu

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

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

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

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

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

Zrzut ekranu przedstawiający podstawowy wpis 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 Entry zmienia się, a TextChangedEventArgs podają tekst przed i po zmianie za pomocą właściwości OldTextValue oraz NewTextValue:

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

Zdarzenie Completed jest zgłaszane, gdy użytkownik zakończy dane wejściowe, naciskając klawisz Return na klawiaturze lub klawisz Tab w systemie Windows. Procedura obsługi zdarzenia to ogólny program obsługi zdarzeń:

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

Po uruchomieniu Completed każde ICommand określone przez właściwość ReturnCommand jest wykonywane, z object podanym przez właściwość ReturnCommandParameter jako parametr do ReturnCommand.

Note

Klasa VisualElement, która znajduje się w Entry hierarchii dziedziczenia, ma również zdarzenia Focused i Unfocused.

Ustawianie odstępów między znakami

Odstępy między znakami można zastosować do obiektu Entry, ustawiając właściwość CharacterSpacing na wartość double:

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

Wynikiem jest to, że znaki w tekście wyświetlanym przez Entry są oddzielone CharacterSpacing jednostkami niezależnymi 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

Można użyć właściwości MaxLength w celu ograniczenia dopuszczalnej długości danych wejściowych dla Entry. Ta właściwość powinna być ustawiona na dodatnią liczbę całkowitą:

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

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

Ustawianie położenia kursora i długości zaznaczenia tekstu

Właściwość CursorPosition może służyć do zwracania lub ustawiania położenia, w którym następny znak zostanie wstawiony do ciągu przechowywanego w właściwości Text.

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

Domyślna wartość właściwości CursorPosition to 0, co oznacza, że tekst zostanie wstawiony na początku Entry.

Ponadto właściwość SelectionLength może służyć do zwracania lub ustawiania długości zaznaczenia tekstu w obiekcie Entry:

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

Wartość domyślna właściwości SelectionLength to 0, co oznacza, że nie wybrano żadnego tekstu.

Wyświetl przycisk Wyczyść

Właściwość ClearButtonVisibility może być używana do kontrolowania, czy w Entry jest wyświetlany przycisk do czyszczenia, który pozwala użytkownikowi wyczyścić tekst. Ta właściwość powinna być ustawiona na członek wyliczenia ClearButtonVisibility.

• Never wskazuje, że przycisk wyczyść nigdy nie będzie wyświetlany. Jest to wartość domyślna dla właściwości ClearButtonVisibility.
• WhileEditing wskazuje, że jasny przycisk zostanie wyświetlony w Entry w momencie, gdy ma on fokusa i zawiera tekst.

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

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

Poniższy zrzut ekranu przedstawia Entry w systemie Android z włączoną funkcją przycisku czyszczenia:

Przekształcanie tekstu

Obiekt Entry może przekształcić wielkość liter tekstu przechowywanego we właściwości Text, ustawiając właściwość TextTransform na wartość 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:

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

Niejasny wpis tekstowy

Entry udostępnia właściwość IsPassword, która wizualnie zaciemnia wprowadzony tekst, gdy jest ustawiona na wartość true:

<Entry IsPassword="true" />

Poniższy zrzut ekranu przedstawia Entry, którego dane wejściowe zostały zasłonięte:

Dostosowywanie klawiatury

Klawiatura ekranowa, która jest wyświetlana, gdy użytkownicy wchodzą w interakcję z Entry, może być ustawiona programowo poprzez właściwość 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.

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

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

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

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

Dostosowywanie klucza powrotnego

Wygląd klawisza Enter na miękkiej klawiaturze wirtualnej, która jest wyświetlana, gdy fokus jest aktywny na Entry, można dostosować, ustawiając właściwość ReturnType na wartość z wyliczenia ReturnType.

• Default – wskazuje, że nie jest wymagany żaden określony klucz powrotny i że zostanie użyta wartość domyślna platformy.
• Done — wskazuje klawisz zwracania "Gotowe".
• Go — oznacza klawisz powrotu "Go".
• Next — wskazuje klawisz zwrotu "Dalej".
• Search — wskazuje klawisz powrotu "Wyszukaj".
• Send – wskazuje klawisz Enter "Send".

W poniższym przykładzie XAML pokazano, jak ustawić klucz zwrotny:

<Entry ReturnType="Send" />

Note

Dokładny wygląd klucza zwrotnego zależy od platformy. W systemie iOS klucz zwrotny jest przyciskiem opartym na tekście. Jednak w systemach Android i Windows klucz zwrotny jest przyciskiem opartym na ikonach.

Po naciśnięciu Return zdarzenie zostanie wywołane i zostanie wykonane dowolne ICommand określone przez właściwość ReturnCommand. Ponadto każdy object określony przez ReturnCommandParameter właściwość zostanie przekazany do ICommand jako parametr. Aby uzyskać więcej informacji na temat poleceń, zapoznaj się z sekcją Commanding (Polecenia).

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ę ekranową dla Entry o nazwie entry, jeśli jest aktualnie wyświetlana.

if (entry.IsSoftInputShowing())
    await entry.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 zapewnia negatywne doświadczenie użytkownika i powinno zostać wyłączone przez ustawienie właściwości IsSpellCheckEnabled na false.

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

<Entry ... 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 Entry poprzez ustawienie właściwości IsReadOnly na true.

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

Note

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