Adicionar um comentário a um slide de uma apresentação

Este tópico mostra como usar as classes no SDK Do Open XML para Office para adicionar um comentário ao primeiro slide em uma apresentação de forma programática.

Estrutura básica do documento de apresentação

A estrutura básica do documento de um documento PresentationML consiste em várias partes, entre elas a main parte que contém a definição de apresentação. O texto a seguir da especificação ISO/IEC 29500 apresenta a forma geral de um pacote PresentationML .

A main parte de um pacote PresentationML começa com um elemento raiz de apresentação. Esse elemento contém uma apresentação que, por sua vez, se refere a uma lista de slides, uma lista de master de slides, uma lista de master de anotações e uma lista de master de apostila. A lista de slides refere-se a todos os slides na apresentação; A lista de master de slides refere-se a todos os mestres de slides usados na apresentação; as anotações master contém informações sobre a formatação de páginas de anotações; e a apostila master descreve como uma apostila parece.

Uma apostila é um conjunto impresso de slides que pode ser fornecido a uma audiência.

Além de texto e gráficos, cada slide pode conter comentários e anotações, pode ter um layout e pode fazer parte de uma ou mais apresentações personalizadas. Um comentário é uma anotação destinada à pessoa que mantém o deck de slides de apresentação. Uma nota é um lembrete ou um pedaço de texto destinado ao apresentador ou ao público-alvo.

Outros recursos que um documento PresentationML pode incluir o seguinte: animação, áudio, vídeo e transições entre slides.

Um documento PresentationML não é armazenado como um corpo grande em uma única parte. Em vez disso, os elementos que implementam determinados agrupamentos de funcionalidade são armazenados em partes separadas. Por exemplo, todos os comentários em um documento são armazenados em uma parte de comentário, enquanto cada slide tem sua própria parte.

© ISO/IEC29500: 2008.

O exemplo de código XML a seguir representa uma apresentação que contém dois slides denotados pelas IDs 267 e 256.

    <p:presentation xmlns:p="…" … > 
       <p:sldMasterIdLst>
          <p:sldMasterId
             xmlns:rel="https://…/relationships" rel:id="rId1"/>
       </p:sldMasterIdLst>
       <p:notesMasterIdLst>
          <p:notesMasterId
             xmlns:rel="https://…/relationships" rel:id="rId4"/>
       </p:notesMasterIdLst>
       <p:handoutMasterIdLst>
          <p:handoutMasterId
             xmlns:rel="https://…/relationships" rel:id="rId5"/>
       </p:handoutMasterIdLst>
       <p:sldIdLst>
          <p:sldId id="267"
             xmlns:rel="https://…/relationships" rel:id="rId2"/>
          <p:sldId id="256"
             xmlns:rel="https://…/relationships" rel:id="rId3"/>
       </p:sldIdLst>
           <p:sldSz cx="9144000" cy="6858000"/>
       <p:notesSz cx="6858000" cy="9144000"/>
    </p:presentation>

Usando o SDK do Open XML, você pode criar estrutura de documentos e conteúdo usando classes fortemente tipdas que correspondem a elementos PresentationML. Você pode encontrar essas classes no namespace DocumentFormat.OpenXml.Presentation . A tabela a seguir lista os nomes de classe das classes que correspondem aos elementos sld, sldLayout, sldMaster e notesMaster .

Elemento PresentationML	Classe SDK Open XML	Descrição
Sld	Slide	Slide de Apresentação. É o elemento raiz do SlidePart.
sldLayout	SlideLayout	Layout do Slide. É o elemento raiz do SlideLayoutPart.
sldMaster	SlideMaster	Mestre de Slides. É o elemento raiz do SlideMasterPart.
notesMaster	NotesMaster	Mestre de Anotações (ou handoutMaster). É o elemento raiz do NotesMasterPart.

A estrutura do elemento Comment

Um comentário é uma nota de texto anexada a um slide, com o objetivo principal de permitir que os leitores de uma apresentação forneçam comentários ao autor da apresentação. Cada comentário contém uma cadeia de texto não formatada e informações sobre seu autor e é anexado a um local específico em um slide. Os comentários podem ser visíveis durante a edição da apresentação, mas não aparecem quando uma apresentação de slides é fornecida. O aplicativo de exibição decide quando exibir comentários e determina sua aparência visual.

O elemento XML a seguir especifica um único comentário anexado a um slide. Ele contém o texto do comentário (texto), sua posição no slide (pos) e atributos referentes a seu autor (authorId), data e hora (dt) e índice de comentários (idx).

    <p:cm authorId="0" dt="2006-08-28T17:26:44.129" idx="1">
        <p:pos x="10" y="10"/>
        <p:text>Add diagram to clarify.</p:text>
    </p:cm>

A tabela a seguir contém as definições dos membros e atributos do elemento cm (comentário).

Membro/Atributo	Definição
authorId	Refere-se à ID de um autor na lista de autores de comentários do documento.
Dt	A data e a hora em que este comentário foi modificado pela última vez.
Idx	Um identificador para este comentário que é exclusivo dentro de uma lista de todos os comentários deste autor neste documento. O primeiro comentário de um autor em um documento tem índice 1.
Pos	As informações de posicionamento para o posicionamento de um comentário em uma superfície de slide.
texto	Texto de comentário.
extLst	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.

O exemplo de código de esquema XML a seguir define os membros do elemento cm , além dos atributos necessários e opcionais.

    <complexType name="CT_Comment">
       <sequence>
           <element name="pos" type="a:CT_Point2D" minOccurs="1" maxOccurs="1"/>
           <element name="text" type="xsd:string" minOccurs="1" maxOccurs="1"/>
           <element name="extLst" type="CT_ExtensionListModify" minOccurs="0" maxOccurs="1"/>
       </sequence>
       <attribute name="authorId" type="xsd:unsignedInt" use="required"/>
       <attribute name="dt" type="xsd:dateTime" use="optional"/>
       <attribute name="idx" type="ST_Index" use="required"/>
    </complexType>

Código de exemplo

O exemplo de código a seguir mostra como adicionar comentários a um documento de apresentação. Para executar o programa, você pode passar os argumentos:

dotnet run -- [filePath] [initials] [name] [test ...]

Observação

Para obter o nome e as iniciais exatos do autor, abra o arquivo de apresentação e clique no item menu Arquivo e clique em Opções. A janela PowerPointOptions é aberta e o conteúdo da guia Geral é exibido. O nome e as iniciais do autor devem corresponder ao nome de usuário e às iniciais nesta guia.

C#

using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Presentation;
using System;
using System.Linq;

AddCommentToPresentation(args[0], args[1], args[2], string.Join(' ', args[3..]));

static void AddCommentToPresentation(string file, string initials, string name, string text)
{
    using (PresentationDocument doc = PresentationDocument.Open(file, true))
    {

        // Declare a CommentAuthorsPart object.
        CommentAuthorsPart authorsPart;

        // If the presentation does not contain a comment authors part, add a new one.
        PresentationPart presentationPart = doc.PresentationPart ?? doc.AddPresentationPart();

        // Verify that there is an existing comment authors part and add a new one if not.
        authorsPart = presentationPart.CommentAuthorsPart ?? presentationPart.AddNewPart<CommentAuthorsPart>();

        // Verify that there is a comment author list in the comment authors part and add one if not.
        CommentAuthorList authorList = authorsPart.CommentAuthorList ?? new CommentAuthorList();
        authorsPart.CommentAuthorList = authorList;

        // Declare a new author ID as either the max existing ID + 1 or 1 if there are no existing IDs.
        uint authorId = authorList.Elements<CommentAuthor>().Select(a => a.Id?.Value).Max() ?? 0;
        authorId++;
        // If there is an existing author with matching name and initials, use that author otherwise create a new CommentAuthor.
        var foo = authorList.Elements<CommentAuthor>().Where(a => a.Name == name && a.Initials == initials).FirstOrDefault();
        CommentAuthor author = foo ??
            authorList.AppendChild
                (new CommentAuthor()
                {
                    Id = authorId,
                    Name = name,
                    Initials = initials,
                    ColorIndex = 0
                });
        // get the author id
        authorId = author.Id ?? authorId;

        // Get the first slide, using the GetFirstSlide method.
        SlidePart slidePart1 = GetFirstSlide(doc);

        // Declare a comments part.
        SlideCommentsPart commentsPart;

        // Verify that there is a comments part in the first slide part.
        if (slidePart1.GetPartsOfType<SlideCommentsPart>().Count() == 0)
        {
            // If not, add a new comments part.
            commentsPart = slidePart1.AddNewPart<SlideCommentsPart>();
        }
        else
        {
            // Else, use the first comments part in the slide part.
            commentsPart = slidePart1.GetPartsOfType<SlideCommentsPart>().First();
        }

        // If the comment list does not exist.
        if (commentsPart.CommentList is null)
        {
            // Add a new comments list.
            commentsPart.CommentList = new CommentList();
        }

        // Get the new comment ID.
        uint commentIdx = author.LastIndex is null ? 1 : author.LastIndex + 1;
        author.LastIndex = commentIdx;

        // Add a new comment.
        Comment comment = commentsPart.CommentList.AppendChild<Comment>(
            new Comment()
            {
                AuthorId = authorId,
                Index = commentIdx,
                DateTime = DateTime.Now
            });

        // Add the position child node to the comment element.
        comment.Append(
            new Position() { X = 100, Y = 200 },
            new Text() { Text = text });

        // Save the comment authors part.
        authorList.Save();

        // Save the comments part.
        commentsPart.CommentList.Save();
    }
}

// Get the slide part of the first slide in the presentation document.
static SlidePart GetFirstSlide(PresentationDocument? presentationDocument)
{
    // Get relationship ID of the first slide
    PresentationPart? part = presentationDocument?.PresentationPart;
    SlideId? slideId = part?.Presentation?.SlideIdList?.GetFirstChild<SlideId>();
    string? relId = slideId?.RelationshipId;
    if (relId is null)
    {
        throw new ArgumentNullException("The first slide does not contain a relationship ID.");
    }
    // Get the slide part by the relationship ID.
    SlidePart? slidePart = part?.GetPartById(relId) as SlidePart;

    if (slidePart is null)
    {
        throw new ArgumentNullException("The slide part is null.");
    }

    return slidePart;
}

Visual Basic

Imports DocumentFormat.OpenXml.Packaging
Imports DocumentFormat.OpenXml.Presentation

Module Program
    Sub Main(args As String())
        AddCommentToPresentation(args(0), args(1), args(2), String.Join(" ", args.Skip(3)))
    End Sub

    Public Sub AddCommentToPresentation(ByVal file As String,
                ByVal initials As String,
                ByVal name As String,
                ByVal text As String)

        Dim doc As PresentationDocument =
          PresentationDocument.Open(file, True)

        Using (doc)

            ' Declare a CommentAuthorsPart object.
            Dim authorsPart As CommentAuthorsPart

            ' Verify that there is an existing comment authors part.
            If (doc.PresentationPart.CommentAuthorsPart Is Nothing) Then

                ' If not, add a new one.
                authorsPart = doc.PresentationPart.AddNewPart(Of CommentAuthorsPart)()
            Else
                authorsPart = doc.PresentationPart.CommentAuthorsPart
            End If

            ' Verify that there is a comment author list in the comment authors part.
            If (authorsPart.CommentAuthorList Is Nothing) Then

                ' If not, add a new one.
                authorsPart.CommentAuthorList = New CommentAuthorList()
            End If

            ' Declare a new author ID.
            Dim authorId As UInteger = 0
            Dim author As CommentAuthor = Nothing

            ' If there are existing child elements in the comment authors list.
            If authorsPart.CommentAuthorList.HasChildren = True Then

                ' Verify that the author passed in is on the list.
                Dim authors = authorsPart.CommentAuthorList.Elements(Of CommentAuthor)().Where _
              (Function(a) a.Name = name AndAlso a.Initials = initials)

                ' If so...
                If (authors.Any()) Then

                    ' Assign the new comment author the existing ID.
                    author = authors.First()
                    authorId = author.Id
                End If

                ' If not...
                If (author Is Nothing) Then

                    ' Assign the author passed in a new ID.
                    authorId =
                authorsPart.CommentAuthorList.Elements(Of CommentAuthor)().Select(Function(a) a.Id.Value).Max()
                End If

            End If

            ' If there are no existing child elements in the comment authors list.
            If (author Is Nothing) Then

                authorId = authorId + 1

                ' Add a new child element (comment author) to the comment author list.
                author = (authorsPart.CommentAuthorList.AppendChild(Of CommentAuthor) _
              (New CommentAuthor() With {.Id = authorId,
               .Name = name,
               .Initials = initials,
               .ColorIndex = 0}))
            End If

            ' Get the first slide, using the GetFirstSlide() method.
            Dim slidePart1 As SlidePart
            slidePart1 = GetFirstSlide(doc)

            ' Declare a comments part.
            Dim commentsPart As SlideCommentsPart

            ' Verify that there is a comments part in the first slide part.
            If slidePart1.GetPartsOfType(Of SlideCommentsPart)().Count() = 0 Then

                ' If not, add a new comments part.
                commentsPart = slidePart1.AddNewPart(Of SlideCommentsPart)()
            Else

                ' Else, use the first comments part in the slide part.
                commentsPart =
              slidePart1.GetPartsOfType(Of SlideCommentsPart)().First()
            End If

            ' If the comment list does not exist.
            If (commentsPart.CommentList Is Nothing) Then

                ' Add a new comments list.
                commentsPart.CommentList = New CommentList()
            End If

            ' Get the new comment ID.
            Dim commentIdx As UInteger
            If author.LastIndex Is Nothing Then
                commentIdx = 1
            Else
                commentIdx = CType(author.LastIndex, UInteger) + 1
            End If

            author.LastIndex = commentIdx

            ' Add a new comment.
            Dim comment As Comment =
(commentsPart.CommentList.AppendChild(Of Comment)(New Comment() _
             With {.AuthorId = authorId, .Index = commentIdx, .DateTime = DateTime.Now}))

            ' Add the position child node to the comment element.
            comment.Append(New Position() With
               {.X = 100, .Y = 200}, New Text() With {.Text = text})


            ' Save comment authors part.
            authorsPart.CommentAuthorList.Save()

            ' Save comments part.
            commentsPart.CommentList.Save()

        End Using

    End Sub

    ' Get the slide part of the first slide in the presentation document.
    Public Function GetFirstSlide(ByVal presentationDocument As PresentationDocument) As SlidePart
        ' Get relationship ID of the first slide
        Dim part As PresentationPart = presentationDocument.PresentationPart
        Dim slideId As SlideId = part.Presentation.SlideIdList.GetFirstChild(Of SlideId)()
        Dim relId As String = slideId.RelationshipId

        ' Get the slide part by the relationship ID.
        Dim slidePart As SlidePart = DirectCast(part.GetPartById(relId), SlidePart)

        Return slidePart
    End Function
End Module

Confira também

• Abrir referência de biblioteca de classes do SDK XML