Como trabalhar com slides de anotações

Este tópico discute o Open XML SDK para a classe Office NotesSlide e como ele se relaciona com o esquema PresentationML do Open XML File Format.

Anotações Slides no PresentationML

A especificação ISO/IEC 29500 descreve o elemento Open XML PresentationML <notes/> usado para representar slides de notas em um documento PresentationML da seguinte maneira:

Este elemento especifica a existência de um slide de anotações junto com seus dados correspondentes. Contidos em um slide de anotações estão todos os elementos comuns do slide, juntamente com propriedades adicionais que são específicas do elemento anotações.

Exemplo: considere o seguinte slide de anotações PresentationML:

<p:notes>
    <p:cSld>
        …
    </p:cSld>
    …
</p:notes>

No exemplo acima, um elemento de anotações especifica a existência de um slide de anotações com todas as suas partes. Observe o elemento cSld, que especifica os elementos comuns que podem aparecer em qualquer tipo de slide e, em seguida, quaisquer elementos especificam propriedades não comuns adicionais para este slide de anotações.

© ISO/IEC 29500: 2016

O <notes/> elemento é o elemento raiz da parte do Slide de Anotações PresentationML. Para obter mais informações sobre a estrutura geral das partes e elementos que compõem um documento PresentationML, consulte Estrutura de um documento PresentationML.

A tabela a seguir lista os elementos filho do <notes/> elemento usado ao trabalhar com slides de notas e as classes Open XML SDK que correspondem a eles.

Elemento PresentationML Classe Open XML SDK
<clrMapOvr/> ColorMapOverride
<cSld/> CommonSlideData
<extLst/> ExtensionListWithModification

A tabela a seguir da especificação ISO/IEC 29500 descreve os atributos do <notes/> elemento.

Atributos Description
showMasterPhAnim (Mostrar animações de espaço reservado mestre) Especifica se as animações devem ou não ser exibidas nos espaços reservados do slide master.

Os valores possíveis para esse atributo são definidos pelo tipo de dados Esquema boolean XML do W3C.
showMasterSp (Mostrar Formas Mestras) Especifica se as formas no slide master devem ser mostradas nos slides ou não.

Os valores possíveis para esse atributo são definidos pelo tipo de dados Esquema boolean XML do W3C.

© ISO/IEC 29500: 2016

Open XML SDK Classe NotesSlide

A classe OXML SDK NotesSlide representa o <notes/> elemento definido no esquema Open XML File Format para documentos PresentationML. Use a NotesSlide classe para manipular elementos individuais <notes/> em um documento PresentationML.

As classes que representam elementos filho do <notes/> elemento e que, portanto, são comumente associados à NotesSlide classe são mostradas na lista a seguir.

  • Classe ColorMapOverride

    A ColorMapOverride classe corresponde ao <clrMapOvr/> elemento. As seguintes informações da especificação ISO/IEC 29500 introduzem o <clrMapOvr/> elemento:

    Esse elemento fornece um mecanismo para substituir os esquemas de cores listados no <ClrMap/> elemento. Se o <masterClrMapping/> elemento filho estiver presente, o esquema de cores definido pelo master será usado. Se o <overrideClrMapping/> elemento filho estiver presente, ele definirá um novo esquema de cores específico para o slide de anotações pai, o slide de apresentação ou o layout do slide.

© ISO/IEC 29500: 2016

  • Classe CommonSlideData

    A CommonSlideData classe corresponde ao <cSld/> elemento. As seguintes informações da especificação ISO/IEC 29500 introduzem o <cSld/> elemento:

    Esse elemento especifica um contêiner para o tipo de informações de slide que é relevante para todos os tipos de slide. Todos os slides compartilham um conjunto comum de propriedades que é independente do tipo de slide; A descrição dessas propriedades para qualquer slide específico é armazenada no contêiner do <cSld/> slide. Os dados de slide específicos do tipo de slide indicado pelo elemento pai são armazenados em outro lugar.

    Os dados reais descrevem <cSld/> apenas o slide pai específico; é apenas o tipo de informação armazenada que é comum em todos os slides.

    © ISO/IEC 29500: 2016

  • Classe ExtensionListWithModification

    A ExtensionListWithModification classe corresponde ao <extLst/>elemento. As seguintes informações da especificação ISO/IEC 29500 introduzem o <extLst/> elemento:

    Este elemento especifica a lista de extensões com capacidade de modificação dentro da qual todas as extensões futuras do tipo <ext/> de elemento são definidas. A lista de extensão, juntamente com as extensões futuras correspondentes, é usada para estender os recursos de armazenamento da estrutura PresentationML. Isso permite que vários novos tipos de dados sejam armazenados nativamente na estrutura.

    [Observação: o uso desse elemento extLst permite que o aplicativo gerador armazene se essa propriedade de extensão foi modificada. nota final]

    © ISO/IEC 29500: 2016

Trabalhando com a classe NotesSlide

Conforme mostrado no exemplo de código do Open XML SDK a seguir, cada instância da classe está associada a uma instância da classe, que representa uma parte do slide de anotações, uma das partes de um pacote de arquivos de apresentação PresentationML e uma parte que é necessária para cada slide de anotações em um arquivo de NotesSlideNotesSlidePart apresentação. Cada NotesSlide instância de classe também pode ser associada a NotesMaster uma instância da classe, que por sua vez está associada a uma parte de apresentação com nome semelhante, representada pela NotesMasterPart classe.

A NotesSlide classe, que representa o <notes/> elemento, também está, portanto, associada a uma série de outras classes que representam os elementos filho do <notes/> elemento. Entre essas classes, conforme mostrado no exemplo de código a seguir, estão a classe e a CommonSlideDataColorMapOverride classe. A ShapeTree classe e as Shape classes são, por sua vez, CommonSlideData associadas à classe.

Exemplo de código do Open XML SDK

Nos snippets P de código a seguir representa o DocumentFormat.OpenXml.Presentation namespace e D representa o namespace.

No trecho abaixo, uma apresentação é aberta e Presentation.Open a primeira SlidePart é recuperada ou adicionada se a apresentação ainda não tiver um SlidePart.

using (PresentationDocument presentationDocument = PresentationDocument.Open(pptxPath, true) ?? throw new Exception("Presentation Document does not exist"))
{
    // Get the first slide in the presentation or use the InsertNewSlide.InsertNewSlideIntoPresentation helper method to insert a new slide.
    SlidePart slidePart = presentationDocument.PresentationPart?.SlideParts.FirstOrDefault() ?? InsertNewSlideNS.InsertNewSlide(presentationDocument, 1, "my new slide");

    // Add a new NoteSlidePart if one does not already exist
    NotesSlidePart notesSlidePart = slidePart.NotesSlidePart ?? slidePart.AddNewPart<NotesSlidePart>();

Neste trecho, o a NoteSlide é adicionado ao NoteSlidePart se um ainda não existir. O NotesSlide construtor de classe cria instâncias da CommonSlideData classe. O CommonSlideData construtor de classe cria uma instância da ShapeTree classe, cujo construtor, por sua vez, cria instâncias de classe adicionais: uma instância da NonVisualGroupShapeProperties classe, uma instância da GroupShapeProperties classe e uma instância da Shape classe.

// Add a NoteSlide to the NoteSlidePart if one does not already exist.
notesSlidePart.NotesSlide ??= new P.NotesSlide(
    new P.CommonSlideData(
        new P.ShapeTree(
            new P.NonVisualGroupShapeProperties(
                new P.NonVisualDrawingProperties() { Id = 1, Name = "" },
                new P.NonVisualGroupShapeDrawingProperties(),
                new P.ApplicationNonVisualDrawingProperties()),
            new P.GroupShapeProperties(
                new D.Transform2D(
                    new D.Offset() { X = 0, Y = 0 },
                    new D.Extents() { Cx = 0, Cy = 0 },
                    new D.ChildOffset() { X = 0, Y = 0 },
                    new D.ChildExtents() { Cx = 0, Cy = 0 })),

O Shape construtor cria uma instância de NonVisualShapeProperties, ShapeProperties, e TextBody classes junto com seus elementos filho necessários. O TextBody contém o Paragraph, que tem um Run, que contém o texto da nota. A parte do slide é adicionada à parte do slide de anotações.

            new P.Shape(
                new P.NonVisualShapeProperties(
                    new P.NonVisualDrawingProperties() { Id = 3, Name = "test Placeholder 3" },
                    new P.NonVisualShapeDrawingProperties(),
                    new P.ApplicationNonVisualDrawingProperties(
                        new P.PlaceholderShape() { Type = PlaceholderValues.Body, Index = 1 })),
                new P.ShapeProperties(),
                new P.TextBody(
                    new D.BodyProperties(),
                    new D.Paragraph(
                        new D.Run(
                            new D.Text("This is a test note!"))))))));

notesSlidePart.AddPart(slidePart);

A parte do slide de anotações criada com o código acima contém o seguinte XML

<?xml version="1.0" encoding="utf-8"?>
<p:notes xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main">
  <p:cSld>
    <p:spTree>
      <p:nvGrpSpPr>
        <p:cNvPr id="1" name=""/>
        <p:cNvGrpSpPr/>
        <p:nvPr/>
      </p:nvGrpSpPr>
      <p:grpSpPr>
        <a:xfrm xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
          <a:off x="0" y="0"/>
          <a:ext cx="0" cy="0"/>
          <a:chOff x="0" y="0"/>
          <a:chExt cx="0" cy="0"/>
        </a:xfrm>
      </p:grpSpPr>
      <p:sp>
        <p:nvSpPr>
          <p:cNvPr id="3" name="test Placeholder 3"/>
          <p:cNvSpPr/>
          <p:nvPr/>
        </p:nvSpPr>
        <p:spPr/>
        <p:txBody>
          <a:bodyPr xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"/>
          <a:p xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
            <a:r>
              <a:t>This is a test note!</a:t>
            </a:r>
          </a:p>
        </p:txBody>
      </p:sp>
    </p:spTree>
  </p:cSld>
</p:notes>

Os snippets a seguir adicionam o necessário NotesMasterPart e ThemePart se eles estão ausentes.

// Add the required NotesMasterPart if it is missing
NotesMasterPart notesMasterPart = notesSlidePart.NotesMasterPart ?? notesSlidePart.AddNewPart<NotesMasterPart>();

// Add a NotesMaster to the NotesMasterPart if not present
notesMasterPart.NotesMaster ??= new NotesMaster(
new P.CommonSlideData(
    new P.ShapeTree(
        new P.NonVisualGroupShapeProperties(
            new P.NonVisualDrawingProperties() { Id = 1, Name = "New Placeholder" },
            new P.NonVisualGroupShapeDrawingProperties(),
            new P.ApplicationNonVisualDrawingProperties()),
        new P.GroupShapeProperties())),
new P.ColorMap()
{
    Background1 = D.ColorSchemeIndexValues.Light1,
    Background2 = D.ColorSchemeIndexValues.Light2,
    Text1 = D.ColorSchemeIndexValues.Dark1,
    Text2 = D.ColorSchemeIndexValues.Dark2,
    Accent1 = D.ColorSchemeIndexValues.Accent1,
    Accent2 = D.ColorSchemeIndexValues.Accent2,
    Accent3 = D.ColorSchemeIndexValues.Accent3,
    Accent4 = D.ColorSchemeIndexValues.Accent4,
    Accent5 = D.ColorSchemeIndexValues.Accent5,
    Accent6 = D.ColorSchemeIndexValues.Accent6,
    Hyperlink = D.ColorSchemeIndexValues.Hyperlink,
    FollowedHyperlink = D.ColorSchemeIndexValues.FollowedHyperlink,
});

// Add a new ThemePart for the NotesMasterPart
ThemePart themePart = notesMasterPart.ThemePart ?? notesMasterPart.AddNewPart<ThemePart>();

// Add the Theme if it is missing
themePart.Theme ??= new Theme(
    new ThemeElements(
        new ColorScheme(
            new Dark1Color(
                new SystemColor() { Val = SystemColorValues.WindowText }),
            new Light1Color(
                new SystemColor() { Val = SystemColorValues.Window }),
            new Dark2Color(
                new RgbColorModelHex() { Val = "f1d7be" }),
            new Light2Color(
                new RgbColorModelHex() { Val = "171717" }),
            new Accent1Color(
                new RgbColorModelHex() { Val = "ea9f7d" }),
            new Accent2Color(
                new RgbColorModelHex() { Val = "168ecd" }),
            new Accent3Color(
                new RgbColorModelHex() { Val = "e694db" }),
            new Accent4Color(
                new RgbColorModelHex() { Val = "f0612a" }),
            new Accent5Color(
                new RgbColorModelHex() { Val = "5fd46c" }),
            new Accent6Color(
                new RgbColorModelHex() { Val = "b158d1" }),
            new D.Hyperlink(
                new RgbColorModelHex() { Val = "699f82" }),
            new FollowedHyperlinkColor(
                new RgbColorModelHex() { Val = "699f82" }))
        { Name = "Office2" },
        new D.FontScheme(
            new MajorFont(
                new LatinFont(),
                new EastAsianFont(),
                new ComplexScriptFont()),
            new MinorFont(
                new LatinFont(),
                new EastAsianFont(),
                new ComplexScriptFont()))
        { Name = "Office2" },
        new FormatScheme(
            new FillStyleList(
                new NoFill(),
                new SolidFill(),
                new D.GradientFill(),
                new D.BlipFill(),
                new D.PatternFill(),
                new GroupFill()),
            new LineStyleList(
                new D.Outline(),
                new D.Outline(),
                new D.Outline()),
            new EffectStyleList(
                new EffectStyle(
                    new EffectList()),
                new EffectStyle(
                    new EffectList()),
                new EffectStyle(
                    new EffectList())),
            new BackgroundFillStyleList(
                new NoFill(),
                new SolidFill(),
                new D.GradientFill(),
                new D.BlipFill(),
                new D.PatternFill(),
                new GroupFill()))
        { Name = "Office2" }),
    new ObjectDefaults(),
    new ExtraColorSchemeList());

Código de exemplo

A seguir está um exemplo de código completo em C# e Visual Basic.

using (PresentationDocument presentationDocument = PresentationDocument.Open(pptxPath, true) ?? throw new Exception("Presentation Document does not exist"))
{
    // Get the first slide in the presentation or use the InsertNewSlide.InsertNewSlideIntoPresentation helper method to insert a new slide.
    SlidePart slidePart = presentationDocument.PresentationPart?.SlideParts.FirstOrDefault() ?? InsertNewSlideNS.InsertNewSlide(presentationDocument, 1, "my new slide");

    // Add a new NoteSlidePart if one does not already exist
    NotesSlidePart notesSlidePart = slidePart.NotesSlidePart ?? slidePart.AddNewPart<NotesSlidePart>();

    // Add a NoteSlide to the NoteSlidePart if one does not already exist.
    notesSlidePart.NotesSlide ??= new P.NotesSlide(
        new P.CommonSlideData(
            new P.ShapeTree(
                new P.NonVisualGroupShapeProperties(
                    new P.NonVisualDrawingProperties() { Id = 1, Name = "" },
                    new P.NonVisualGroupShapeDrawingProperties(),
                    new P.ApplicationNonVisualDrawingProperties()),
                new P.GroupShapeProperties(
                    new D.Transform2D(
                        new D.Offset() { X = 0, Y = 0 },
                        new D.Extents() { Cx = 0, Cy = 0 },
                        new D.ChildOffset() { X = 0, Y = 0 },
                        new D.ChildExtents() { Cx = 0, Cy = 0 })),
                new P.Shape(
                    new P.NonVisualShapeProperties(
                        new P.NonVisualDrawingProperties() { Id = 3, Name = "test Placeholder 3" },
                        new P.NonVisualShapeDrawingProperties(),
                        new P.ApplicationNonVisualDrawingProperties(
                            new P.PlaceholderShape() { Type = PlaceholderValues.Body, Index = 1 })),
                    new P.ShapeProperties(),
                    new P.TextBody(
                        new D.BodyProperties(),
                        new D.Paragraph(
                            new D.Run(
                                new D.Text("This is a test note!"))))))));

    notesSlidePart.AddPart(slidePart);

    // Add the required NotesMasterPart if it is missing
    NotesMasterPart notesMasterPart = notesSlidePart.NotesMasterPart ?? notesSlidePart.AddNewPart<NotesMasterPart>();

    // Add a NotesMaster to the NotesMasterPart if not present
    notesMasterPart.NotesMaster ??= new NotesMaster(
    new P.CommonSlideData(
        new P.ShapeTree(
            new P.NonVisualGroupShapeProperties(
                new P.NonVisualDrawingProperties() { Id = 1, Name = "New Placeholder" },
                new P.NonVisualGroupShapeDrawingProperties(),
                new P.ApplicationNonVisualDrawingProperties()),
            new P.GroupShapeProperties())),
    new P.ColorMap()
    {
        Background1 = D.ColorSchemeIndexValues.Light1,
        Background2 = D.ColorSchemeIndexValues.Light2,
        Text1 = D.ColorSchemeIndexValues.Dark1,
        Text2 = D.ColorSchemeIndexValues.Dark2,
        Accent1 = D.ColorSchemeIndexValues.Accent1,
        Accent2 = D.ColorSchemeIndexValues.Accent2,
        Accent3 = D.ColorSchemeIndexValues.Accent3,
        Accent4 = D.ColorSchemeIndexValues.Accent4,
        Accent5 = D.ColorSchemeIndexValues.Accent5,
        Accent6 = D.ColorSchemeIndexValues.Accent6,
        Hyperlink = D.ColorSchemeIndexValues.Hyperlink,
        FollowedHyperlink = D.ColorSchemeIndexValues.FollowedHyperlink,
    });

    // Add a new ThemePart for the NotesMasterPart
    ThemePart themePart = notesMasterPart.ThemePart ?? notesMasterPart.AddNewPart<ThemePart>();

    // Add the Theme if it is missing
    themePart.Theme ??= new Theme(
        new ThemeElements(
            new ColorScheme(
                new Dark1Color(
                    new SystemColor() { Val = SystemColorValues.WindowText }),
                new Light1Color(
                    new SystemColor() { Val = SystemColorValues.Window }),
                new Dark2Color(
                    new RgbColorModelHex() { Val = "f1d7be" }),
                new Light2Color(
                    new RgbColorModelHex() { Val = "171717" }),
                new Accent1Color(
                    new RgbColorModelHex() { Val = "ea9f7d" }),
                new Accent2Color(
                    new RgbColorModelHex() { Val = "168ecd" }),
                new Accent3Color(
                    new RgbColorModelHex() { Val = "e694db" }),
                new Accent4Color(
                    new RgbColorModelHex() { Val = "f0612a" }),
                new Accent5Color(
                    new RgbColorModelHex() { Val = "5fd46c" }),
                new Accent6Color(
                    new RgbColorModelHex() { Val = "b158d1" }),
                new D.Hyperlink(
                    new RgbColorModelHex() { Val = "699f82" }),
                new FollowedHyperlinkColor(
                    new RgbColorModelHex() { Val = "699f82" }))
            { Name = "Office2" },
            new D.FontScheme(
                new MajorFont(
                    new LatinFont(),
                    new EastAsianFont(),
                    new ComplexScriptFont()),
                new MinorFont(
                    new LatinFont(),
                    new EastAsianFont(),
                    new ComplexScriptFont()))
            { Name = "Office2" },
            new FormatScheme(
                new FillStyleList(
                    new NoFill(),
                    new SolidFill(),
                    new D.GradientFill(),
                    new D.BlipFill(),
                    new D.PatternFill(),
                    new GroupFill()),
                new LineStyleList(
                    new D.Outline(),
                    new D.Outline(),
                    new D.Outline()),
                new EffectStyleList(
                    new EffectStyle(
                        new EffectList()),
                    new EffectStyle(
                        new EffectList()),
                    new EffectStyle(
                        new EffectList())),
                new BackgroundFillStyleList(
                    new NoFill(),
                    new SolidFill(),
                    new D.GradientFill(),
                    new D.BlipFill(),
                    new D.PatternFill(),
                    new GroupFill()))
            { Name = "Office2" }),
        new ObjectDefaults(),
        new ExtraColorSchemeList());
}

Confira também

Sobre o Open XML SDK para Office

Como criar uma apresentação fornecendo um nome de arquivo

Como inserir um novo slide em uma apresentação

Como excluir um slide de uma apresentação

Como aplicar um tema a uma apresentação

  • Last updated on