Caixa de edição rica

Você pode usar um controle RichEditBox para inserir e editar documentos de rich text que contêm texto formatado, hiperlinks, imagens, equações matemáticas e outros conteúdos avançados. Você pode tornar um RichEditBox somente leitura definindo sua propriedade IsReadOnly como true.

Esse é o controle correto?

Use um RichEditBox para exibir e editar arquivos de texto. Você não usa um RichEditBox para obter a entrada do usuário em seu aplicativo da mesma forma que usa outras caixas de entrada de texto padrão. Em vez disso, você o usa para trabalhar com arquivos de texto separados do seu aplicativo. Normalmente, você salva o texto inserido em um RichEditBox em um arquivo .rtf.

• Se a finalidade principal da caixa de texto multilinha for criar documentos somente leitura (como entradas de blog ou o conteúdo de uma mensagem de email), e esses documentos exigirem texto rico, utilize um bloco de texto rico.
• Ao capturar texto que será consumido apenas e não será reexibido para os usuários, use um controle de entrada de texto sem formatação.
• Para todos os outros cenários, use um controle de entrada de texto sem formatação.

Para obter mais informações sobre como escolher o controle de texto certo, consulte o artigo Controles de texto.

Recommendations

• Quando você cria uma caixa de texto Rich Text, forneça botões de estilo e implemente as ações comandadas por eles.
• Use uma fonte que seja consistente com o estilo de seu aplicativo.
• Faça com que a altura do controle de texto seja suficiente para acomodar entradas típicas.
• Não deixe que seus controles de entrada de texto aumentem de tamanho enquanto os usuários digitam.
• Não use uma caixa de texto com várias linhas quando os usuários só precisarem de uma linha única.
• Não use um controle Rich Text se um controle de texto sem formatação for adequado.

Exemplos

Esta caixa de edição avançada tem um documento de rich text aberto nela. Os botões de formatação e arquivo não fazem parte da caixa de edição avançada, mas você deve fornecer pelo menos um conjunto mínimo de botões de estilo e implementar suas ações.

Criar uma caixa de edição avançada

• APIs importantes: classe RichEditBox, propriedade Document, propriedade IsReadOnly, propriedade IsSpellCheckEnabled

Abra o aplicativo Da Galeria do WinUI e veja o RichEditBox em ação

O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou obtenha o código-fonte no GitHub

Por padrão, o RichEditBox dá suporte à verificação ortográfica. Para desabilitar o verificador ortográfico, defina a propriedade IsSpellCheckEnabled como false. Para obter mais informações, consulte o artigo Diretrizes para verificação ortográfica .

Use a propriedade Document de RichEditBox para obter seu conteúdo. O conteúdo de um RichEditBox é um objeto ITextDocument , ao contrário do controle RichTextBlock, que usa objetos Block como seu conteúdo. A interface ITextDocument fornece uma maneira de carregar e salvar o documento em um fluxo, recuperar intervalos de texto, obter a seleção ativa, desfazer e refazer alterações, definir atributos de formatação padrão e assim por diante.

Este exemplo mostra como editar, carregar e salvar um arquivo Rich Text Format (.rtf) em um 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;
    }
}

Usar uma caixa de edição avançada para equações matemáticas

O RichEditBox pode exibir e editar equações matemáticas usando UnicodeMath. As equações são armazenadas e recuperadas no formato MathML 3.0 .

Por padrão, o controle RichEditBox não interpreta a entrada como matemática. Para habilitar o modo matemático, chame SetMathMode na propriedade TextDocument , passando o valor RichEditMathMode.MathOnly (para desabilitar o modo matemático, chame SetMathMode , mas passe o valor NoMath).

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

Isso permite que a entrada UnicodeMath seja automaticamente reconhecida e convertida em MathML em tempo real. Por exemplo, inserir 4^2 converte em 4² e 1/2 converte em 1/2. Consulte o aplicativo Da Galeria do WinUI para obter mais exemplos.

Para salvar o conteúdo matemático de uma caixa de edição avançada como uma cadeia de caracteres MathML, chame GetMathML.

richEditBox.TextDocument.GetMathML(out String mathML);

Para definir o conteúdo matemático de uma caixa de edição avançada, chame SetMathML, passando uma cadeia de caracteres MathML.

Escolha o teclado correto para o controle de texto

Para ajudar os usuários a inserir dados usando o teclado virtual ou o SIP (Soft Input Panel), você pode definir o escopo de entrada do controle de texto para corresponder ao tipo de dados que o usuário deve inserir. O layout de teclado padrão geralmente é apropriado para trabalhar com documentos rich text.

Para obter mais informações sobre como usar modos de entrada, consulte Usar modo de entrada para alterar o teclado virtual touch.

UWP e WinUI para UWP

Importante

As informações e exemplos neste artigo são otimizados para aplicativos que usam o SDK do Aplicativo Windows e o WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam o WinUI 2. Consulte a referência da API UWP para obter informações e exemplos específicos da plataforma.

Esta seção contém informações necessárias para usar o controle em um aplicativo UWP ou WinUI 2.

As APIs para esse controle existem no namespace Windows.UI.Xaml.Controls.

• APIs UWP:classe RichEditBox, Propriedade do documento, propriedade IsReadOnly, propriedade IsSpellCheckEnabled
• Abra o aplicativo WinUI for UWP Gallery e veja o RichEditBox em ação. O aplicativo WinUI 2 Gallery inclui exemplos interativos da maioria dos controles, dos recursos e das funcionalidades do WinUI 2. Obtenha o aplicativo na Microsoft Store ou obtenha o código-fonte no GitHub.

É recomendável usar a WinUI mais recente para UWP para obter os estilos e modelos mais atuais para todos os controles. WinUI 2.2 ou posterior inclui um novo modelo para esse controle que usa cantos arredondados. Para obter mais informações, consulte raio de canto .

Artigos relacionados

• Controles de texto
• Diretrizes para verificação ortográfica
• Diretrizes para entrada de texto
• Classe TextBox
• PasswordBox classe