Caixa de edição rica

Você pode usar um controle RichEditBox para inserir e editar documentos rich text que contenham 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.

Será este o controlo correto?

Use um RichEditBox para exibir e editar arquivos de texto. Você não utiliza um RichEditBox para obter a entrada do utilizador na sua aplicação da mesma forma que usa outras caixas de introdução 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 o objetivo principal da caixa de texto de várias linhas for criar documentos somente leitura (como entradas de blog ou o conteúdo de uma mensagem de email) e esses documentos exigirem texto enriquecido, em vez disso, use um bloco de texto enriquecido .
• Ao capturar texto que só será consumido e não reexibido aos 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 saber mais sobre como escolher o controle de texto correto, veja o artigo Controles de texto .

Recommendations

• Ao criar uma caixa de texto enriquecido, forneça botões para formatação e implemente as suas ações.
• Use uma fonte consistente com o estilo do seu aplicativo.
• Ajuste a altura do controle de texto para que seja suficiente para acomodar entradas típicas.
• Não permita que seus controles de entrada de texto cresçam em altura enquanto os usuários digitam.
• Não use uma caixa de texto com várias linhas quando os usuários precisarem apenas de uma única linha.
• Não use um controle de rich text se um controle de texto sem formatação for adequado.

Examples

Esta caixa de edição avançada tem um documento 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

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

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

Você usa a propriedade Document do 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, digitar 4^2 converte para 4², e 1/2 converte para 1/2. Consulte o aplicativo WinUI 3 Gallery 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 certo para o seu controlo de texto

Para ajudar os usuários a inserir dados usando o teclado virtual ou o SIP (Painel de Entrada Flexível), 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 saber mais sobre como usar escopos de entrada, veja Usar escopo de entrada para alterar o teclado virtual.

UWP e WinUI 2

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

Recomendamos usar a WinUI 2 mais recente para obter os estilos e modelos mais atuais para todos os controles. WinUI 2.2 ou posterior inclui um novo modelo para este controle que usa cantos arredondados. Consulte Raio de cantopara obter mais informações.

Artigos relacionados

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