Compartilhar via

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

  • Artigo

Este tópico mostra como utilizar as classes no SDK Open XML para o Office para criar e adicionar programaticamente um estilo de caráter a um documento de processamento de palavras. Contém um método de exemplo CreateAndAddCharacterStyle para ilustrar esta tarefa, além de um método de exemplo suplementar para adicionar a parte de estilos quando for necessário.

CreateAndAddCharacterStyle Method

O CreateAndAddCharacterStyle método de exemplo pode ser utilizado para adicionar um estilo a um documento de processamento de palavras. Primeiro, tem de obter uma referência à parte de definições de estilo no documento ao qual pretende adicionar o estilo. Veja a secção Chamar o Método de Exemplo para obter um exemplo que mostra como fazê-lo.

O método aceita quatro parâmetros que indicam: o caminho para o ficheiro a editar, o ID de estilo do estilo (um identificador interno), o nome do estilo (para utilização externa na interface de utilizador) e, opcionalmente, quaisquer aliases de estilo (nomes alternativos para utilização na interface de utilizador).

static void CreateAndAddCharacterStyle(string filePath, string styleid, string stylename, string aliases = "")

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

Acerca de IDs de Estilo, Nomes de Estilo e Aliases

O ID de estilo é utilizado pelo documento para fazer referência ao estilo e pode ser considerado como o identificador principal. Normalmente, utiliza o ID de estilo para identificar um estilo no código. Um estilo também pode ter um nome a apresentar separado apresentado na interface de utilizador. Muitas vezes, o nome do estilo, portanto, aparece em maiúsculas e minúsculas e com espaçamento (por exemplo, Título 1), enquanto o ID de estilo é mais sucinta (por exemplo, cabeçalho1) e destina-se a utilização interna. Os aliases especificam nomes de estilo alternativos que podem ser utilizados na interface de utilizador de uma aplicação.

Por exemplo, considere o seguinte exemplo de código XML retirado 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 de elemento styleId de estilo define o main identificador interno do estilo, o ID de estilo (OverdueAmountChar). O elemento aliases especifica dois nomes de estilo alternativos, Late Due e Late Amount, que estão separados por vírgulas. Cada nome tem de ser separado por uma ou mais vírgulas. Por fim, o elemento name especifica o nome do estilo primário, que é o normalmente apresentado na interface de utilizador de uma aplicação.

Chamar o Método de Exemplo

Pode utilizar o CreateAndAddCharacterStyle método de exemplo para criar e adicionar um estilo com nome a um documento de processamento de palavras com o SDK Open XML. O seguinte exemplo de código mostra como abrir e obter uma referência a um documento de processamento de palavras, obter uma referência à parte de definições de estilo do documento e, em seguida, chamar o CreateAndAddCharacterStyle método .

Para chamar o método , transmita uma referência ao ficheiro para editar como o primeiro parâmetro, o ID de estilo do estilo como segundo parâmetro, o nome do estilo como o terceiro parâmetro e, opcionalmente, quaisquer aliases de estilo como o quarto parâmetro. Por exemplo, o exemplo de código seguinte cria o estilo de caráter "Valor Em Atraso" num ficheiro de exemplo com o nome do primeiro argumento para o método . Também cria três execuções de texto num parágrafo e aplica o estilo à segunda execução.

static void AddStylesToPackage(string filePath)
{
    // Create and add the character style with the style id, style name, and
    // aliases specified.
    CreateAndAddCharacterStyle(
        filePath,
        "OverdueAmountChar",
        "Overdue Amount Char",
        "Late Due, Late Amount");

    using (WordprocessingDocument doc = WordprocessingDocument.Open(filePath, true))
    {

        // 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 and get a reference to it.
        RunProperties rPr = r.RunProperties ?? r.PrependChild(new RunProperties());

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

Tipos de Estilo

O WordprocessingML suporta seis tipos de estilo, quatro dos quais pode especificar com o atributo type no elemento de estilo. As seguintes informações, da secção 17.7.4.17 na especificação ISO/IEC 29500 , introduzem tipos de estilo.

Os tipos de estilo referem-se à propriedade num estilo que define o tipo de estilo criado com esta definição de estilo. O WordprocessingML suporta seis tipos de definições de estilo pelos valores do atributo de tipo da definição de estilo:

  • Estilos de parágrafo
  • Estilos de carateres
  • Estilos ligados (parágrafo + caráter) Realizados através do elemento de ligação (}17.7.4.6).
  • Table styles
  • Estilos de numeração
  • Propriedades predefinidas de parágrafo + caráter

Considere um estilo chamado Cabeçalho 1 num documento, conforme mostrado no seguinte exemplo de código.

    <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 type tem um valor de parágrafo, o que indica que a seguinte definição de estilo é um estilo de parágrafo.

Pode definir os tipos de estilos de parágrafo, caráter, tabela e numeração ao especificar o valor correspondente no atributo de tipo do elemento de estilo.

Tipo de Estilo de Caráter

Especifique o caráter como o tipo de estilo ao definir o valor do atributo de tipo no elemento de estilo como "caráter".

As seguintes informações da secção 17.7.9 da especificação ISO/IEC 29500 abordam os estilos de carateres. Tenha em atenção que os números de secção precedidos por indicação de secções na especificação ISO.

Estilos de Execução (Caráter) 17.7.9

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

Um estilo de caráter tem duas características específicas do tipo de estilo:

  • O atributo type no estilo tem um valor de caráter, o que indica que a seguinte definição de estilo é um estilo de caráter.

  • O estilo especifica apenas propriedades ao nível do caráter com o rPr elemento . Neste caso, as propriedades de execução são o conjunto de propriedades aplicadas a cada execução que é deste estilo.

Em seguida, o estilo de carateres é aplicado às execuções ao referenciar o valor do styleId atributo para este estilo no elemento das propriedades de rStyle execução.

A imagem seguinte mostra algum texto que tenha um estilo de carateres aplicado. Um estilo de caráter só pode ser aplicado a um intervalo de texto ao nível do sub-parágrafo.

Figura 1. Texto com um estilo de carateres aplicado

Um estilo de carateres aplicado a algum texto

Como Funciona o Código

O CreateAndAddCharacterStyle método começa por abrir o ficheiro especificado e obter uma referência ao elemento estilos na parte 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 estilos é criado e guardado na peça.

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;

Criar o Estilo

Para criar o estilo, o código instancia a Style classe e define determinadas propriedades, como o Type estilo (parágrafo), o StyleIde se o estilo é um CustomStyle.

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

O código resulta no seguinte XML.

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

Em seguida, o código cria os elementos subordinados do estilo, que definem as propriedades do estilo. Para criar um elemento, instancia a respetiva classe correspondente e, em seguida, chama o Append método para adicionar o elemento subordinado ao estilo. Para obter mais informações sobre estas propriedades, consulte a secção 17.7 da especificação ISO/IEC 29500 .

// 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 (!String.IsNullOrEmpty(aliases))
{
    style.Append(aliases1);
}

style.Append(styleName1);
style.Append(linkedStyle1);

Em seguida, o código instancia um StyleRunProperties objeto para criar um rPr elemento (Propriedades de Execução). Especifique as propriedades de carateres que se aplicam ao estilo, como o tipo de letra e a cor, neste elemento. Em seguida, as propriedades são acrescentadas como subordinados do rPr elemento .

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

// 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);

O XML seguinte mostra o estilo final gerado pelo código apresentado aqui.

    <w:style w:type="character" w:styleId="OverdueAmountChar" w:customStyle="true" xmlns:w="http://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>

Aplicar o Estilo de Caráter

Depois de criar o estilo, pode aplicá-lo a uma execução ao referenciar o valor do styleId atributo para este estilo no elemento das propriedades de rStyle execução. O exemplo de código seguinte mostra como aplicar um estilo a uma execução referenciada pela variável r. O ID de estilo do estilo a aplicar, OverdueAmountChar neste exemplo, é armazenado na propriedade RunStyle do rPr objeto. Esta propriedade representa o elemento das propriedades de rStyle execução.

// If the Run has no RunProperties object, create one and get a reference to it.
RunProperties rPr = r.RunProperties ?? r.PrependChild(new RunProperties());

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

Código de exemplo

Segue-se o exemplo de código completo CreateAndAddCharacterStyle em C# e Visual Basic.

// Create a new character style with the specified style id, style name and aliases and 
// add it to the specified file.
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 (!String.IsNullOrEmpty(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();

    return part;
}

Confira também

Como: Aplicar um estilo a um parágrafo num documento de processamento de palavras

Open XML SDK class library reference (Referência da biblioteca de classes SDK Open XML)