Como trabalhar com slides de anotações

Artigo
11/16/2023

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

Slides de Anotações em PresentationML

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

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

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

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

No exemplo acima, um elemento de notas 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, todos os elementos especificam propriedades adicionais não comuns para este slide de anotações.

O <elemento notes> é o elemento raiz da parte Slide de Notas do 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 elemento de <anotações> usado ao trabalhar com slides de anotações e as classes de SDK Open XML que correspondem a elas.

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

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

Atributos	Description
showMasterPhAnim (mostrar animações de espaço reservado mestre)	Especifica se deve ou não exibir animações em espaços reservados do slide master. Os valores possíveis para esse atributo são definidos pelo tipo de dados booliano W3C XML Schema.
showMasterSp (Mostrar Formas Mestras)	Especifica se as formas no slide master devem ser mostradas em slides ou não. Os valores possíveis para esse atributo são definidos pelo tipo de dados booliano W3C XML Schema.

Classe Open XML SDK NotesSlide

A classe OxML SDK NotesSlide representa o <elemento notes> definido no esquema Formato de Arquivo XML Aberto para documentos PresentationML. Use a classe NotesSlide para manipular elementos de anotações> individuais <em um documento PresentationML.

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

Classe ColorMapOverride

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

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

Classe CommonSlideData

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

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

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

Classe ExtensionListWithModification

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

Esse elemento especifica a lista de extensão com capacidade de modificação na qual todas as extensões futuras do tipo <de elemento são> definidas. A lista de extensão junto 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 dentro da estrutura.

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

Trabalhando com a classe NotesSlide

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

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

Abrir o exemplo de código do SDK XML

O método a seguir adiciona uma nova parte de slide de notas a uma apresentação existente e cria uma instância de uma classe Open XML SDKNotesSlide na nova parte do slide de notas. O construtor da classe NotesSlide cria instâncias da classe CommonSlideData e da classe ColorMap . O construtor da classe CommonSlideData cria uma instância da classe ShapeTree , cujo construtor, por sua vez, cria instâncias de classe adicionais: uma instância da classe NonVisualGroupShapeProperties , uma instância da classe GroupShapeProperties e uma instância da classe Shape .

O namespace representado pela letra P no código é o namespace DocumentFormat.OpenXml.Presentation .

C#
Visual Basic

using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Drawing;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Presentation;
using P = DocumentFormat.OpenXml.Presentation;

static NotesSlidePart CreateNotesSlidePart(SlidePart slidePart1)
{
    NotesSlidePart notesSlidePart1 = slidePart1.AddNewPart<NotesSlidePart>("rId6");
    NotesSlide notesSlide = new NotesSlide(
    new CommonSlideData(new ShapeTree(
      new P.NonVisualGroupShapeProperties(
      new P.NonVisualDrawingProperties() { Id = (UInt32Value)1U, Name = "" },
      new P.NonVisualGroupShapeDrawingProperties(),
      new ApplicationNonVisualDrawingProperties()),
      new GroupShapeProperties(new TransformGroup()),
      new P.Shape(
      new P.NonVisualShapeProperties(
        new P.NonVisualDrawingProperties() { Id = (UInt32Value)2U, Name = "" },
        new P.NonVisualShapeDrawingProperties(new ShapeLocks() { NoGrouping = true }),
        new ApplicationNonVisualDrawingProperties(new PlaceholderShape())),
      new P.ShapeProperties(),
      new P.TextBody(
        new BodyProperties(),
        new ListStyle(),
        new Paragraph(new EndParagraphRunProperties()))))),
    new ColorMapOverride(new MasterColorMapping()));
    notesSlidePart1.NotesSlide = notesSlide;
    return notesSlidePart1;
}

Imports DocumentFormat.OpenXml.Drawing
Imports DocumentFormat.OpenXml.Packaging
Imports DocumentFormat.OpenXml.Presentation
Imports P = DocumentFormat.OpenXml.Presentation

Module MyModule

    Sub Main(args As String())
    End Sub

    Function CreateNotesSlidePart(ByVal slidePart1 As SlidePart) As NotesSlidePart
        Dim notesSlidePart1 As NotesSlidePart = slidePart1.AddNewPart(Of NotesSlidePart)("rId6")
        Dim notesSlide As New NotesSlide(New CommonSlideData(New ShapeTree(New P.NonVisualGroupShapeProperties(New P.NonVisualDrawingProperties() With {
             .Id = 1UI,
             .Name = ""
            }, New P.NonVisualGroupShapeDrawingProperties(), New ApplicationNonVisualDrawingProperties()), New _
                GroupShapeProperties(New TransformGroup()), New P.Shape(New P.NonVisualShapeProperties(New P.NonVisualDrawingProperties() With {
             .Id = 2UI,
             .Name = ""
            }, New P.NonVisualShapeDrawingProperties(New ShapeLocks() With {
             .NoGrouping = True
            }), New ApplicationNonVisualDrawingProperties(New PlaceholderShape())), New P.ShapeProperties(), New _
                P.TextBody(New BodyProperties(), New ListStyle(), New Paragraph(New EndParagraphRunProperties()))))),
            New ColorMapOverride(New MasterColorMapping()))
        notesSlidePart1.NotesSlide = notesSlide
        Return notesSlidePart1
    End Function
End Module

PresentationML gerado

Quando o código SDK Open XML é executado, o XML a seguir é gravado no documento PresentationML referenciado no código.

    <?xml version="1.0" encoding="utf-8"?>
    <p:notes xmlns:p="https://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="https://schemas.openxmlformats.org/drawingml/2006/main" />
          </p:grpSpPr>
          <p:sp>
            <p:nvSpPr>
              <p:cNvPr id="2"
                       name="" />
              <p:cNvSpPr>
                <a:spLocks noGrp="1"
                           xmlns:a="https://schemas.openxmlformats.org/drawingml/2006/main" />
              </p:cNvSpPr>
              <p:nvPr>
                <p:ph />
              </p:nvPr>
            </p:nvSpPr>
            <p:spPr />
            <p:txBody>
              <a:bodyPr xmlns:a="https://schemas.openxmlformats.org/drawingml/2006/main" />
              <a:lstStyle xmlns:a="https://schemas.openxmlformats.org/drawingml/2006/main" />
              <a:p xmlns:a="https://schemas.openxmlformats.org/drawingml/2006/main">
                <a:endParaRPr />
              </a:p>
            </p:txBody>
          </p:sp>
        </p:spTree>
      </p:cSld>
      <p:clrMapOvr>
        <a:masterClrMapping xmlns:a="https://schemas.openxmlformats.org/drawingml/2006/main" />
      </p:clrMapOvr>
    </p:notes>