Arbeiten mit Kommentaren

Artikel
09/24/2014

Letzte Änderung: Freitag, 8. Oktober 2010

Gilt für: Excel 2010 | Office 2010 | PowerPoint 2010 | Word 2010

Inhalt dieses Artikels
Kommentare in PresentationML
Kommentarklasse im Open XML SDK 2.0
Arbeiten mit der Kommentarklasse
Codebeispiel für das Open XML SDK
Generiertes PresentationML-Dokument

In diesem Thema wird die Comment-Klasse im Open XML SDK 2.0 und ihre Verbindung mit dem PresentationML-Schema im Open XML-Dateiformat erläutert. Weitere Informationen zur Gesamtstruktur der Teile und Elemente eines PresentationML-Dokuments finden Sie unter Struktur eines PresentationML-Dokuments.

Kommentare in PresentationML

In der ISO/IEC 29500-Spezifikation wird der Kommentarabschnitt des PresentationML-Frameworks in Open XML wie folgt erläutert:

Ein Kommentar ist eine an eine Folie angefügte Textnotiz und hat den Hauptzweck, den Lesern der Präsentation die Möglichkeit zu bieten, dem Autor der Präsentation Feedback zu geben. Jeder Kommentar besteht aus einer unformatierten Textzeichenfolge sowie Informationen zum Autor und ist an einer bestimmten Stelle einer Folie angefügt. Kommentare können beim Bearbeiten der Bildschirmpräsentation sichtbar sein, sie werden jedoch beim Halten der Präsentation nicht angezeigt. Die anzeigende Anwendung bestimmt, wann Kommentare angezeigt werden sollen, und deren visuelle Darstellung.

In der ISO/IEC 29500-Spezifikation wird das Element <cm> des PresentationML-Dokuments in Open XML erläutert, das zur Darstellung von Kommentaren in einem PresentationML-Dokument wie folgt verwendet wird:

Dieses Element gibt einen einzelnen an eine Folie angefügten Kommentar an. Es enthält den Text des Kommentars, seine Position auf der Folie und die Attribute bezüglich Autor und Datum.

[Ein Beispiel:

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

Ende des Beispiels]

In der folgenden Tabelle sind die untergeordneten Elemente des Elements <cm > aufgeführt, das bei Verwendung von Kommentaren und der entsprechenden Open XML SDK 2.0-Klassen verwendet wird.

PresentationML-Element	Open XML SDK 2.0-Klasse
<extLst>	ExtensionListWithModification
<pos>	Position
<text>	Text

In der folgenden Tabelle aus der ISO/IEC 29500-Spezifikation werden die Attribute des Elements <cm> erläutert.

Attribut	Beschreibung
authorId	Dieses Attribut gibt den Autor des Kommentars an. Es verweist auf die ID eines Autors in der Kommentarautorenliste des Dokuments. Die möglichen Werte dieses Attributs werden durch den unsignedInt-Datentyp des W3C-XML-Schemas definiert.
dt	Dieses Attribut gibt das Datum und die Uhrzeit der letzten Änderung dieses Kommentars an. Die möglichen Werte dieses Attributs werden durch den datetime-Datentyp des W3C-XML-Schemas definiert.
idx	Dieses Attribut gibt eine Kennung dieses Kommentars an, die in einer Liste aller Kommentare dieses Autors in diesem Dokument eindeutig ist. Der erste Kommentar eines Autors in einem Dokument hat den Index 1. [Hinweis: Da der Index nur für den Kommentarautor eindeutig ist, kann ein Dokument mehrere Kommentare mit demselben Index enthalten, die von verschiedenen Autoren erstellt wurden. Ende des Hinweises] Die möglichen Werte dieses Attributs werden durch den einfachen Typ ST_Index angegeben (§19.7.3).

authorId

Dieses Attribut gibt den Autor des Kommentars an. Es verweist auf die ID eines Autors in der Kommentarautorenliste des Dokuments.

Die möglichen Werte dieses Attributs werden durch den unsignedInt-Datentyp des W3C-XML-Schemas definiert.

Dieses Attribut gibt das Datum und die Uhrzeit der letzten Änderung dieses Kommentars an.

Die möglichen Werte dieses Attributs werden durch den datetime-Datentyp des W3C-XML-Schemas definiert.

idx

Dieses Attribut gibt eine Kennung dieses Kommentars an, die in einer Liste aller Kommentare dieses Autors in diesem Dokument eindeutig ist. Der erste Kommentar eines Autors in einem Dokument hat den Index 1.

[Hinweis: Da der Index nur für den Kommentarautor eindeutig ist, kann ein Dokument mehrere Kommentare mit demselben Index enthalten, die von verschiedenen Autoren erstellt wurden. Ende des Hinweises]

Die möglichen Werte dieses Attributs werden durch den einfachen Typ ST_Index angegeben (§19.7.3).

Kommentarklasse im Open XML SDK 2.0

Die Comment-Klasse im OXML SDK stellt das Element <cm> dar, das im Open XML-Dateiformatschema für PresentationML-Dokumente definiert ist. Mit der Comment-Klasse können Sie einzelne Elemente vom Typ <cm> in einem PresentationML-Dokument ändern.

Klassen, die untergeordnete Elemente des Elements <cm> darstellen und daher häufig der Comment-Klasse zugeordnet werden, sind in der folgenden Liste dargestellt.

ExtensionListWithModification-Klasse

Die ExtensionListWithModification-Klasse entspricht dem Element <extLst>. In den folgenden Informationen aus der http://www.iso.org/iso/iso\_catalogue/catalogue\_tc/catalogue\_detail.htm?csnumber=51463\<extLst><extLst> erläutert:

Dieses Element gibt die Erweiterungsliste mit Modifikationsmöglichkeit an, in der alle künftigen Erweiterungen des Elementtyps <ext> definiert werden. Die Erweiterung wird gemeinsam mit den entsprechenden künftigen Erweiterungen genutzt, um die Speicherfähigkeiten des PresentationML-Frameworks zu vergrößern. Dadurch können verschiedene neue Arten von Daten systeminhärent im Framework gespeichert werden.

[Hinweis: Die Verwendung dieses Elements extLst ermöglicht es der generierenden Anwendung, zu speichern, ob diese Erweiterungseigenschaft geändert wurde. Ende des Hinweises]

Position-Klasse

Die Position-Klasse entspricht dem Element <pos>. In den folgenden Informationen aus der http://www.iso.org/iso/iso\_catalogue/catalogue\_tc/catalogue\_detail.htm?csnumber=51463\<pos><pos> erläutert:

Dieses Element gibt die Positionierungsinformationen zum Platzieren eines Kommentars auf einer Folienoberfläche an. In LNR-Versionen der generierenden Anwendung sollten sich die Positionsinformationen auf den oberen linken Punkt der Kommentarform beziehen. In RNL-Versionen der generierenden Anwendung sollten sich diese Positionsinformationen auf den oberen rechten Punkt der Kommentarform beziehen.

[Hinweis: Der Ankerpunkt auf der Folienoberfläche ist von einer Änderung des Layouts von rechts nach links oder von links nach rechts nicht betroffen. Dies bedeutet, dass der Ankerpunkt für alle Sprachversionen identisch ist. Ende des Hinweises]

[Hinweis: Da für Kommentare keine bestimmte Größe oder Formatierung vorgegeben ist, kann das Widget der Benutzeroberfläche, das zur Anzeige eines Kommentars verwendet wird, eine beliebige Größe haben. Der untere rechte Punkt der Kommentarform wird daher durch die Art und Weise bestimmt, wie die Kommentare von der anzeigenden Anwendung dargestellt werden. Ende des Hinweises]

[Ein Beispiel: <p:pos x="1426" y="660"/> Ende des Beispiels]

Text-Klasse

Die Text-Klasse entspricht dem Element <text>. In den folgenden Informationen aus der ISO/IEC 29500-Spezifikation wird das Element <text> erläutert:

Mit diesem Element wird der Inhalt eines Kommentars angegeben. Hierbei handelt es sich um den Text, den der Autor an die Folie angefügt hat.

[Ein Beispiel: <p:text>Diagramm zur Klärung hinzufügen.</p:text> Ende des Beispiels]

Die möglichen Werte dieses Elements werden durch den string-Datentyp des W3C-XML-Schemas definiert.

Arbeiten mit der Kommentarklasse

Ein Kommentar ist eine an eine Folie angefügte Textnotiz und hat den Hauptzweck, den Lesern der Präsentation die Möglichkeit zu bieten, dem Autor der Präsentation Feedback zu geben. Jeder Kommentar besteht aus einer unformatierten Textzeichenfolge sowie Informationen zum Autor und ist an einer bestimmten Stelle einer Folie angefügt. Kommentare können beim Bearbeiten der Präsentation sichtbar sein, sie werden jedoch beim Halten der Bildschirmpräsentation nicht angezeigt. Die anzeigende Anwendung bestimmt, wann Kommentare angezeigt werden sollen, und deren visuelle Darstellung.

Wie im folgenden Open XML SDK-Codebeispiel gezeigt ist jede Instanz der Comment-Klasse einer Instanz der SlideCommentsPart-Klasse zugeordnet, die einen Folienkommentarteil darstellt. Hierbei handelt es sich um einen der Teile eines PresentationML-Präsentationsdateipakets und einen Teil, der für jede Folie in einer Präsentationsdatei erforderlich ist, die Kommentare enthält. Jede Comment-Klasseninstanz ist ebenfalls einer Instanz der CommentAuthor-Klasse zugeordnet, die wiederum einem Präsentationsteil mit ähnlichem Namen zugeordnet ist. Dieser Teil wird durch die CommentAuthorsPart-Klasse dargestellt. Die Autoren von Kommentaren für eine Präsentation werden in einer Kommentarautorliste angegeben, die durch eine CommentAuthorList-Klasse dargestellt ist. Die Kommentare zu jeder Folie hingegen werden in einer Kommentarliste für die jeweilige Folie angegeben, die durch die CommentList-Klasse dargestellt ist.

Die Comment-Klasse, die das <cm>-Element darstellt, ist daher auch anderen Klassen zugeordnet, die die untergeordneten Elemente des <cm>-Elements darstellen. Unter diesen Klassen befindet sich wie im folgenden Codebeispiel zu sehen die Position-Klasse, die die Position des Kommentars relativ zur Folie angibt, und die Text-Klasse, die den Textinhalt des Kommentars angibt.

Codebeispiel für das Open XML SDK

Mit dem folgenden Codesegment aus dem Artikel Anleitung: Hinzufügen eines Kommentars zu einer Folie in einer Präsentation wird ein neuer Kommentarteil einer vorhandenen Folie in einer Präsentation hinzugefügt (falls die Folie nicht bereits Kommentare enthält), und es wird eine Instanz einer Open XML SDK 2.0-Klasse Comment im Folienkommentarteil erstellt. Zudem wird eine Kommentarliste dem Kommentarteil hinzugefügt, indem eine Instanz der CommentList-Klasse erstellt wird, falls diese noch nicht vorhanden ist. Dann wird dem Kommentar eine ID zugeordnet und ein Kommentar der Kommentarliste hinzugefügt, indem eine Instanz der Comment-Klasse erstellt wird, wobei die erforderlichen Attributwerte zugewiesen werden. Darüber hinaus werden Instanzen der Klassen Position und Text erstellt, die der neuen Comment-Klasseninstanz zugeordnet werden. Das vollständige Codebeispiel finden Sie in dem zuvor genannten Artikel.

   // 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 == null)
        {
            // Add a new comments list.
            commentsPart.CommentList = new CommentList();
        }

        // Get the new comment ID.
        uint commentIdx = author.LastIndex == 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 });

 ' 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})

Generiertes PresentationML-Dokument

Bei Ausführung des Open XML SDK 2.0-Codes in Anleitung: Hinzufügen eines Kommentars zu einer Folie in einer Präsentation einschließlich des in diesem Artikel gezeigten Segments wird der folgende XML-Code in einen neuen Teil CommentAuthors.xml in dem vorhanden PresentationML-Dokument geschrieben, auf das in diesem Code verwiesen wird. Dabei wird vorausgesetzt, dass das Dokument keine Kommentare oder Kommentarautoren enthielt, bevor der Code ausgeführt wurde.

<?xml version="1.0" encoding="utf-8"?>
<p:cmAuthorLst xmlns:p="https://schemas.openxmlformats.org/presentationml/2006/main">
  <p:cmAuthor id="1"
              name="userName"
              initials="userInitials"
              lastIdx="1"
              clrIdx="0" />
</p:cmAuthorLst>

Darüber hinaus wird der folgende XML-Code in einen neuen Comments.xml-Teil im vorhandenen PresentationML-Dokument geschrieben, auf das in dem Code im Artikel verwiesen wird.

<?xml version="1.0" encoding="utf-8"?>
<p:cmLst xmlns:p="https://schemas.openxmlformats.org/presentationml/2006/main">
  <p:cm authorId="1"
        dt="2010-09-07T16:01:18.5351166-07:00"
        idx="1">
    <p:pos x="100"
           y="200" />
    <p:text>commentText</p:text>
  </p:cm>
</p:cmLst>