Ajouter un commentaire à une diapositive dans une présentation

Cette rubrique montre comment utiliser les classes du Kit de développement logiciel (SDK) Open XML pour Office pour ajouter un commentaire à la première diapositive d’une présentation par programme.

Structure de document de présentation de base

La structure de document de base d’un document PresentationML est constituée d’un certain nombre de composants, parmi lesquels le composant principal qui contient la définition de la présentation. Le texte suivant de la spécification ISO/IEC 29500 présente la forme globale d’un package PresentationML .

La partie main d’un package PresentationML commence par un élément racine de présentation. Cet élément contient une présentation qui, à son tour, fait référence à une liste de diapositives, à une liste de diapositives master, à une liste de notes master et à un document master liste. La liste des diapositives référence toutes les diapositives de la présentation ; la liste de masques de diapositive référence tous les masques de diapositive utilisés dans la présentation ; le masque de pages de note contient des informations sur la mise en forme des pages de notes et le masque de document décrit comment un document se présente.

Un document à distribuer est un ensemble imprimé de diapositives qui peut être distribué aux personnes de l’audience.

En plus de textes et de graphiques, chaque diapositive peut contenir des commentaires et des notes, peut avoir une disposition et peut faire partie d’une ou plusieurs présentations personnalisées. Un commentaire est une annotation destinée à la personne qui gère le jeu de diapositives de la présentation. Une note est un rappel ou un élément de texte destiné au présentateur ou à l’audience.

Les autres fonctionnalités qu’un document PresentationML peut inclure les suivantes : animation, audio, vidéo et transitions entre les diapositives.

Un document PresentationML n’est pas stocké sous la forme d’un corps de grande taille dans un même composant. Au lieu de cela, les éléments qui implémentent certains groupes de fonctionnalités sont stockés dans des composants distincts. Par exemple, tous les commentaires d’un document sont stockés dans un même composant Commentaires, alors que chaque diapositive a son propre composant.

© ISO/IEC29500: 2008.

L’exemple de code XML suivant représente une présentation qui contient deux diapositives ayant les numéros d’identification 267 et 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>

À l’aide du Kit de développement logiciel (SDK) Open XML, vous pouvez créer une structure de document et du contenu à l’aide de classes fortement typées qui correspondent aux éléments PresentationML. Vous trouverez ces classes dans l’espace de noms DocumentFormat.OpenXml.Presentation . Le tableau suivant répertorie les noms des classes qui correspondent aux éléments sld, sldLayout, sldMaster et notesMaster.

Élément PresentationML	Classe du Kit de développement logiciel (SDK) Open XML	Description
Sld	Slide	Diapositive de présentation. Il s’agit de l’élément racine de SlidePart.
sldLayout	SlideLayout	Mise en page des diapositives. Il s’agit de l’élément racine de SlideLayoutPart.
sldMaster	SlideMaster	Masque des diapositives. Il s’agit de l’élément racine de SlideMasterPart.
Notesmaster	NotesMaster	Masque des pages de notes (ou handoutMaster). Il s’agit de l’élément racine de NotesMasterPart.

La structure de l’élément de commentaire

Un commentaire est une note de texte rattachée à une diapositive, ayant comme objectif principal de permettre aux lecteurs d’une présentation de fournir des commentaires à l’auteur de la présentation. Chaque commentaire contient une chaîne de texte sans mise en forme et des informations sur son auteur, et elle est rattachée à un emplacement particulier sur une diapositive. Les commentaires peuvent être visibles lors de la modification de la présentation, mais ils n’apparaissent pas lors de l’exécution d’un diaporama. L’application d’affichage décide du moment où afficher les commentaires et détermine leur apparence visuelle.

L’élément XML suivant spécifie un seul commentaire rattaché à une diapositive. Il contient le texte du commentaire (text), sa position sur la diapositive (pos), ainsi que des attributs référençant son auteur (authorId), la date et l’heure (dt) et l’index du commentaire (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>

Le tableau suivant contient les définitions des membres et des attributs de l’élément cm (commentaire).

Membre/Attribut	Définition
authorId	Référence l’ID d’un auteur dans la liste des auteurs de commentaires pour le document.
Dt	La date et l’heure à laquelle ce commentaire a été modifié pour la dernière fois.
Idx	Un identificateur pour ce commentaire, unique dans une liste de tous les commentaires par cet auteur dans ce document. Le premier commentaire d’un auteur a l’index 1.
Pos	Les informations de positionnement pour le placement d’un commentaire sur la surface d’une diapositive.
text	Texte de commentaire.
extLst	Spécifie la liste des extensions avec possibilité de modification dans laquelle toutes les extensions futures de type d’élément ext sont définies. La liste des extensions et les extensions futures correspondantes sont utilisées pour étendre les capacités de stockage de l’infrastructure PresentationML. Ceci permet à différents nouveaux types de données d’être stockés en mode natif dans l’infrastructure.

L’exemple de code de schéma XML suivant définit les membres de l’élément cm, ainsi que les attributs requis ou facultatifs.

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

Exemple de code

L’exemple de code suivant montre comment ajouter des commentaires à un document de présentation. Pour exécuter le programme, vous pouvez passer les arguments :

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

Remarque

Pour obtenir le nom et les initiales de l’auteur, ouvrez le fichier de présentation et cliquez sur l’option de menu Fichier, puis cliquez sur Options. La fenêtre PowerPointOptions s’ouvre et le contenu de l’onglet Général s’affiche. Le nom et les initiales de l’auteur doivent correspondre au Nom d’utilisateur et aux Initiales affichés dans cet onglet.

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

Voir aussi

• Informations de référence sur la bibliothèque de classes du Kit de développement logiciel (SDK) Open XML