Текстовое поле

Статья
07/13/2023

Элемент управления TextBox позволяет пользователю вводить текст в приложение. Обычно он используется для записи одной строки текста. Но элемент можно настроить и для записи нескольких строк. Текст отображается на экране в простом унифицированном формате обычного текста.

Текстовое поле

Элемент TextBox имеет несколько компонентов, которые могут упростить ввод текста. В этом элементе работает привычное встроенное контекстное меню с поддержкой копирования и вставки текста. Кнопка "Очистить все" позволяет пользователю быстро удалить весь введенный текст. В нем также есть встроенные функции проверки орфографии, которые включены по умолчанию.

Выбор правильного элемента управления

Используйте элемент управления TextBox, чтобы пользователь мог вводить и редактировать неформатированный текст, в частности, в форме. С помощью свойства Text можно получить и задать текст в элементе управления TextBox.

Вы можете сделать элемент TextBox предназначенным только для чтения. Но это должно быть временным, условным состоянием. Если текст не редактируется, попробуйте использовать элемент TextBlock.

Элемент управления PasswordBox можно использовать для сбора паролей или других конфиденциальных данных, например номеров карт социального страхования. Поле ввода пароля внешне похоже на поле текстового ввода с той разницей, что в нем вместо вводимого текста отображаются маркеры.

Используйте элемент управления AutoSuggestBox, чтобы позволить пользователю искать термины или показать пользователю список рекомендаций для выбора во время ввода.

Элемент RichEditBox служит для отображения и правки текстовых файлов.

Дополнительные сведения можно найти в статье об элементах управления текстом.

UWP и WinUI 2

Внимание

Сведения и примеры в этой статье оптимизированы для приложений, использующих пакет SDK для приложений Windows и WinUI 3, но обычно применимы к приложениям UWP, использующим WinUI 2. См. справочник по API UWP для конкретных сведений и примеров платформы.

В этом разделе содержатся сведения, необходимые для использования элемента управления в приложении UWP или WinUI 2.

API для этого элемента управления существуют в пространстве имен Windows.UI.Xaml.Controls .

API UWP: класс TextBox, свойство Text
Откройте приложение коллекции WinUI 2 и просмотрите текстовое поле в действии. Приложения из коллекции WinUI 2 включают интерактивные примеры большинства элементов управления, возможностей и функций WinUI 2. Получите приложение из Microsoft Store или получите исходный код в GitHub.

Мы рекомендуем использовать последнюю версию WinUI 2 , чтобы получить самые актуальные стили и шаблоны для всех элементов управления. WinUI 2.2 или более поздней версии содержит новый шаблон для этого элемента управления, использующего округленные углы. Дополнительные сведения см. в разделе о радиусе угла.

Создание текстового поля

Важные API: класс TextBox, свойство Text

Откройте приложение коллекции WinUI 3 и просмотрите текстовое поле в действии.

Приложение коллекции WinUI 3 включает интерактивные примеры большинства элементов управления, функций и функций WinUI 3. Получение приложения из Microsoft Store или получение исходного кода на GitHub

Вот код XAML для простого текстового поля с заголовком и замещающим текстом.

<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);

Ниже показано текстовое поле, полученное в результате выполнения этого фрагмента кода XAML.

Простое текстовое поле

Использование текстового поля для ввода данных в форму

Текстовое поле часто используется, чтобы принять ввод данных в форму и получить полную текстовую строку из текстового поля с помощью свойства Text. Обычно доступ к свойству Text осуществляется в таких событиях, как нажатие кнопки "Отправить". Но вы можете использовать событие TextChanged или TextChanging, если нужно выполнить какие-либо действия сразу при изменении текста.

В этом примере показано, как получить и задать текущее содержимое текстового поля.

<TextBox name="SampleTextBox" Text="Sample Text"/>

string sampleText = SampleTextBox.Text;
...
SampleTextBox.Text = "Sample text retrieved";

К текстовому полю можно добавить Header (или метку) и PlaceholderText (или водяной знак), чтобы пользователь понимал, для чего оно используется. Чтобы настроить оформление заголовка, задайте свойство HeaderTemplate вместо Header. Сведения о проектировании см. в руководстве по использованию меток.

Вы можете ограничить число вводимых пользователем символов, настроив свойство MaxLength. Но свойство MaxLength не ограничивает длину вставленного текста. Используйте событие Paste, чтобы изменить вставленный текст, если это важно для вашего приложения.

В текстовом поле есть кнопка "Очистить все" ("X"), которая появляется при введении текста в поле. Когда пользователь нажимает кнопку "X", текст в поле удаляется. Это выглядит следующим образом:

Текстовое поле с кнопкой

Кнопка "Очистить все" отображается только для редактируемых однострочных текстовых полей, которые содержат текст и имеют фокус.

Кнопка "Очистить все" не отображается в любом из перечисленных ниже случаев.

Параметр IsReadOnly имеет значение true.
Параметр AcceptsReturn имеет значение true.
TextWrap имеет значение, отличное от NoWrap.

В этом примере показано, как получить и задать текущее содержимое текстового поля.

<TextBox name="SampleTextBox" Text="Sample Text"/>

string sampleText = SampleTextBox.Text;
...
SampleTextBox.Text = "Sample text retrieved";

Текст, предназначенный только для чтения

Текстовое поле можно сделать доступным только для чтения, присвоив свойству IsReadOnly значение true. Обычно вы переключаете это свойство в приложении, исходя из условий в приложении. Если вам нужен текст, который всегда предназначен только для чтения, воспользуйтесь элементом TextBlock.

Объект TextBox можно сделать доступным только для чтения, присвоив свойству IsReadOnly значение true. Например, у вас может быть элемент TextBox для пользовательских комментариев, который включается только при определенных условиях. Элемент TextBox можно сделать предназначенным только для чтения, пока не будут выполняться эти условия. Если вам нужно только отобразить текст, воспользуйтесь элементом TextBlock или RichTextBlock.

Текстовое поле, предназначенное только для чтения, ничем не отличается от текстового поля, предназначенного для чтения и записи. Поэтому пользователь может растеряться. Пользователь может выделять и копировать текст. IsEnabled

Включение многострочного ввода

Есть два свойства, которые позволяют управлять отображением текста на нескольких строках в текстовом поле. Обычно нужно указать оба эти свойства, чтобы сделать текстовое поле многострочным.

Чтобы позволить текстовому полю разрешать и отображать символы новой строки или возврата, установите для свойства AcceptsReturn значение true.
Чтобы включить обтекание текстом, установите для свойства TextWrapping значение Wrap. Теперь текст будет переноситься на новую строку, когда он достигает края текстового поля, независимо от символов разделителя строки.

Примечание.

TextBox и RichEditBox не поддерживают значение WrapWholeWords для свойств TextWrapping. Если попытаться указать WrapWholeWords в качестве значения для параметра TextBox.TextWrapping или RichEditBox.TextWrapping, отобразится исключение с сообщением о недействительном аргументе.

Многострочное текстовое поле будет постоянно увеличиваться по вертикали по мере ввода текста, если нет ограничений в свойстве Height, MaxHeight или родительском контейнере. Следите за тем, чтобы многострочное текстовое поле не выходило за пределы видимой зоны. Если это произошло, ограничьте его увеличение. Мы рекомендуем всегда указывать целесообразную высоту для многострочного текстового поля и не позволять ему увеличиваться в высоту во время ввода текста пользователем.

Прокрутка с помощью колесика прокрутки или пальца включается автоматически по мере необходимости. Но вертикальные полосы прокрутки не отображаются по умолчанию. Вы можете отобразить вертикальные полосы прокрутки, установив для параметра ScrollViewer.VerticalScrollBarVisibility значение Auto для встроенного класса ScrollViewer, как показано здесь.

<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);

Вот как выглядит текстовое поле после добавления текста.

Поле многострочного текста

Форматирование отображаемого текста

Используйте свойство TextAlignment для выравнивания текста в текстовом поле. Чтобы выровнять текстовое поле в рамках макета страницы, используйте свойства HorizontalAlignment и VerticalAlignment.

Хотя текстовое поле поддерживает только неформатированный текст, вы можете настроить отображение текста в текстовом поле в соответствии с фирменным оформлением. Можно задать стандартные свойства Control, например, FontFamily, FontSize, FontStyle, Background, Foreground и CharacterSpacing, чтобы изменить внешний вид текста. Эти свойства влияют только на то, как текстовое поле отображает текст локально. Например, если скопировать и вставить текст в элемент управления для форматированного текста, форматирование не будет применено.

В этом примере показано текстовое поле, предназначенное только для чтения, с несколькими настроенными свойствами для внешнего вида текста.

<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);

Созданное текстовое поле выглядит следующим образом:

Форматированное текстовое поле

По умолчанию команды, отображаемые в контекстном меню текстового поля, зависят от состояния текстового поля. Например, если текстовое поле является редактируемым, отображаются следующие команды:

Команда	Отображается, когда...
Копия	...текст выделен.
Вырезать	...текст выделен.
Вставить	...буфер обмена содержит текст.
Выделить все	...элемент TextBox содержит текст.
Отмена	...текст был изменен.

Чтобы изменить команды, отображаемые в контекстном меню, обрабатывайте событие ContextMenuOpening. Пример этого см. в разделе "Настройка CommandBarFlyout RichEditBox" в коллекции WinUI 2. Сведения о проектировании см. в руководстве по контекстным меню.

Выделение, копирование и вставка

Получить выбранный текст из текстового поля или задать его можно с помощью свойства SelectedText. Чтобы управлять выделением текста, используйте свойства SelectionStart и SelectionLength, а также методы Select и SelectAll. Событие SelectionChanged позволяет выполнять действия, пока пользователь выбирает или отменяет выбор текста. Вы можете изменить цвет, используемый для выделения выбранного текста, настроив свойство SelectionHighlightColor.

Элемент TextBox поддерживает копирование и вставку по умолчанию. Вы можете реализовать в приложении пользовательскую обработку события Paste в редактируемых текстовых элементах управления. Например, можно удалить разрывы строк из многострочного адреса при вставке в однострочное поле поиска. Или вы можете проверить длину вставленного текста и предупредить пользователя, если превышает максимальную длину текста, который можно сохранить в базе данных. Дополнительные сведения и примеры см. в статье о событии Paste.

Ниже приведен пример применяемых для этого свойств и методов. При выборе текста в первом текстовом поле выбранный текст отображается во втором текстовом поле, которое доступно только для чтения. Значения свойств SelectionLength и SelectionStart отображаются в двух текстовых блоках. Для этого используется событие 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();
}

Вот результат выполнения этого кода.

Выбранный текст в текстовом поле

Выбор подходящей клавиатуры для элемента управления текстом

Чтобы упростить пользователям ввод данных с помощью сенсорной клавиатуры или панели функционального ввода, можно настроить тип вводимых данных элемента управления для ввода текста таким образом, чтобы элемент управления соответствовал типу данных, которые должен вводить пользователь.

Сенсорная клавиатура позволяет вводить текст, если приложение выполняется на устройстве с сенсорным экраном. Сенсорная клавиатура появляется, когда пользователь касается редактируемого поля ввода, например, TextBox или RichEditBox. Пользователи смогут вводить данные в вашем приложении гораздо быстрее и с меньшими усилиями, если вы настроите тип вводимых данных элемента управления текстом в соответствии с типом вводимых данных. Тип вводимых данных предоставляет системе подсказку о типе текстового ввода, ожидаемого элементом управления. Благодаря этому система может отобразить специальную раскладку сенсорной клавиатуры в соответствии с используемым типом ввода.

Например, если текстовое поле используется только для ввода 4-значного PIN-кода, установите для свойства InputScope значение Number. Это сообщает системе, что нужно отобразить раскладку цифровой клавиатуры, благодаря чему пользователю проще вводить PIN-код.

Важно, что область ввода не приводит к выполнению какой-либо проверки входных данных и не препятствует пользователю предоставлять любые входные данные с помощью аппаратной клавиатуры или другого устройства ввода. Вы по-прежнему несете ответственность за проверку вводимых данных в коде.

Другие свойства, влияющие на сенсорную клавиатуру: IsSpellCheckEnabled, IsTextPredictionEnabled и PreventKeyboardDisplayOnProgrammaticFocus. (IsSpellCheckEnabled также влияет на элемент TextBox при использовании аппаратной клавиатуры.)

Дополнительные сведения и примеры см. в статье Использование типа вводимых данных для изменения сенсорной клавиатуры и в документации по свойствам.

Получение кода примера

Пример коллекции WinUI. Просмотрите все элементы управления XAML в интерактивном формате.

Поделиться через

Текстовое поле

Выбор правильного элемента управления

Рекомендации

Поля ввода из одной строки

Элементы управления для ввода многострочного текста

UWP и WinUI 2

Создание текстового поля

Использование текстового поля для ввода данных в форму

Текст, предназначенный только для чтения

Включение многострочного ввода

Форматирование отображаемого текста

Изменение контекстного меню

Выделение, копирование и вставка

Выбор подходящей клавиатуры для элемента управления текстом

Получение кода примера

Дополнительные ресурсы

Поделиться через

Текстовое поле

Выбор правильного элемента управления

Рекомендации

Поля ввода из одной строки

Элементы управления для ввода многострочного текста

UWP и WinUI 2

Создание текстового поля

Использование текстового поля для ввода данных в форму

Текст, предназначенный только для чтения

Включение многострочного ввода

Форматирование отображаемого текста

Изменение контекстного меню

Выделение, копирование и вставка

Выбор подходящей клавиатуры для элемента управления текстом

Получение кода примера

Связанные статьи

Дополнительные ресурсы