Udostępnij za pośrednictwem

Wpis

  • Artykuł

Interfejs użytkownika aplikacji wieloplatformowej platformy .NET (.NET MAUI) Entry umożliwia wprowadzanie i edytowanie pojedynczego wiersza tekstu. Ponadto Entry element może być używany jako pole hasła.

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

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

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

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

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 we wprowadzonym tekście.
  • CursorPosition, typu int, definiuje położenie kursora w edytorze.
  • FontAttributes, typu FontAttributes, określa styl tekstu.
  • FontAutoScalingEnabled, typu bool, określa, czy tekst będzie odzwierciedlać preferencje skalowania ustawione w systemie operacyjnym. Wartość domyślna tej właściwości to true.
  • FontFamily, typu string, definiuje rodzinę czcionek.
  • FontSize, typu double, definiuje rozmiar czcionki.
  • IsReadOnly, typu bool, określa, czy użytkownik nie powinien modyfikować tekstu. Wartość domyślna tej właściwości to false.
  • IsSpellCheckEnabled, typu bool, określa, czy sprawdzanie pisowni jest włączone.
  • IsTextPredictionEnabled, typu bool, określa, czy włączono przewidywanie tekstu i automatyczną korektę tekstu.
  • Keyboard, typu Keyboard, określa miękką klawiaturę wejściową wyświetlaną podczas wprowadzania tekstu.
  • MaxLength, typu int, definiuje maksymalną długość danych wejściowych.
  • Placeholder, typu string, definiuje tekst wyświetlany, gdy kontrolka jest pusta.
  • PlaceholderColor, typu Color, definiuje kolor tekstu zastępczego.
  • SelectionLength, typu int, reprezentuje długość zaznaczonego tekstu w kontrolce.
  • Text, typu string, definiuje tekst wprowadzony w kontrolce.
  • TextColor, typu Color, definiuje kolor wprowadzonego tekstu.
  • TextTransform, typu TextTransform, określa wielkość liter wprowadzonego tekstu.

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

Ponadto InputView definiuje TextChanged zdarzenie, które jest zgłaszane, gdy tekst w Entry zmianach. Obiekt TextChangedEventArgs , który towarzyszy TextChanged zdarzeniu, ma NewTextValue właściwości i OldTextValue , które określają odpowiednio nowy i stary tekst.

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

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.

Uwaga

W systemie iOS klawiatura wprowadzania nietrwałego może obejmować pole wprowadzania tekstu, gdy pole znajduje się w dolnej części ekranu, co utrudnia wprowadzanie tekstu. Jednak w aplikacji .NET MAUI dla systemu iOS strony automatycznie przewijają się, gdy klawiatura nietrwała będzie obejmować pole wprowadzania tekstu, aby pole było powyżej klawiatury nietrwałej wprowadzania. Metodę KeyboardAutoManagerScroll.Disconnect w Microsoft.Maui.Platform przestrzeni nazw można wywołać, aby wyłączyć to domyślne zachowanie. Metodę KeyboardAutoManagerScroll.Connect można wywołać, aby ponownie włączyć zachowanie po jej wyłączeniu.

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

Zdarzenie TextChanged jest wywoływane, gdy tekst w Entry zmianach i TextChangedEventArgs podaj tekst przed i po zmianie za pomocą OldTextValue właściwości i 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 Return na klawiaturze lub naciskając 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 zdarzenia wszystkie ICommand określone przez ReturnCommand właściwość są wykonywane, z object określonym przez ReturnCommandParameter właściwość przekazywaną ReturnCommanddo właściwości .

Uwaga

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

Ustawianie odstępów między znakami

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

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

Wynikiem jest to, że znaki w tekście wyświetlanym przez Entry element są oddzielone CharacterSpacing od siebie jednostkami niezależnymi od urządzenia.

Uwaga

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

Ogranicz długość danych wejściowych

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

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

MaxLength Wartość właściwości 0 wskazuje, że żadne dane wejściowe nie będą dozwolone, a wartość int.MaxValue, która jest wartością domyślną Entryelementu , wskazuje, że nie ma obowiązującego limitu liczby 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 Text we właściwości :

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

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

Ponadto SelectionLength właściwość 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 SelectionLength właściwości to 0, co oznacza, że nie wybrano żadnego tekstu.

Wyświetlanie przycisku wyczyść

Właściwość ClearButtonVisibility może służyć do kontrolowania, czy jest Entry wyświetlany przycisk wyczyść, co umożliwia użytkownikowi wyczyszczenie tekstu. Ta właściwość powinna być ustawiona na element członkowski ClearButtonVisibility wyliczenia:

  • Never wskazuje, że przycisk wyczyść nigdy nie będzie wyświetlany. Jest to wartość domyślna ClearButtonVisibility właściwości .
  • WhileEditing wskazuje, że w elemecie Entryzostanie wyświetlony jasny przycisk , który ma fokus i tekst.

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

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

Poniższy zrzut ekranu przedstawia w Entry systemie Android z włączonym przyciskiem wyczyść:

Zrzut ekranu przedstawiający podstawowy wpis z wyraźnym przyciskiem w systemie Android.

Przekształcanie tekstu

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

  • None wskazuje, że tekst nie zostanie przekształcony.
  • Default wskazuje, że będzie używane domyślne zachowanie platformy. Jest to wartość domyślna TextTransform właściwości.
  • Lowercase wskazuje, że tekst zostanie przekształcony w małe litery.
  • Uppercase wskazuje, że tekst zostanie przekształcony na wielkie 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

EntryIsPassword Udostępnia właściwość, która wizualnie zaciemnia tekst wprowadzony, gdy jest ustawiona na truewartość :

<Entry IsPassword="true" />

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

Zrzut ekranu przedstawiający podstawowy wpis z parametrem IsPassword ustawionym na wartość true.

Dostosowywanie klawiatury

Klawiatura nietrwała wprowadzania, która jest wyświetlana, gdy użytkownicy wchodzą w interakcję z elementem Entry , mogą być ustawiane programowo za pośrednictwem Keyboard właściwości na jedną z następujących właściwości klasy Keyboard :

  • Chat — używany do tworzenia tekstu 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 telefonów.
  • 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 Keyboard właściwości:

<Entry Keyboard="Chat" />

Klasa Keyboard ma również metodę Create fabryki, która może służyć do dostosowywania klawiatury przez określenie wielkich liter, sprawdzania pisowni i zachowania sugestii. KeyboardFlags Wartości wyliczenia są określane jako argumenty metody, przy czym zwracana jest niestandardowa Keyboard wartość . Wyliczenie KeyboardFlags zawiera następujące wartości:

  • None — do klawiatury nie są dodawane żadne funkcje.
  • CapitalizeSentence – wskazuje, że pierwsza litera pierwszego wyrazu każdego wprowadzonego zdania zostanie automatycznie wpisana literą.
  • Spellcheck — wskazuje, że sprawdzanie pisowni będzie wykonywane na wprowadzonym tekście.
  • Suggestions — wskazuje, że uzupełnianie wyrazów będzie oferowane dla wprowadzonego tekstu.
  • CapitalizeWord — wskazuje, że pierwsza litera każdego wyrazu będzie automatycznie wielkich liter.
  • CapitalizeCharacter — wskazuje, że każdy znak będzie automatycznie wielkich liter.
  • CapitalizeNone — wskazuje, że nie nastąpi automatyczna kapitalizowanie.
  • All — wskazuje, że w wprowadzonym tekście wystąpi sprawdzanie pisowni, uzupełnianie wyrazów i wielkie litery zdań.

Poniższy przykład kodu XAML pokazuje, jak dostosować wartość domyślną Keyboard , aby oferować uzupełnianie wyrazów i wielką literę każdego wprowadzonego znaku:

<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 zwrotnego na klawiaturze nietrwałej wprowadzania, która jest wyświetlana po Entry ustawieniu fokusu, można dostosować, ustawiając ReturnType właściwość na wartość ReturnType wyliczenia:

  • Default — wskazuje, że nie jest wymagany żaden określony klucz powrotny i że zostanie użyta wartość domyślna platformy.
  • Done — wskazuje "Done" return key (Gotowe) zwracany klucz.
  • Go — wskazuje zwrotny "Go".
  • Next — wskazuje zwrotny "Dalej".
  • Search — wskazuje klucz zwrotny "Wyszukaj".
  • Send — wskazuje klucz zwrotny "Wyślij".

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

<Entry ReturnType="Send" />

Uwaga

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 uruchomione i zostanie wykonane dowolne ICommand określone przez ReturnCommand właściwość.Completed Ponadto wszystkie object określone przez ReturnCommandParameter właściwość zostaną przekazane jako ICommand parametr. Aby uzyskać więcej informacji na temat poleceń, zobacz Commanding (Polecenia).

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

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

  • IsSoftInputShowing, który sprawdza, czy urządzenie jest obecnie wyświetlane miękkie klawiatury wejściowej.
  • 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 nietrwałej wprowadzania, jeśli jest ona obecnie ukryta.

W poniższym przykładzie pokazano, jak ukryć klawiaturę wprowadzania nietrwałego Entry na nazwie entry, jeśli jest ona obecnie 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 truewartość . 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 środowisko i powinno zostać wyłączone przez ustawienie IsSpellCheckEnabled właściwości na false:

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

Uwaga

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

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 truewartość . 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 zapewnia negatywne środowisko i powinno być wyłączone przez ustawienie IsTextPredictionEnabled właściwości na false:

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

Uwaga

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

Zapobieganie wpisowi tekstowemu

Użytkownikom można uniemożliwić modyfikowanie tekstu w obiekcie Entry przez ustawienie IsReadOnly właściwości na true:

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

Uwaga

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