Zone d’édition enrichie

Vous pouvez utiliser un contrôle RichEditBox pour entrer et modifier des documents de texte enrichi contenant du texte mis en forme, des liens hypertexte, des images, des équations mathématiques et d’autres contenus enrichis. Vous pouvez définir une propriété RichEditBox en lecture seule en définissant sa propriété IsReadOnly sur true.

Est-ce le contrôle approprié ?

Utilisez un RichEditBox pour afficher et modifier des fichiers texte. Vous n’utilisez pas richEditBox pour obtenir une entrée utilisateur dans votre application de la façon dont vous utilisez d’autres zones de saisie de texte standard. Au lieu de cela, vous l’utilisez pour utiliser des fichiers texte distincts de votre application. Vous enregistrez généralement du texte entré dans un richEditBox dans un fichier .rtf.

• Si l’objectif principal de la zone de texte multiligne est de créer des documents en lecture seule (tels que les entrées de blog ou le contenu d’un e-mail) et que ces documents nécessitent du texte enrichi, utilisez un bloc de texte enrichi à la place.
• Lors de la capture de texte qui ne sera consommé que et non réaffiché aux utilisateurs, utilisez un contrôle d’entrée de texte brut.
• Pour tous les autres scénarios, utilisez un contrôle d’entrée de texte brut.

Pour plus d’informations sur le choix du contrôle de texte approprié, consultez l’article Contrôles de texte.

Recommendations

• Quand vous créez une zone de texte enrichi, ajoutez des boutons de style et implémentez leurs actions.
• Utilisez une police cohérente avec le style de votre application.
• Faites en sorte que la hauteur du contrôle de texte soit suffisante pour recevoir des entrées classiques.
• Ne laissez pas les contrôles de saisie de texte s’allonger en hauteur quand les utilisateurs entrent le texte.
• N’utilisez pas de zone de texte de plusieurs lignes quand les utilisateurs n’ont besoin que d’une seule ligne.
• N’utilisez pas de contrôle de texte enrichi si un contrôle de texte brut est approprié.

Examples

Cette zone d’édition enrichie comporte un document de texte enrichi ouvert dans celui-ci. Les boutons de mise en forme et de fichier ne font pas partie de la zone d’édition enrichie, mais vous devez fournir au moins un ensemble minimal de boutons de style et implémenter leurs actions.

Créer une zone d’édition enrichie

L’application WinUI 3 Gallery inclut des exemples interactifs de la plupart des contrôles, des caractéristiques et des fonctionnalités de WinUI 3. Obtenir l’application à partir du Microsoft Store ou obtenir le code source sur GitHub

Par défaut, RichEditBox prend en charge la vérification orthographique. Pour désactiver le vérificateur orthographique, définissez la propriété IsSpellCheckEnabled sur false. Pour plus d’informations, consultez l’article Directives pour la vérification orthographique.

Vous utilisez la propriété Document de RichEditBox pour obtenir son contenu. Le contenu d’un objet RichEditBox est un objet ITextDocument , contrairement au contrôle RichTextBlock, qui utilise des objets Block comme contenu. L’interface ITextDocument permet de charger et d’enregistrer le document dans un flux, de récupérer des plages de texte, d’obtenir la sélection active, d’annuler et de rétablir les modifications, de définir les attributs de mise en forme par défaut, et ainsi de suite.

Cet exemple montre comment modifier, charger et enregistrer un fichier format de texte enrichi (.rtf) dans un 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;
    }
}

Utiliser une zone d’édition enrichie pour les équations mathématiques

RichEditBox peut afficher et modifier des équations mathématiques à l’aide de UnicodeMath. Les équations sont stockées et récupérées au format MathML 3.0 .

Par défaut, le contrôle RichEditBox n’interprète pas l’entrée en tant que mathématiques. Pour activer le mode mathématique, appelez SetMathMode sur la propriété TextDocument , en passant la valeur RichEditMathMode.MathOnly (pour désactiver le mode mathématique, appelez SetMathMode , mais passez la valeur NoMath).

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

Cela permet à l’entrée UnicodeMath d’être automatiquement reconnue et convertie en MathML en temps réel. Par exemple, la saisie de 4^2 convertit en 4² et 1/2 est convertie en 1/2. Pour plus d’exemples, consultez l’application Galerie WinUI 3 .

Pour enregistrer le contenu mathématique d’une zone d’édition enrichie sous forme de chaîne MathML, appelez GetMathML.

richEditBox.TextDocument.GetMathML(out String mathML);

Pour définir le contenu mathématique d’une zone d’édition enrichie, appelez SetMathML, en passant une chaîne MathML.

Choisir le clavier adapté à votre contrôle de texte

Pour aider les utilisateurs à entrer des données à l’aide du clavier tactile ou du panneau d’entrée réversible (SIP), vous pouvez définir l’étendue d’entrée du contrôle de texte pour qu’elle corresponde au type de données que l’utilisateur doit entrer. La disposition du clavier par défaut est généralement appropriée pour l’utilisation de documents de texte enrichi.

Pour plus d’informations sur l’utilisation des étendues d’entrée, consultez Utiliser l’étendue d’entrée pour modifier le clavier tactile.

UWP et WinUI 2

Les API de ce contrôle existent dans l’espace de noms Windows.UI.Xaml.Controls .

Nous vous recommandons d’utiliser la dernière version de WinUI 2 pour obtenir les styles et modèles les plus récents pour tous les contrôles. WinUI 2.2 ou version ultérieure inclut un nouveau modèle pour ce contrôle qui utilise des angles arrondis. Pour plus d’informations, voir Rayon d’angle.

Articles connexes

• Contrôles de texte
• Instructions pour la vérification orthographique
• Recommandations en matière d’entrée de texte
• Classe TextBox
• Classe PasswordBox