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

Элемент управления 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;
    }
}

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

RichEditBox может отображать и редактировать математические уравнения с помощью UnicodeMath. Уравнения хранятся и извлекаются в формате MathML 3.0 .

По умолчанию элемент управления RichEditBox не интерпретирует входные данные как математические. Чтобы включить математический режим, вызовите SetMathMode в свойстве TextDocument, передав значение RichEditMathMode.MathOnly (чтобы отключить математический режим, вызвать SetMathMode, но передать значение NoMath).

richEditBox.TextDocument.SetMathMode(Microsoft.UI.Text.RichEditMathMode.MathOnly);

Это позволяет автоматически распознавать и преобразовывать входные данные Юникода в MathML в режиме реального времени. Например, ввод 4^2 преобразуется в 4², а 1/2 преобразуется в ½. См. приложение WinUI 3 Gallery для дополнительных примеров.

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

richEditBox.TextDocument.GetMathML(out String mathML);

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

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

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

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

UWP и WinUI 2

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

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

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

• Текстовые элементы управления
• Рекомендации по проверке орфографии
• Рекомендации по вводу текста
• Класс TextBox
• Класс PasswordBox