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


Поле расширенного редактирования текста

Элемент управления RichEditBox можно использовать для ввода и редактирования текстовых документов с форматированным текстом, гиперссылками и изображениями. Вы можете сделать richEditBox только для чтения, задав для свойства IsReadOnly значение true.

Это правильный элемент управления?

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

  • Если основное назначение многострочного поля — создание документов только для чтения (например, записей в блогах или содержимого электронных писем) и эти документы требуют форматированного текста, используйте вместо этого блок оформления текста.
  • При вводе текста, который будет использоваться только для обработки, а не отображаться пользователям, используйте поле ввода простого текста.
  • Для всех других сценариев используйте контроль ввода обычного текста.

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

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

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

Примеры

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

Поле форматированного текста с открытым документом

Создание полнофункционированного поля редактирования

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

По умолчанию RichEditBox поддерживает проверку орфографии. Чтобы отключить средство проверки орфографии, задайте для свойства IsSpellCheckEnabled значение false. Дополнительные сведения см. в статье "Рекомендации по проверке орфографии ".

Для получения содержимого вы используете свойство Document RichEditBox. Содержимое RichEditBox — это объект ITextDocument , в отличие от элемента управления RichTextBlock, который использует объекты Block в качестве содержимого. Интерфейс ITextDocument предоставляет способ загрузки и сохранения документа в потоке, извлечения текстовых диапазонов, получения активного выделения, отмены и повтора изменений, задания атрибутов форматирования по умолчанию и т. д.

В этом примере показано, как редактировать, загружать и сохранять файл форматированного текста (.rtf) в RichEditBox.

<RelativePanel Margin="20" HorizontalAlignment="Stretch">
    <RelativePanel.Resources>
        <Style TargetType="AppBarButton">
            <Setter Property="IsCompact" Value="True"/>
        </Style>
    </RelativePanel.Resources>
    <AppBarButton x:Name="openFileButton" Icon="OpenFile"
                  Click="OpenButton_Click" ToolTipService.ToolTip="Open file"/>
    <AppBarButton Icon="Save" Click="SaveButton_Click"
                  ToolTipService.ToolTip="Save file"
                  RelativePanel.RightOf="openFileButton" Margin="8,0,0,0"/>

    <AppBarButton Icon="Bold" Click="BoldButton_Click" ToolTipService.ToolTip="Bold"
                  RelativePanel.LeftOf="italicButton" Margin="0,0,8,0"/>
    <AppBarButton x:Name="italicButton" Icon="Italic" Click="ItalicButton_Click"
                  ToolTipService.ToolTip="Italic" RelativePanel.LeftOf="underlineButton" Margin="0,0,8,0"/>
    <AppBarButton x:Name="underlineButton" Icon="Underline" Click="UnderlineButton_Click"
                  ToolTipService.ToolTip="Underline" RelativePanel.AlignRightWithPanel="True"/>

    <RichEditBox x:Name="editor" Height="200" RelativePanel.Below="openFileButton"
                 RelativePanel.AlignLeftWithPanel="True" RelativePanel.AlignRightWithPanel="True"/>
</RelativePanel>
private async void OpenButton_Click(object sender, RoutedEventArgs e)
{
    // Open a text file.
    Windows.Storage.Pickers.FileOpenPicker open =
        new Windows.Storage.Pickers.FileOpenPicker();
    open.SuggestedStartLocation =
        Windows.Storage.Pickers.PickerLocationId.DocumentsLibrary;
    open.FileTypeFilter.Add(".rtf");

    Windows.Storage.StorageFile file = await open.PickSingleFileAsync();

    if (file != null)
    {
        try
        {
            Windows.Storage.Streams.IRandomAccessStream randAccStream =
        await file.OpenAsync(Windows.Storage.FileAccessMode.Read);

            // Load the file into the Document property of the RichEditBox.
            editor.Document.LoadFromStream(Windows.UI.Text.TextSetOptions.FormatRtf, randAccStream);
        }
        catch (Exception)
        {
            ContentDialog errorDialog = new ContentDialog()
            {
                Title = "File open error",
                Content = "Sorry, I couldn't open the file.",
                PrimaryButtonText = "Ok"
            };

            await errorDialog.ShowAsync();
        }
    }
}

private async void SaveButton_Click(object sender, RoutedEventArgs e)
{
    Windows.Storage.Pickers.FileSavePicker savePicker = new Windows.Storage.Pickers.FileSavePicker();
    savePicker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.DocumentsLibrary;

    // Dropdown of file types the user can save the file as
    savePicker.FileTypeChoices.Add("Rich Text", new List<string>() { ".rtf" });

    // Default file name if the user does not type one in or select a file to replace
    savePicker.SuggestedFileName = "New Document";

    Windows.Storage.StorageFile file = await savePicker.PickSaveFileAsync();
    if (file != null)
    {
        // Prevent updates to the remote version of the file until we
        // finish making changes and call CompleteUpdatesAsync.
        Windows.Storage.CachedFileManager.DeferUpdates(file);
        // write to file
        Windows.Storage.Streams.IRandomAccessStream randAccStream =
            await file.OpenAsync(Windows.Storage.FileAccessMode.ReadWrite);

        editor.Document.SaveToStream(Windows.UI.Text.TextGetOptions.FormatRtf, randAccStream);

        // Let Windows know that we're finished changing the file so the
        // other app can update the remote version of the file.
        Windows.Storage.Provider.FileUpdateStatus status = await Windows.Storage.CachedFileManager.CompleteUpdatesAsync(file);
        if (status != Windows.Storage.Provider.FileUpdateStatus.Complete)
        {
            Windows.UI.Popups.MessageDialog errorBox =
                new Windows.UI.Popups.MessageDialog("File " + file.Name + " couldn't be saved.");
            await errorBox.ShowAsync();
        }
    }
}

private void BoldButton_Click(object sender, RoutedEventArgs e)
{
    Windows.UI.Text.ITextSelection selectedText = editor.Document.Selection;
    if (selectedText != null)
    {
        Windows.UI.Text.ITextCharacterFormat charFormatting = selectedText.CharacterFormat;
        charFormatting.Bold = Windows.UI.Text.FormatEffect.Toggle;
        selectedText.CharacterFormat = charFormatting;
    }
}

private void ItalicButton_Click(object sender, RoutedEventArgs e)
{
    Windows.UI.Text.ITextSelection selectedText = editor.Document.Selection;
    if (selectedText != null)
    {
        Windows.UI.Text.ITextCharacterFormat charFormatting = selectedText.CharacterFormat;
        charFormatting.Italic = Windows.UI.Text.FormatEffect.Toggle;
        selectedText.CharacterFormat = charFormatting;
    }
}

private void UnderlineButton_Click(object sender, RoutedEventArgs e)
{
    Windows.UI.Text.ITextSelection selectedText = editor.Document.Selection;
    if (selectedText != null)
    {
        Windows.UI.Text.ITextCharacterFormat charFormatting = selectedText.CharacterFormat;
        if (charFormatting.Underline == Windows.UI.Text.UnderlineType.None)
        {
            charFormatting.Underline = Windows.UI.Text.UnderlineType.Single;
        }
        else {
            charFormatting.Underline = Windows.UI.Text.UnderlineType.None;
        }
        selectedText.CharacterFormat = charFormatting;
    }
}

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

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

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

UWP и WinUI 2

Внимание

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

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

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

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