Nuta
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować się zalogować lub zmienić katalog.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Kontrolka TextBox umożliwia użytkownikowi wpisywanie tekstu w aplikacji. Zazwyczaj służy do przechwytywania pojedynczego wiersza tekstu, ale można go skonfigurować do przechwytywania wielu wierszy tekstu. Tekst jest wyświetlany na ekranie w prostym, jednolitym formacie zwykłego tekstu.
Pole tekstowe ma wiele funkcji, które mogą uprościć wprowadzanie tekstu. Zawiera znane, wbudowane menu kontekstowe z obsługą kopiowania i wklejania tekstu. Przycisk "Wyczyść wszystko" umożliwia użytkownikowi szybkie usunięcie całego wprowadzonego tekstu. Ma również wbudowane i włączone funkcje sprawdzania pisowni.
Czy jest to właściwa kontrola?
Użyj kontrolki TextBox , aby umożliwić użytkownikowi wprowadzanie i edytowanie niesformatowanych tekstu, na przykład w formularzu. Możesz użyć właściwości Text , aby pobrać i ustawić tekst w polu tekstowym.
Można utworzyć pole tekstowe tylko do odczytu, ale powinno to być stan tymczasowy, warunkowy. Jeśli tekst nigdy nie jest edytowalny, rozważ użycie zamiast tego elementu TextBlock .
Użyj kontrolki PasswordBox , aby zebrać hasło lub inne dane prywatne, takie jak numer ubezpieczenia społecznego. Pole hasła wygląda jak pole do wprowadzania tekstu, z tą różnicą, że zamiast wprowadzonego tekstu wyświetlane są gwiazdki.
Użyj kontrolki AutoSuggestBox , aby umożliwić użytkownikowi wprowadzanie terminów wyszukiwania lub wyświetlanie użytkownikowi listy sugestii do wyboru podczas wpisywania.
Użyj kontrolki RichEditBox do wyświetlania i edytowania plików tekstowych sformatowanych.
Aby uzyskać więcej informacji na temat wybierania odpowiedniej kontrolki tekstu, zobacz artykuł Kontrolki tekstu .
Rekomendacje
- Użyj etykiety lub tekstu zastępczego, jeśli przeznaczenie pola tekstowego nie jest jasne. Etykieta jest widoczna bez względu na to, czy pole wprowadzania tekstu ma wartość. Tekst zastępczy jest wyświetlany wewnątrz pola wprowadzania tekstu i zniknie po wprowadzeniu wartości.
- Nadaj polu tekstowemu odpowiednią szerokość zakresu wartości, które można wprowadzić. Długość słów różni się między językami, dlatego należy wziąć pod uwagę lokalizację, jeśli aplikacja ma być przygotowana na rynek międzynarodowy.
- Pole wprowadzania tekstu jest zwykle jednowierszowe (
TextWrap = "NoWrap"). Kiedy użytkownicy muszą wprowadzić lub edytować długi ciąg znaków, ustaw pole wprowadzania tekstu na format wielowierszowy (TextWrap = "Wrap"). - Ogólnie rzecz biorąc, pole wprowadzania tekstu jest używane do edycji tekstu. Można jednak utworzyć pole tekstowe tylko do odczytu, aby jego zawartość mogła być odczytywana, zaznaczona i kopiowana, ale nie edytowana.
- Jeśli musisz zmniejszyć bałagan w widoku, rozważ utworzenie zestawu pól wejściowych tekstowych wyświetlanych tylko wtedy, gdy pole wyboru sterującego jest zaznaczone. Można również powiązać włączony stan pola wejściowego tekstu z kontrolką, taką jak pole wyboru.
- Zastanów się, jak chcesz, aby pole wprowadzania tekstu zachowywało się, gdy zawiera wartość, a użytkownik go naciągnie. Domyślne zachowanie jest odpowiednie do edytowania wartości, a nie zastępowania jej; punkt wstawiania jest umieszczany między wyrazami, a nic nie jest zaznaczone. Jeśli zamiana jest najczęstszym przypadkiem użycia dla danego pola tekstowego, możesz zaznaczyć cały tekst w chwili, gdy kontrolka przejmuje fokus, a wpisywanie zastępuje zaznaczenie.
Pola wejściowe z jedną linią
Użyj wielu jednowierszowych pól tekstowych, aby zebrać liczne małe fragmenty tekstu. Jeśli pola tekstowe są ze sobą powiązane, pogrupuj je razem.
Uczyń rozmiar jednowierszowych pól tekstowych nieco szerszym niż najdłuższe oczekiwane dane wejściowe. Jeśli tak sprawia, że kontrolka jest zbyt szeroka, rozdziel ją na dwie kontrolki. Można na przykład podzielić pojedyncze pole adresu na "Linia adresu 1" i "Linia adresu 2".
Ustaw maksymalną długość znaków, które można wprowadzić. Jeśli źródło danych zapasowych nie zezwala na długi ciąg wejściowy, ogranicz dane wejściowe i użyj wyskakującego okienka sprawdzania poprawności, aby poinformować użytkowników o osiągnięciu limitu.
Użyj kontrolek wprowadzania tekstu jednowierszowego, aby zebrać małe fragmenty tekstu od użytkowników.
Poniższy przykład przedstawia jednowierszowe pole tekstowe do przechwytywania odpowiedzi na pytanie zabezpieczające. Oczekuje się, że odpowiedź będzie krótka, a więc jednowierszowe pole tekstowe jest odpowiednie tutaj.
Użyj zestawu krótkich, stałych, jednowierszowych kontrolek wprowadzania tekstu, aby wprowadzić dane w określonym formacie.
Użyj jednowierszowego pola tekstowego bez ograniczeń do wprowadzania lub edytowania ciągów w połączeniu z przyciskiem polecenia, który pomaga użytkownikom wybrać prawidłowe wartości.
Kontrolki wprowadzania tekstu wielowierszowego
Podczas tworzenia pola tekstowego z formatowaniem, podaj przyciski stylów i zaimplementuj ich działania.
Użyj czcionki zgodnej ze stylem aplikacji.
Ustaw wysokość kontrolki tekstu wystarczająco wysoką, aby pomieścić typowe wpisy.
Podczas przechwytywania długich zakresów tekstu z maksymalną liczbą znaków lub wyrazów użyj zwykłego pola tekstowego i podaj licznik działający na żywo, aby pokazać użytkownikowi, ile znaków lub wyrazów pozostało przed osiągnięciem limitu. Musisz samodzielnie utworzyć licznik. umieść je poniżej pola tekstowego i dynamicznie aktualizuj je, gdy użytkownik wprowadza każdy znak lub wyraz.
Nie pozwól, aby kontrolki wprowadzania tekstu rosły w wysokości podczas wpisywania przez użytkowników.
Nie używaj wielowierszowego pola tekstowego, gdy użytkownicy potrzebują tylko jednego wiersza.
Nie używaj kontrolki tekstu sformatowanego, jeśli odpowiednia jest kontrolka zwykłego tekstu.
Tworzenie pola tekstowego
- Ważne interfejsy API:TextBox, właściwość Text
Aplikacja Galeria WinUI 3 zawiera interaktywne przykłady większości kontrolek, funkcji i funkcji interfejsu WinUI 3. Pobierz aplikację ze Sklepu Microsoft lub pobierz kod źródłowy w witrynie GitHub
Oto kod XAML prostego pola tekstowego z nagłówkiem i tekstem zastępczym.
<TextBox Width="500" Header="Notes" PlaceholderText="Type your notes here"/>
TextBox textBox = new TextBox();
textBox.Width = 300;
textBox.Header = "Notes";
textBox.PlaceholderText = "Type your notes here";
// Add the TextBox to the visual tree.
rootGrid.Children.Add(textBox);
Oto pole tekstowe, które wynika z tego kodu XAML.
Używanie pola tekstowego do wprowadzania danych w formularzu
Często używa się pola tekstowego do akceptowania danych wejściowych w formularzu i używania właściwości Text , aby uzyskać pełny ciąg tekstowy z pola tekstowego. Zwykle używasz zdarzenia, takiego jak kliknięcie przycisku przesyłania, aby uzyskać dostęp do właściwości Text, ale możesz obsłużyć zdarzenie TextChanged lub TextChanging , jeśli trzeba zrobić coś, gdy tekst się zmieni.
W tym przykładzie pokazano, jak pobrać i ustawić bieżącą zawartość pola tekstowego.
<TextBox name="SampleTextBox" Text="Sample Text"/>
string sampleText = SampleTextBox.Text;
...
SampleTextBox.Text = "Sample text retrieved";
Możesz dodać nagłówek (lub etykietę) i symbol zastępczy ( lub znak wodny) do pola tekstowego, aby nadać użytkownikowi wskazanie, do czego służy pole tekstowe. Aby dostosować wygląd nagłówka, można ustawić właściwość HeaderTemplate zamiast Header. Aby uzyskać informacje o projekcie, zobacz Wytyczne dotyczące etykiet.
Możesz ograniczyć liczbę znaków, które użytkownik może wpisać, ustawiając właściwość MaxLength . Jednak MaxLength nie ogranicza długości wklejonego tekstu. Użyj zdarzenia Wklej , aby zmodyfikować wklejony tekst, jeśli jest to ważne dla aplikacji.
Pole tekstowe zawiera przycisk „usuń wszystko” („X”), który pojawia się po wpisaniu tekstu. Gdy użytkownik kliknie znak "X", tekst w polu tekstowym zostanie wyczyszczony. Wygląda na to.
Przycisk "wyczyść wszystko" jest wyświetlany tylko dla edytowalnych, jednowierszowych pól tekstowych, które zawierają tekst i mają ustawiony fokus.
Wyczyść cały przycisk nie jest wyświetlany w żadnym z następujących przypadków:
- IsReadOnly ma wartość true
- AcceptsReturn ma wartość true
- Element TextWrap ma wartość inną niż NoWrap
W tym przykładzie pokazano, jak pobrać i ustawić bieżącą zawartość pola tekstowego.
<TextBox name="SampleTextBox" Text="Sample Text"/>
string sampleText = SampleTextBox.Text;
...
SampleTextBox.Text = "Sample text retrieved";
Tworzenie pola tekstowego tylko do odczytu
Pole tekstowe można ustawić jako tylko do odczytu, ustawiając właściwość IsReadOnly na true. Zazwyczaj tę właściwość można przełączać w kodzie aplikacji na podstawie warunków w aplikacji. Jeśli potrzebujesz tekstu, który jest zawsze tylko do odczytu, rozważ użycie zamiast tego funkcji TextBlock.
Pole TextBox można ustawić jako tylko do odczytu, ustawiając właściwość IsReadOnly na true. Na przykład może istnieć pole tekstowe dla użytkownika w celu wprowadzania komentarzy, które są włączone tylko w określonych warunkach. Pole TextBox można ustawić jako tylko do odczytu, dopóki warunki nie zostaną spełnione. Jeśli chcesz tylko wyświetlić tekst, rozważ użycie zamiast tego elementu TextBlock lub RichTextBlock.
Pole tekstowe tylko do odczytu wygląda tak samo jak pole tekstowe odczytu/zapisu, więc może być mylące dla użytkownika. Użytkownik może wybrać i skopiować tekst. JestWłączony
Włącz dane wejściowe wielowierszowe
Istnieją dwie właściwości, których można użyć do kontrolowania, czy pole tekstowe wyświetla tekst w więcej niż jednym wierszu. Zazwyczaj ustawiasz obie właściwości, aby zrobić wielowierszowe pole tekstowe.
- Aby umożliwić polu tekstowemu zezwalanie na wyświetlanie znaków nowego wiersza lub znaków powrotu, ustaw właściwość AcceptsReturn na true.
- Aby włączyć zawijanie tekstu, ustaw właściwość TextWrapping na Wrap. Powoduje to zawijanie tekstu, gdy osiągnie krawędź pola tekstowego niezależnie od znaków separatora wiersza.
Uwaga / Notatka
Kontrolki TextBox i RichEditBox nie obsługują wartości WrapWholeWords dla właściwości TextWrapping. Jeśli spróbujesz użyć WrapWholeWords jako wartości textBox.TextWrapping lub RichEditBox.TextWrapping, zostanie zgłoszony nieprawidłowy wyjątek argumentu.
Pole tekstowe wielowierszowe będzie nadal rosnąć w pionie w miarę wprowadzania tekstu, chyba że jest ograniczone przez jego właściwość Height lub MaxHeight albo przez kontener nadrzędny. Powinieneś upewnić się, że pole tekstowe wielowierszowe nie zwiększa się poza widoczny obszar i ograniczyć jego rozrost, jeśli tak się dzieje. Zalecamy, aby zawsze określać odpowiednią wysokość dla pola tekstowego wielowierszowego i nie pozwalać, by zwiększało się wraz z wprowadzaniem tekstu przez użytkownika.
Przewijanie przy użyciu kółka przewijania lub dotyku jest automatycznie włączane w razie potrzeby. Jednak pionowe paski przewijania nie są domyślnie widoczne. Możesz wyświetlić pionowe paski przewijania, ustawiając element ScrollViewer.VerticalScrollBarVisibility na Automatycznie w osadzonym programie ScrollViewer, jak pokazano tutaj.
<TextBox AcceptsReturn="True" TextWrapping="Wrap"
MaxHeight="172" Width="300" Header="Description"
ScrollViewer.VerticalScrollBarVisibility="Auto"/>
TextBox textBox = new TextBox();
textBox.AcceptsReturn = true;
textBox.TextWrapping = TextWrapping.Wrap;
textBox.MaxHeight = 172;
textBox.Width = 300;
textBox.Header = "Description";
ScrollViewer.SetVerticalScrollBarVisibility(textBox, ScrollBarVisibility.Auto);
Poniżej przedstawiono wygląd pola tekstowego po dodaniu tekstu.
Formatowanie wyświetlanego tekstu
Użyj właściwości TextAlignment, aby wyrównać tekst w polu tekstowym. Aby wyrównać pole tekstowe w układzie strony, użyj właściwości HorizontalAlignment i VerticalAlignment .
Pole tekstowe obsługuje tylko niesformatowany tekst, ale możesz dostosować sposób wyświetlania tekstu w polu tekstowym tak, aby był zgodny z marką. Można ustawić standardowe właściwości kontrolki
W tym przykładzie przedstawiono pole tekstowe tylko do odczytu z kilkoma właściwościami ustawionymi w celu dostosowania wyglądu tekstu.
<TextBox Text="Sample Text" IsReadOnly="True"
FontFamily="Verdana" FontSize="24"
FontWeight="Bold" FontStyle="Italic"
CharacterSpacing="200" Width="300"
Foreground="Blue" Background="Beige"/>
TextBox textBox = new TextBox();
textBox.Text = "Sample Text";
textBox.IsReadOnly = true;
textBox.FontFamily = new FontFamily("Verdana");
textBox.FontSize = 24;
textBox.FontWeight = Windows.UI.Text.FontWeights.Bold;
textBox.FontStyle = Windows.UI.Text.FontStyle.Italic;
textBox.CharacterSpacing = 200;
textBox.Width = 300;
textBox.Background = new SolidColorBrush(Windows.UI.Colors.Beige);
textBox.Foreground = new SolidColorBrush(Windows.UI.Colors.Blue);
// Add the TextBox to the visual tree.
rootGrid.Children.Add(textBox);
Wynikowe pole tekstowe wygląda następująco.
Modyfikowanie menu kontekstowego
Domyślnie polecenia wyświetlane w menu kontekstowym pola tekstowego zależą od stanu pola tekstowego. Na przykład następujące polecenia można wyświetlić, gdy pole tekstowe można edytować.
| Command | Wyświetlane, gdy... |
|---|---|
| Kopiuj | zaznaczono tekst. |
| Cięcie | zaznaczono tekst. |
| Wklej | Schowek zawiera tekst. |
| Wybierz wszystko | Pole tekstowe zawiera tekst. |
| Cofnąć | tekst został zmieniony. |
Aby zmodyfikować polecenia wyświetlane w menu kontekstowym, obsłuż zdarzenie ContextMenuOpening . Aby zobaczyć tego przykład, obejrzyj Dostosowywanie CommandBarFlyout RichEditBox — dodawanie 'Udostępnij' w galerii WinUI 2. Aby uzyskać informacje o projekcie, zobacz Wytyczne dotyczące menu kontekstowych.
Wybieranie, kopiowanie i wklejanie
Możesz pobrać lub ustawić zaznaczony tekst w polu tekstowym przy użyciu właściwości SelectedText . Użyj właściwości SelectionStart i SelectionLength oraz metod Select i SelectAll, aby manipulować zaznaczeniem tekstu. Obsłuż zdarzenie SelectionChanged , aby zrobić coś, gdy użytkownik wybierze lub anuluje zaznaczenie tekstu. Kolor używany do wyróżniania zaznaczonego tekstu można zmienić, ustawiając właściwość SelectionHighlightColor .
Pole tekstowe domyślnie obsługuje kopiowanie i wklejanie. Możesz zapewnić niestandardową obsługę zdarzenia Wklej w edytowalnych kontrolkach tekstowych w aplikacji. Na przykład można usunąć podziały wierszy z adresu wielowierszowego podczas wklejania go w jednowierszowym polu wyszukiwania. Możesz też sprawdzić długość wklejonego tekstu i ostrzec użytkownika, jeśli przekroczy maksymalną długość, którą można zapisać w bazie danych. Aby uzyskać więcej informacji i przykładów, zobacz zdarzenie Wklej.
Tutaj mamy przykład tych właściwości i metod w użyciu. Po wybraniu tekstu w pierwszym polu tekstowym zaznaczony tekst jest wyświetlany w drugim polu tekstowym, które jest tylko do odczytu. Wartości właściwości SelectionLength i SelectionStart są wyświetlane w dwóch blokach tekstowych. Odbywa się to przy użyciu zdarzenia SelectionChanged .
<StackPanel>
<TextBox x:Name="textBox1" Height="75" Width="300" Margin="10"
Text="The text that is selected in this TextBox will show up in the read only TextBox below."
TextWrapping="Wrap" AcceptsReturn="True"
SelectionChanged="TextBox1_SelectionChanged" />
<TextBox x:Name="textBox2" Height="75" Width="300" Margin="5"
TextWrapping="Wrap" AcceptsReturn="True" IsReadOnly="True"/>
<TextBlock x:Name="label1" HorizontalAlignment="Center"/>
<TextBlock x:Name="label2" HorizontalAlignment="Center"/>
</StackPanel>
private void TextBox1_SelectionChanged(object sender, RoutedEventArgs e)
{
textBox2.Text = textBox1.SelectedText;
label1.Text = "Selection length is " + textBox1.SelectionLength.ToString();
label2.Text = "Selection starts at " + textBox1.SelectionStart.ToString();
}
Oto wynik tego kodu.
Wybieranie odpowiedniej klawiatury dla kontrolki tekstu
Aby ułatwić użytkownikom wprowadzanie danych przy użyciu klawiatury dotykowej lub Panelu wprowadzania nietrwałego (SIP), możesz ustawić zakres wejściowy kontrolki tekstu tak, aby był zgodny z rodzajem danych, które użytkownik powinien wprowadzić.
Klawiatura dotykowa może służyć do wprowadzania tekstu, gdy aplikacja działa na urządzeniu z ekranem dotykowym. Klawiatura dotykowa jest wywoływana, gdy użytkownik naciągnie edytowalne pole wejściowe, takie jak TextBox lub RichEditBox. Możesz znacznie szybciej i łatwiej użytkownikom wprowadzać dane w aplikacji, ustawiając zakres wejściowy kontrolki tekstu tak, aby był zgodny z rodzajem danych, które mają być wprowadzane przez użytkownika. Zakres wejściowy zawiera wskazówkę dla systemu na temat typu wprowadzania tekstu oczekiwanego przez kontrolkę, dzięki czemu system może zapewnić wyspecjalizowany układ klawiatury dotykowej dla typu wejściowego.
Jeśli na przykład pole tekstowe jest używane tylko do wprowadzania 4-cyfrowego numeru PIN, ustaw właściwość InputScope na Number. Dzięki temu system wyświetli układ klawiatury liczbowej, co ułatwia użytkownikowi wprowadzenie numeru PIN.
Ważny Zakres danych wejściowych nie powoduje przeprowadzenia walidacji danych wejściowych i nie uniemożliwia użytkownikowi podania żadnych danych wejściowych za pośrednictwem klawiatury sprzętowej lub innego urządzenia wejściowego. Nadal ponosisz odpowiedzialność za weryfikowanie danych wejściowych w kodzie zgodnie z potrzebami.
Inne właściwości wpływające na klawiaturę dotykową to IsSpellCheckEnabled, IsTextPredictionEnabled i PreventKeyboardDisplayOnProgrammaticFocus. (IsSpellCheckEnabled również wpływa na TextBox, gdy jest używana klawiatura sprzętowa).
Aby uzyskać więcej informacji i przykładów, zobacz Używanie zakresu wprowadzania w celu zmiany klawiatury dotykowej oraz dokumentację właściwości.
UwP i WinUI 2
Ważne
Informacje i przykłady w tym artykule są zoptymalizowane dla aplikacji korzystających z Windows App SDK oraz WinUI 3, ale generalnie mają zastosowanie także w aplikacjach UWP używających WinUI 2. Zobacz dokumentację interfejsu API platformy UWP, aby uzyskać informacje i przykłady dotyczące platformy.
Ta sekcja zawiera informacje potrzebne do używania kontrolki w aplikacji platformy UWP lub WinUI 2.
API dla tej kontrolki istnieją w ramach przestrzeni nazw Windows.UI.Xaml.Controls.
- Interfejsy API platformy UWP:Klasa TextBox, właściwość Text
-
Otwórz aplikację Galeria WinUI 2 i zobacz akcję TextBox. Aplikacja z galerii
WinUI 2 zawiera interaktywne przykłady większości kontrolek, funkcji i funkcji winUI 2. Pobierz aplikację ze Sklepu Microsoft lub pobierz kod źródłowy w witrynie GitHub.
Zalecamy użycie najnowszej wersji WinUI 2 , aby uzyskać najbardziej aktualne style i szablony dla wszystkich kontrolek. Interfejs WinUI 2.2 lub nowszy zawiera nowy szablon dla tej kontrolki, który używa zaokrąglonych narożników. Aby uzyskać więcej informacji, zobacz Zaokrąglenie narożnika.
Powiązane artykuły
- Kontrolki tekstu
- wskazówki dotyczące sprawdzania pisowni
- Dodawanie wyszukiwania
- Wskazówki dotyczące wprowadzania tekstu
- Klasa TextBox
- Klasa PasswordBox
- Właściwość String.Length
Współpracuj z nami na GitHub
Źródło tej treści można znaleźć na GitHubie, gdzie można także tworzyć i przeglądać problemy oraz pull requesty. Więcej informacji znajdziesz w naszym przewodniku dla współautorów.
Windows developer