Créer et ajouter un style de caractère à un document de traitement de texte

Cette rubrique montre comment utiliser les classes du Kit de développement logiciel (SDK) Open XML pour Office afin de créer et d’ajouter par programmation un style de caractère à un document de traitement de texte. Il contient un exemple de méthode CreateAndAddCharacterStyle pour illustrer cette tâche, ainsi qu’un exemple de méthode supplémentaire pour ajouter la partie styles lorsque cela est nécessaire.

CreateAndAddCharacterStyle, méthode

L’exemple de méthode CreateAndAddCharacterStyle peut être utilisé pour ajouter un style à un document de traitement de texte. Vous devez d’abord obtenir une référence à la partie définitions de style dans le document auquel vous souhaitez ajouter le style. Consultez la section Appel de l’exemple de méthode pour obtenir un exemple montrant comment procéder.

La méthode accepte quatre paramètres qui indiquent : une référence à la partie des définitions de style, l’ID de style du style (identificateur interne), le nom du style (pour une utilisation externe dans l’interface utilisateur) et éventuellement, tous les alias de style (autres noms à utiliser dans l’interface utilisateur).

C#

    public static void CreateAndAddCharacterStyle(StyleDefinitionsPart styleDefinitionsPart,
        string styleid, string stylename, string aliases="")

Visual Basic

    Public Sub CreateAndAddCharacterStyle(ByVal styleDefinitionsPart As StyleDefinitionsPart, 
    ByVal styleid As String, ByVal stylename As String, Optional ByVal aliases As String = "")

La liste de code complète pour la méthode se trouve dans la section Exemple de code.

À propos des ID de style, des noms de style et des alias

L’ID de style est utilisé par le document pour faire référence au style et peut être considéré comme son identificateur principal. En règle générale, vous utilisez l’ID de style pour identifier un style dans le code. Un style peut également avoir un nom d’affichage distinct affiché dans l’interface utilisateur. Souvent, le nom du style apparaît donc dans la casse et avec un espacement (par exemple, Titre 1), tandis que l’ID de style est plus succinct (par exemple, heading1) et destiné à une utilisation interne. Les alias spécifient d’autres noms de style qui peuvent être utilisés dans l’interface utilisateur d’une application.

Par exemple, considérez l’exemple de code XML suivant tiré d’une définition de style.

    <w:style w:type="character" w:styleId="OverdueAmountChar" . . .
      <w:aliases w:val="Late Due, Late Amount" />
      <w:name w:val="Overdue Amount Char" />
    . . .
    </w:style>

L’attribut styleId de l’élément style définit l’identificateur interne main du style, l’ID de style (OverdueAmountChar). L’élément aliases spécifie deux autres noms de style, Late Due et Late Amount, qui sont séparés par des virgules. Chaque nom doit être séparé par une ou plusieurs virgules. Enfin, l’élément name spécifie le nom du style principal, qui est généralement affiché dans l’interface utilisateur d’une application.

Appel de la méthode de l’exemple

Vous pouvez utiliser l’exemple de méthode CreateAndAddCharacterStyle pour créer et ajouter un style nommé à un document de traitement de texte à l’aide du Kit de développement logiciel (SDK) Open XML. L’exemple de code suivant montre comment ouvrir et obtenir une référence à un document de traitement de texte, récupérer une référence à la partie des définitions de style du document, puis appeler la méthode CreateAndAddCharacterStyle .

Pour appeler la méthode, vous passez une référence à la partie définitions de style comme premier paramètre, l’ID de style du style comme deuxième paramètre, le nom du style comme troisième paramètre et éventuellement, tous les alias de style comme quatrième paramètre. Par exemple, l’exemple de code suivant crée le style de caractère « Overdue Amount Char » dans un exemple de fichier nommé CreateAndAddCharacterStyle.docx. Il crée également trois séries de texte dans un paragraphe et applique le style à la deuxième exécution.

C#

    string strDoc = @"C:\Users\Public\Documents\CreateAndAddCharacterStyle.docx";

    using (WordprocessingDocument doc = 
        WordprocessingDocument.Open(strDoc, true))
    {
        // Get the Styles part for this document.
        StyleDefinitionsPart part =
            doc.MainDocumentPart.StyleDefinitionsPart;

        // If the Styles part does not exist, add it.
        if (part == null)
        {
            part = AddStylesPartToPackage(doc);
        }

        // Create and add the character style with the style id, style name, and
        // aliases specified.
        CreateAndAddCharacterStyle(part,
            "OverdueAmountChar",
            "Overdue Amount Char",
            "Late Due, Late Amount");
        
        // Add a paragraph with a run with some text.
        Paragraph p = 
            new Paragraph(
                new Run(
                    new Text("this is some text "){Space = SpaceProcessingModeValues.Preserve}));
        
        // Add another run with some text.
        p.AppendChild<Run>(new Run(new Text("in a run "){Space = SpaceProcessingModeValues.Preserve}));
        
        // Add another run with some text.
        p.AppendChild<Run>(new Run(new Text("in a paragraph."){Space = SpaceProcessingModeValues.Preserve}));

        // Add the paragraph as a child element of the w:body.
        doc.MainDocumentPart.Document.Body.AppendChild(p);

        // Get a reference to the second run (indexed starting with 0).
        Run r = p.Descendants<Run>().ElementAtOrDefault(1);

        // If the Run has no RunProperties object, create one.
        if (r.Elements<RunProperties>().Count() == 0)
        {
            r.PrependChild<RunProperties>(new RunProperties());
        }
        
        // Get a reference to the RunProperties.
        RunProperties rPr = r.RunProperties;
        
        // Set the character style of the run.
        if (rPr.RunStyle == null)
            rPr.RunStyle = new RunStyle();
        rPr.RunStyle.Val = "OverdueAmountChar";

Visual Basic

    Dim strDoc As String = "C:\Users\Public\Documents\CreateAndAddCharacterStyle.docx"

    Using doc As WordprocessingDocument =
        WordprocessingDocument.Open(strDoc, True)

        ' Get the Styles part for this document.
        Dim part As StyleDefinitionsPart =
            doc.MainDocumentPart.StyleDefinitionsPart

        ' If the Styles part does not exist, add it.
        If part Is Nothing Then
            part = AddStylesPartToPackage(doc)
        End If

        ' Create and add the character style with the style id, style name, and
        ' aliases specified.
        CreateAndAddCharacterStyle(part,
            "OverdueAmountChar",
            "Overdue Amount Char",
            "Late Due, Late Amount")

        ' Add a paragraph with a run with some text.
        Dim p As New Paragraph(
            New Run(
                New Text("This is some text ") With { _
                    .Space = SpaceProcessingModeValues.Preserve}))

        ' Add another run with some text.
        p.AppendChild(Of Run)(New Run(New Text("in a run ") With { _
            .Space = SpaceProcessingModeValues.Preserve}))

        ' Add another run with some text.
        p.AppendChild(Of Run)(New Run(New Text("in a paragraph.") With { _
            .Space = SpaceProcessingModeValues.Preserve}))

        ' Add the paragraph as a child element of the w:body.
        doc.MainDocumentPart.Document.Body.AppendChild(p)

        ' Get a reference to the second run (indexed starting with 0).
        Dim r As Run = p.Descendants(Of Run)().ElementAtOrDefault(1)

        ' If the Run has no RunProperties object, create one.
        If r.Elements(Of RunProperties)().Count() = 0 Then
            r.PrependChild(Of RunProperties)(New RunProperties())
        End If

        ' Get a reference to the RunProperties.
        Dim rPr As RunProperties = r.RunProperties

        ' Set the character style of the run.
        If rPr.RunStyle Is Nothing Then
            rPr.RunStyle = New RunStyle()
        End If
        rPr.RunStyle.Val = "OverdueAmountChar"

    End Using

Style Types

WordprocessingML prend en charge six types de style, dont quatre que vous pouvez spécifier à l’aide de l’attribut type sur l’élément style. Les informations suivantes, issues de la section 17.7.4.17 de la spécification ISO/IEC 29500 , présentent les types de style.

Les types de style font référence à la propriété d’un style qui définit le type de style créé avec cette définition de style. WordprocessingML prend en charge six types de définitions de style par les valeurs de l’attribut de type de la définition de style :

• Styles de paragraphe
• Styles de caractères
• Styles liés (paragraphe + caractère) Accomplis via l’élément link (§17.7.4.6).
• Styles de tableau
• Styles de numérotation
• Propriétés de paragraphe + caractère par défaut

Considérez un style appelé Titre 1 dans un document, comme illustré dans l’exemple de code suivant.

    <w:style w:type="paragraph" w:styleId="Heading1">
      <w:name w:val="heading 1"/>
      <w:basedOn w:val="Normal"/>
      <w:next w:val="Normal"/>
      <w:link w:val="Heading1Char"/>
      <w:uiPriority w:val="1"/>
      <w:qformat/>
      <w:rsid w:val="00F303CE"/>
      …
    </w:style>

L’attribut type a une valeur de paragraphe, ce qui indique que la définition de style suivante est un style de paragraphe.

Vous pouvez définir les types de styles paragraphe, caractère, tableau et numérotation en spécifiant la valeur correspondante dans l’attribut type de l’élément de style.

Type de style de caractère

Vous spécifiez caractère comme type de style en définissant la valeur de l’attribut type sur l’élément de style sur « character ».

Les informations suivantes de la section 17.7.9 de la spécification ISO/IEC 29500 traitent des styles de caractères. N’oubliez pas que les numéros de section précédés de § indiquent les sections de la spécification ISO.

17.7.9 Styles d’exécution (caractère)

Les styles de caractères sont des styles qui s’appliquent au contenu d’une ou plusieurs séries de texte dans le contenu d’un document. Cette définition implique que le style peut uniquement définir des propriétés de caractère (propriétés qui s’appliquent au texte dans un paragraphe), car il ne peut pas être appliqué aux paragraphes. Les styles de caractères ne peuvent être référencés que par des exécutions dans un document, et ils doivent être référencés par l’élément rStyle dans les propriétés d’exécution d’une exécution.

Un style de caractère a deux caractéristiques propres au type de style :

• L’attribut type sur le style a une valeur de caractère, ce qui indique que la définition de style suivante est un style de caractère.

• Le style spécifie uniquement les propriétés de niveau caractère à l’aide de l’élément rPr. Dans ce cas, les propriétés d’exécution sont l’ensemble de propriétés appliquées à chaque exécution de ce style.

Le style de caractère est ensuite appliqué aux exécutions en référençant la valeur d’attribut styleId de ce style dans l’élément rStyle des propriétés d’exécution.

L’image suivante montre du texte auquel un style de caractère a été appliqué. Un style de caractère ne peut être appliqué qu’à une plage de texte au niveau du sous-paragraphe.

Figure 1. Texte avec un style de caractère appliqué

Fonctionnement du code

La méthode CreateAndAddCharacterStyle commence par récupérer une référence à l’élément styles dans la partie styles. L’élément styles est l’élément racine de la partie et contient tous les éléments de style individuels. Si la référence est null, l’élément styles est créé et enregistré dans le composant.

C#

    // Get access to the root element of the styles part.
        Styles styles = styleDefinitionsPart.Styles;
        if (styles == null)
        {
            styleDefinitionsPart.Styles = new Styles();
            styleDefinitionsPart.Styles.Save();
        }

Visual Basic

    ' Get access to the root element of the styles part.
        Dim styles As Styles = styleDefinitionsPart.Styles
        If styles Is Nothing Then
            styleDefinitionsPart.Styles = New Styles()
            styleDefinitionsPart.Styles.Save()
        End If

Création du style

Pour créer le style, le code instancie la classe Style et définit certaines propriétés, telles que le Type de style (paragraphe), le StyleId et si le style est un CustomStyle.

C#

    // Create a new character style and specify some of the attributes.
    Style style = new Style()
    {
        Type = StyleValues.Character,
        StyleId = styleid,
        CustomStyle = true
    };

Visual Basic

    ' Create a new character style and specify some of the attributes.
    Dim style As New Style() With { _
        .Type = StyleValues.Character, _
        .StyleId = styleid, _
        .CustomStyle = True}

Le code génère le code XML suivant.

    <w:style w:type="character" w:styleId="OverdueAmountChar" w:customStyle="true" xmlns:w="https://schemas.openxmlformats.org/wordprocessingml/2006/main">
    </w:style>

Le code crée ensuite les éléments enfants du style, qui définissent les propriétés du style. Pour créer un élément, vous instanciez sa classe correspondante, puis appelez la méthode Append([]) pour ajouter l’élément enfant au style. Pour plus d’informations sur ces propriétés, consultez la section 17.7 de la spécification ISO/IEC 29500 .

C#

    // Create and add the child elements (properties of the style).
    Aliases aliases1 = new Aliases() { Val = aliases };
    StyleName styleName1 = new StyleName() { Val = stylename };
    LinkedStyle linkedStyle1 = new LinkedStyle() { Val = "OverdueAmountPara" };
    if (aliases != "")
        style.Append(aliases1);
    style.Append(styleName1);
    style.Append(linkedStyle1);

Visual Basic

    ' Create and add the child elements (properties of the style).
    Dim aliases1 As New Aliases() With {.Val = aliases}
    Dim styleName1 As New StyleName() With {.Val = stylename}
    Dim linkedStyle1 As New LinkedStyle() With {.Val = "OverdueAmountPara"}
    If aliases <> "" Then
        style.Append(aliases1)
    End If
    style.Append(styleName1)
    style.Append(linkedStyle1)

Ensuite, le code instancie un objet StyleRunProperties pour créer un élément rPr (Run Properties). Vous spécifiez les propriétés de caractère qui s’appliquent au style, telles que la police et la couleur, dans cet élément. Les propriétés sont ensuite ajoutées en tant qu’enfants de l’élément rPr .

Lorsque les propriétés d’exécution sont créées, le code ajoute l’élément rPr au style et l’élément style à l’élément racine styles dans la partie styles.

C#

    // Create the StyleRunProperties object and specify some of the run properties.
    StyleRunProperties styleRunProperties1 = new StyleRunProperties();
    Bold bold1 = new Bold();
    Color color1 = new Color() { ThemeColor = ThemeColorValues.Accent2 };
    RunFonts font1 = new RunFonts() { Ascii = "Tahoma" };
    Italic italic1 = new Italic();
    // Specify a 24 point size.
    FontSize fontSize1 = new FontSize() { Val = "48" };
    styleRunProperties1.Append(font1);
    styleRunProperties1.Append(fontSize1);
    styleRunProperties1.Append(color1);
    styleRunProperties1.Append(bold1);
    styleRunProperties1.Append(italic1);

    // Add the run properties to the style.
    style.Append(styleRunProperties1);

    // Add the style to the styles part.
    styles.Append(style);

Visual Basic

    ' Create the StyleRunProperties object and specify some of the run properties.
    Dim styleRunProperties1 As New StyleRunProperties()
    Dim bold1 As New Bold()
    Dim color1 As New Color() With { _
        .ThemeColor = ThemeColorValues.Accent2}
    Dim font1 As New RunFonts() With {.Ascii = "Tahoma"}
    Dim italic1 As New Italic()
    ' Specify a 24 point size.
    Dim fontSize1 As New FontSize() With {.Val = "48"}
    styleRunProperties1.Append(font1)
    styleRunProperties1.Append(fontSize1)
    styleRunProperties1.Append(color1)
    styleRunProperties1.Append(bold1)
    styleRunProperties1.Append(italic1)

    ' Add the run properties to the style.
    style.Append(styleRunProperties1)

    ' Add the style to the styles part.
    styles.Append(style)

Le code XML suivant montre le style final généré par le code indiqué ici.

    <w:style w:type="character" w:styleId="OverdueAmountChar" w:customStyle="true" xmlns:w="https://schemas.openxmlformats.org/wordprocessingml/2006/main">
      <w:aliases w:val="Late Due, Late Amount" />
      <w:name w:val="Overdue Amount Char" />
      <w:link w:val="OverdueAmountPara" />
      <w:rPr>
        <w:rFonts w:ascii="Tahoma" />
        <w:sz w:val="48" />
        <w:color w:themeColor="accent2" />
        <w:b />
        <w:i />
      </w:rPr>
    </w:style>

Application du style de caractère

Une fois le style créé, vous pouvez l’appliquer à une exécution en référençant la valeur d’attribut styleId de ce style dans l’élément rStyle des propriétés d’exécution. L’exemple de code suivant montre comment appliquer un style à une exécution référencée par la variable r. L’ID de style du style à appliquer, OverdueAmountChar dans cet exemple, est stocké dans la propriété RunStyle de l’objet rPr . Cette propriété représente l’élément rStyle des propriétés d’exécution.

C#

    // If the Run has no RunProperties object, create one.
    if (r.Elements<RunProperties>().Count() == 0)
    {
        r.PrependChild<RunProperties>(new RunProperties());
    }

    // Get a reference to the RunProperties.
    RunProperties rPr = r.RunProperties;

    // Set the character style of the run.
    if (rPr.RunStyle == null)
        rPr.RunStyle = new RunStyle();
    rPr.RunStyle.Val = "OverdueAmountChar";

Visual Basic

    ' If the Run has no RunProperties object, create one.
    If r.Elements(Of RunProperties)().Count() = 0 Then
        r.PrependChild(Of RunProperties)(New RunProperties())
    End If

    ' Get a reference to the RunProperties.
    Dim rPr As RunProperties = r.RunProperties

    ' Set the character style of the run.
    If rPr.RunStyle Is Nothing Then
        rPr.RunStyle = New RunStyle()
    End If
    rPr.RunStyle.Val = "OverdueAmountChar"

Exemple de code

Voici l’exemple de code CreateAndAddCharacterStyle complet en C# et Visual Basic.

C#

using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;
using System;

CreateAndAddCharacterStyle(args[0], args[1], args[2], args[3]);

// Create a new character style with the specified style id, style name and aliases and 
// add it to the specified style definitions part.
static void CreateAndAddCharacterStyle(string filePath, string styleid, string stylename, string aliases = "")
{
    using (WordprocessingDocument wordprocessingDocument = WordprocessingDocument.Open(filePath, true))
    {
        // Get access to the root element of the styles part.
        Styles? styles = wordprocessingDocument?.MainDocumentPart?.StyleDefinitionsPart?.Styles ?? AddStylesPartToPackage(wordprocessingDocument).Styles;

        if (styles is not null)
        {
            // Create a new character style and specify some of the attributes.
            Style style = new Style()
            {
                Type = StyleValues.Character,
                StyleId = styleid,
                CustomStyle = true
            };

            // Create and add the child elements (properties of the style).
            Aliases aliases1 = new Aliases() { Val = aliases };
            StyleName styleName1 = new StyleName() { Val = stylename };
            LinkedStyle linkedStyle1 = new LinkedStyle() { Val = "OverdueAmountPara" };
            if (aliases != "")
                style.Append(aliases1);
            style.Append(styleName1);
            style.Append(linkedStyle1);

            // Create the StyleRunProperties object and specify some of the run properties.
            StyleRunProperties styleRunProperties1 = new StyleRunProperties();
            Bold bold1 = new Bold();
            Color color1 = new Color() { ThemeColor = ThemeColorValues.Accent2 };
            RunFonts font1 = new RunFonts() { Ascii = "Tahoma" };
            Italic italic1 = new Italic();
            // Specify a 24 point size.
            FontSize fontSize1 = new FontSize() { Val = "48" };
            styleRunProperties1.Append(font1);
            styleRunProperties1.Append(fontSize1);
            styleRunProperties1.Append(color1);
            styleRunProperties1.Append(bold1);
            styleRunProperties1.Append(italic1);

            // Add the run properties to the style.
            style.Append(styleRunProperties1);

            // Add the style to the styles part.
            styles.Append(style);
        }
    }
}

// Add a StylesDefinitionsPart to the document.  Returns a reference to it.
static StyleDefinitionsPart AddStylesPartToPackage(WordprocessingDocument? doc)
{
    StyleDefinitionsPart part;

    if (doc?.MainDocumentPart is null)
    {
        throw new ArgumentNullException("MainDocumentPart is null.");
    }

    part = doc.MainDocumentPart.AddNewPart<StyleDefinitionsPart>();
    Styles root = new Styles();
    root.Save(part);
    return part;
}

Visual Basic

Imports DocumentFormat.OpenXml.Packaging
Imports DocumentFormat.OpenXml.Wordprocessing
Imports Bold = DocumentFormat.OpenXml.Wordprocessing.Bold
Imports Color = DocumentFormat.OpenXml.Wordprocessing.Color
Imports FontSize = DocumentFormat.OpenXml.Wordprocessing.FontSize
Imports Italic = DocumentFormat.OpenXml.Wordprocessing.Italic

Module Program
    Sub Main(args As String())
    End Sub


    ' Create a new character style with the specified style id, style name and aliases and add 
    ' it to the specified style definitions part.
    Public Sub CreateAndAddCharacterStyle(ByVal styleDefinitionsPart As StyleDefinitionsPart,
        ByVal styleid As String, ByVal stylename As String, Optional ByVal aliases As String = "")
        ' Get access to the root element of the styles part.
        Dim styles As Styles = styleDefinitionsPart.Styles
        If styles Is Nothing Then
            styleDefinitionsPart.Styles = New Styles()
            styleDefinitionsPart.Styles.Save()
        End If

        ' Create a new character style and specify some of the attributes.
        Dim style As New Style() With {
            .Type = StyleValues.Character,
            .StyleId = styleid,
            .CustomStyle = True}

        ' Create and add the child elements (properties of the style).
        Dim aliases1 As New Aliases() With {.Val = aliases}
        Dim styleName1 As New StyleName() With {.Val = stylename}
        Dim linkedStyle1 As New LinkedStyle() With {.Val = "OverdueAmountPara"}
        If aliases <> "" Then
            style.Append(aliases1)
        End If
        style.Append(styleName1)
        style.Append(linkedStyle1)

        ' Create the StyleRunProperties object and specify some of the run properties.
        Dim styleRunProperties1 As New StyleRunProperties()
        Dim bold1 As New Bold()
        Dim color1 As New Color() With {
            .ThemeColor = ThemeColorValues.Accent2}
        Dim font1 As New RunFonts() With {.Ascii = "Tahoma"}
        Dim italic1 As New Italic()
        ' Specify a 24 point size.
        Dim fontSize1 As New FontSize() With {.Val = "48"}
        styleRunProperties1.Append(font1)
        styleRunProperties1.Append(fontSize1)
        styleRunProperties1.Append(color1)
        styleRunProperties1.Append(bold1)
        styleRunProperties1.Append(italic1)

        ' Add the run properties to the style.
        style.Append(styleRunProperties1)

        ' Add the style to the styles part.
        styles.Append(style)
    End Sub

    ' Add a StylesDefinitionsPart to the document.  Returns a reference to it.
    Public Function AddStylesPartToPackage(ByVal doc As WordprocessingDocument) _
        As StyleDefinitionsPart
        Dim part As StyleDefinitionsPart
        part = doc.MainDocumentPart.AddNewPart(Of StyleDefinitionsPart)()
        Dim root As New Styles()
        root.Save(part)
        Return part
    End Function
End Module

Voir aussi

Guide pratique pour appliquer un style à un paragraphe dans un document de traitement de texte Référence debibliothèque de classes du Kit de développement logiciel (SDK) Open XML