Criar e adicionar estilo de caracteres em um documento de processamento de texto

Este tópico mostra como usar as classes no SDK Open XML para Office para criar e adicionar programaticamente um estilo de caractere a um documento de processamento de palavras. Ele contém um método CreateAndAddCharacterStyle de exemplo para ilustrar essa tarefa, além de um método de exemplo suplementar para adicionar a parte de estilos quando for necessário.

Método CreateAndAddCharacterStyle

O método de exemplo CreateAndAddCharacterStyle pode ser usado para adicionar um estilo a um documento de processamento de palavras. Primeiro, você deve obter uma referência à parte definições de estilo no documento ao qual deseja adicionar o estilo. Consulte a seção Chamando o Método de Exemplo para obter um exemplo que mostra como fazer isso.

O método aceita quatro parâmetros que indicam: uma referência à parte definições de estilo, a ID de estilo (um identificador interno), o nome do estilo (para uso externo na interface do usuário) e, opcionalmente, quaisquer aliases de estilo (nomes alternativos para uso na interface do usuário).

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 = "")

A listagem de código completa para o método pode ser encontrada na seção Código de Exemplo .

Sobre IDs de estilo, nomes de estilo e aliases

A ID de estilo é usada pelo documento para se referir ao estilo e pode ser considerada como seu identificador primário. Normalmente, você usa a ID de estilo para identificar um estilo no código. Um estilo também pode ter um nome de exibição separado mostrado na interface do usuário. Geralmente, o nome de estilo, portanto, aparece no caso adequado e com espaçamento (por exemplo, Título 1), enquanto a ID de estilo é mais sucinta (por exemplo, título1) e destina-se ao uso interno. Os aliases especificam nomes de estilo alternativos que podem ser usados na interface do usuário de um aplicativo.

Por exemplo, considere o exemplo de código XML a seguir extraído de uma definição de estilo.

    <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>

O atributo style elementId define o main identificador interno do estilo, a ID de estilo (OverdueAmountChar). O elemento aliases especifica dois nomes de estilo alternativos, Late Due e Late Amount, que são separados por vírgula. Cada nome deve ser separado por uma ou mais vírgulas. Por fim, o elemento nome especifica o nome de estilo primário, que é o normalmente mostrado na interface de usuário de um aplicativo.

Chamando o método de exemplo

Você pode usar o método de exemplo CreateAndAddCharacterStyle para criar e adicionar um estilo nomeado a um documento de processamento de palavras usando o SDK Open XML. O exemplo de código a seguir mostra como abrir e obter uma referência a um documento de processamento de palavras, recuperar uma referência à parte de definições de estilo do documento e, em seguida, chamar o método CreateAndAddCharacterStyle .

Para chamar o método, você passa uma referência à parte definições de estilo como o primeiro parâmetro, a ID de estilo do estilo como o segundo parâmetro, o nome do estilo como o terceiro parâmetro e, opcionalmente, qualquer alias de estilo como o quarto parâmetro. Por exemplo, o exemplo de código a seguir cria o estilo de caractere "Overdue Amount Char" em um arquivo de exemplo chamado CreateAndAddCharacterStyle.docx. Ele também cria três execuções de texto em um parágrafo e aplica o estilo à segunda execução.

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

Tipos de estilo

WordprocessingML dá suporte a seis tipos de estilo, quatro dos quais você pode especificar usando o atributo de tipo no elemento style. As informações a seguir, da seção 17.7.4.17 na especificação ISO/IEC 29500 , introduz tipos de estilo.

Tipos de estilo referem-se à propriedade em um estilo que define o tipo de estilo criado com essa definição de estilo. WordprocessingML dá suporte a seis tipos de definições de estilo pelos valores para o atributo de tipo da definição de estilo:

• Estilos de parágrafo
• Estilos de caractere
• Estilos vinculados (parágrafo + caractere) Realizados por meio do elemento link (§17.7.4.6).
• Table styles
• Estilos de numeração
• Parágrafo padrão + propriedades de caractere

Considere um estilo chamado Título 1 em um documento, conforme mostrado no exemplo de código a seguir.

    <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>

O atributo de tipo tem um valor de parágrafo, o que indica que a definição de estilo a seguir é um estilo de parágrafo.

Você pode definir os tipos de estilos de parágrafo, caractere, tabela e numeração especificando o valor correspondente no atributo de tipo do elemento de estilo.

Tipo de estilo de caractere

Especifique o caractere como o tipo de estilo definindo o valor do atributo de tipo no elemento de estilo como "caractere".

As informações a seguir da seção 17.7.9 da especificação ISO/IEC 29500 discutem estilos de caracteres. Lembre-se de que os números de seção precedidos por § indicam seções na especificação ISO.

17.7.9 Executar estilos (caracteres)

Estilos de caractere são estilos que se aplicam ao conteúdo de uma ou mais execuções de texto no conteúdo de um documento. Essa definição implica que o estilo só pode definir propriedades de caractere (propriedades que se aplicam ao texto dentro de um parágrafo) porque ela não pode ser aplicada a parágrafos. Os estilos de caractere só podem ser referenciados por execuções dentro de um documento e devem ser referenciados pelo elemento rStyle no conjunto de propriedades de execução de uma execução.

Um estilo de caractere tem duas características específicas do tipo de estilo:

• O atributo de tipo no estilo tem um valor de caractere, o que indica que a definição de estilo a seguir é um estilo de caractere.

• O estilo especifica apenas propriedades no nível do caractere usando o elemento rPr. Nesse caso, as propriedades de execução são o conjunto de propriedades aplicadas a cada execução que é desse estilo.

Em seguida, o estilo de caractere é aplicado a execuções fazendo referência ao valor de atributo styleId para esse estilo no elemento rStyle das propriedades de execução.

A imagem a seguir mostra algum texto que teve um estilo de caractere aplicado. Um estilo de caractere só pode ser aplicado a um intervalo de nível de parágrafo abaixo do texto.

Figura 1. Texto com um estilo de caractere aplicado

Como o código funciona

O método CreateAndAddCharacterStyle começa recuperando uma referência ao elemento styles na parte de estilos. O elemento styles é o elemento raiz da parte e contém todos os elementos de estilo individuais. Se a referência for nula, o elemento styles será criado e salvo na parte.

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

Criando o Estilo

Para criar o estilo, o código instancia a classe Style e define determinadas propriedades, como o tipo de estilo (parágrafo), o StyleId e se o estilo é um 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}

O código resulta no XML a seguir.

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

O código em seguida cria os elementos filho do estilo, que definem as propriedades do estilo. Para criar um elemento, instancie sua classe correspondente e, em seguida, chame o método Append([]) para adicionar o elemento filho ao estilo. Para obter mais informações sobre essas propriedades, consulte a seção 17.7 da especificação 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)

Em seguida, o código instancia um objeto StyleRunProperties para criar um elemento rPr (Propriedades de Execução ). Você especifica as propriedades de caractere que se aplicam ao estilo, como fonte e cor, nesse elemento. As propriedades são então acrescentadas como filhos do elemento rPr .

Quando as propriedades de execução são criadas, o código acrescenta o elemento rPr ao estilo e o elemento de estilo ao elemento raiz de estilos na parte estilos.

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)

O XML a seguir mostra o estilo final gerado pelo código mostrado aqui.

    <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>

Aplicando o estilo de caractere

Depois de criar o estilo, você pode aplicá-lo a uma execução fazendo referência ao valor de atributo styleId para esse estilo no elemento rStyle das propriedades de execução. O exemplo de código a seguir mostra como aplicar um estilo a uma execução referenciada pela variável r. A ID de estilo do estilo a ser aplicado, OverdueAmountChar neste exemplo, é armazenada na propriedade RunStyle do objeto rPr . Essa propriedade representa o elemento rStyle das propriedades de execução.

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"

Código de exemplo

A seguir está o exemplo de código CreateAndAddCharacterStyle completo no C# e no 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

Confira também

Como aplicar um estilo a um parágrafo em um documento de processamento de palavrasAbrir referência de biblioteca de classes do SDK XML