Agregar un comentario a una diapositiva en una presentación

En este tema se muestra cómo usar las clases del SDK de Open XML para Office para agregar un comentario a la primera diapositiva de una presentación mediante programación.

Estructura básica de un documento de presentación

La estructura básica de un documento PresentationML consta de varias partes, entre las que se encuentra la parte principal que contiene la definición de la presentación. El siguiente texto de la especificación ISO/IEC 29500 presenta la forma general de un paquete de PresentationML.

La parte principal de un paquete PresentationML comienza con un elemento raíz de presentación. Dicho elemento contiene una presentación que, a su vez, hace referencia a una lista de diapositivas, a otra de patrones de diapositivas, a otra de patrones de notas y a otra de patrones de documentos. La lista de diapositivas hace referencia a todas las diapositivas de la presentación, la de patrones de diapositivas a todos los patrones de diapositivas que se han usado en la presentación, el patrón de notas contiene información acerca del formato de las páginas de notas y el patrón de documentos describe la apariencia de los documentos.

Un documento es un conjunto impreso de diapositivas que se pueden proporcionar a un público.

Al igual que el texto y los gráficos, cada diapositiva puede incluir comentarios y notas, tener un diseño y formar parte de una o varias presentaciones personalizadas. Un comentario es una anotación dirigida a la persona que se encarga del mantenimiento de las diapositivas de la presentación. Una nota es un aviso o texto dirigido al moderador o al público.

Otras características que un documento PresentationML puede incluir son las siguientes: animación, audio, vídeo y transiciones entre diapositivas .

Los documentos PresentationML no se almacenan como un gran cuerpo en una sola parte. En su lugar, los elementos que implementan ciertas agrupaciones de funcionalidades se almacenan en partes independientes. Por ejemplo, todos los comentarios de un documento se almacenan en una parte de comentarios mientras que cada diapositiva cuenta con su propia parte.

© ISO/IEC29500: 2008.

El siguiente ejemplo de código XML representa una presentación que contiene dos diapositivas denotadas por los identificadores 267 y 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>

Con el SDK de Open XML, puede crear contenido y estructura de documentos mediante clases fuertemente tipadas que corresponden a elementos PresentationML. Puede encontrar estas clases en el espacio de nombres DocumentFormat.OpenXml.Presentation . En la tabla siguiente se enumeran los nombres de las clases que corresponden a los elementos sld, sldLayout, sldMaster y notesMaster.

Elemento de PresentationML	Open XML SDK (clase)	Descripción
Sld	Diapositiva	Diapositiva de presentación. Es el elemento raíz de SlidePart.
sldLayout	SlideLayout	Diseño de la diapositiva. Es el elemento raíz de SlideLayoutPart.
sldMaster	SlideMaster	Patrón de diapositivas. Es el elemento raíz de SlideMasterPart.
notesMaster	NotesMaster	Patrón de notas (o handoutMaster). Es el elemento raíz de NotesMasterPart.

Estructura del elemento Comment

Un comentario es una nota de texto adjunta a una diapositiva y su objetivo principal consiste en permitir a los lectores de una presentación proporcionar comentarios al autor de esta. Cada comentario contiene una cadena de texto sin formato e información acerca del autor y está adjunto en una ubicación concreta de la diapositiva. Los comentarios pueden verse al editar la presentación, pero no al mostrarla. La aplicación que muestra la presentación decide cuándo mostrar los comentarios y determina su apariencia visual.

El siguiente elemento XML especifica un solo comentario adjunto a una diapositiva. Contiene el texto del comentario (text), su posición en la diapositiva (pos) y los atributos que hacen referencia al autor (authorId), la fecha y hora (dt) y el índice de comentarios (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>

En la siguiente tabla se incluyen las definiciones de los miembros y atributos del elemento cm (comentario).

Miembro o atributo	Definición
authorId	Hace referencia al identificador de un autor de la lista de autores de comentarios del documento.
Despegue	Fecha y hora en que se modificó por última vez este comentario.
Idx	Un identificador de este comentario que es exclusivo dentro de una lista de comentarios realizados por este autor en este documento. El primer comentario de un autor en un documento tiene el índice 1.
Pos	La información de posicionamiento de la selección de ubicación de un comentario en la superficie de una diapositiva.
text	Texto del comentario.
extLst	Especifica la lista de extensiones con capacidad de modificación en la que se definen todas las extensiones futuras del tipo de elemento ext. La lista de extensiones, junto con las extensiones futuras correspondientes, se usa para ampliar las capacidades de almacenamiento del marco PresentationML. Esto permite que se almacenen en el marco diversos tipos de datos nuevos de forma nativa.

El siguiente ejemplo de código de esquema XML define los miembros del elemento cm además de los atributos opcionales y obligatorios.

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

En el ejemplo de código siguiente se muestra cómo agregar comentarios a un documento de presentación. Para ejecutar el programa, puede pasar los argumentos:

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

Nota:

[!NOTA] Para obtener el nombre y las iniciales exactas del autor, abra el archivo de presentación, haga clic en el elemento de menú Archivo y, a continuación, haga clic en Opciones. Se abre la ventana PowerPointOptions y se muestra el contenido de la pestaña General . El nombre y las iniciales del autor deben coincidir con el Nombre de usuario y las Iniciales de esta ficha.

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

Vea también

• Referencia de la biblioteca de clases del SDK de Open XML