通过

使用注释

  • 项目

上次修改时间： 2010年10月8日

适用范围： Excel 2010 | Office 2010 | PowerPoint 2010 | Word 2010

本文内容
PresentationML 中的注释
Open XML SDK 2.0 Comment 类
使用 Comment 类
Open XML SDK 代码示例
生成的 PresentationML

本主题讨论 Open XML SDK 2.0 Comment 类以及它与 Open XML 文件格式 PresentationML 架构的关系。有关构成 PresentationML 文档的部件和元素的整体结构的详细信息，请参阅 PresentationML 文档的结构。

PresentationML 中的注释

ISO/IEC 29500（该链接可能指向英文页面） 规范对 Open XML PresentationML 框架的注释部分进行了如下介绍：

注释是附加到幻灯片的文本备注，主要用途是使演示文稿的读者能够向演示文稿作者提供反馈。每个注释包含无格式文本字符串及有关其作者的信息，并附加到幻灯片上的特定位置。在编辑演示文稿时，注释是可见的，但在播放幻灯片时不会出现。显示幻灯片的应用程序决定何时显示注释并确定其外观。

© ISO/IEC29500: 2008。

ISO/IEC 29500（该链接可能指向英文页面） 规范介绍了 Open XML PresentationML <cm> 元素，此元素用于表示 PresentationML 文档中的注释，如下所示：

此元素指定附加到幻灯片的单个注释。它包含注释的文本、注释在幻灯片中的位置以及引用其作者和日期的属性。

[示例：

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

示例结束]

© ISO/IEC29500: 2008。

下表列出了在处理注释和与注释对应的 Open XML SDK 2.0 类时使用的 <cm > 元素的子元素。

PresentationML 元素

Open XML SDK 2.0 类

<extLst>

ExtensionListWithModification

<pos>

Position

<text>

Text

来自 ISO/IEC 29500（该链接可能指向英文页面） 规范的以下表介绍了 <cm> 元素的属性。

属性

说明

authorId

此属性指定注释的作者。它引用文档的注释作者列表中的作者 ID。

此属性的可能值由 W3C XML 架构 unsignedInt 数据类型定义。

dt

此属性指定上次修改此注释的日期和时间。

此属性的可能值由 W3C XML 架构 datetime 数据类型定义。

idx

此属性指定此注释的标识符，该标识符在此文档中由此作者创建的所有注释列表中是唯一的。作者在文档中的第一个注释的索引为 1。

[注意：由于索引仅对于注释作者是唯一的，因此文档可以包含由不同作者创建的具有同一索引的多个注释。注释结束]

此属性的可能值由 ST_Index 简单类型 (§19.7.3) 定义。

© ISO/IEC29500: 2008。

Open XML SDK 2.0 Comment 类

OXML SDK Comment 类表示在 PresentationML 文档的 Open XML 文件格式架构中定义的 <cm> 元素。使用 Comment 类可对 PresentationML 文档中的各个 <cm> 元素执行操作。

下面的列表显示了表示 <cm> 元素的子元素并因此通常与 Comment 类关联的类。

ExtensionListWithModification 类

ExtensionListWithModification 类对应于 <extLst>元素。来自 ISO/IEC 29500（该链接可能指向英文页面） 规范的以下信息介绍了 <extLst> 元素：

此元素指定具有修改功能的扩展名列表，其中定义了元素类型 <ext> 未来的所有扩展名。扩展名列表以及相应的未来扩展名用于扩展 PresentationML 框架的存储功能，从而允许各种新的数据类型以固有的方式存储在该框架内。

[注意：使用此 extLst 元素可以使生成应用程序存储有关此扩展属性是否已修改的相关信息。注释结束]

© ISO/IEC29500: 2008。

Position 类

Position 类对应于 <pos>元素。来自 ISO/IEC 29500（该链接可能指向英文页面） 规范的以下信息介绍了 <pos> 元素：

此元素指定注释在幻灯片表面的放置位置信息。在生成的应用程序的 LTR 版本中，此位置信息应引用注释形状的左上点。在生成的应用程序的 RTL 版本中，此位置信息应引用注释形状的右上点。

[注意：幻灯片表面上的定位点不受从右到左或从左到右的布局更改的影响。也就是说，定位点对于所有语言版本保持不变。注释结束]

[注意：由于注释没有指定的大小或格式，因此用于显示注释的该 UI 小组件可为任意大小，注释形状的右下点根据查看应用程序选择的显示注释方式来确定。注释结束]

[示例：<p:pos x="1426" y="660"/> 示例结束]

© ISO/IEC29500: 2008。

Text 类

Text 类对应于 <text>元素。来自 ISO/IEC 29500（该链接可能指向英文页面） 规范的以下信息介绍了 <text> 元素：

此元素指定注释的内容。这是作者批注幻灯片时使用的文本。

[示例：<p:text>添加图表以进行阐述。</p:text> 示例结束]

此元素的可能值由 W3C XML 架构 string 数据类型定义。

© ISO/IEC29500: 2008。

使用 Comment 类

注释是附加到幻灯片的文本备注，主要用途是使演示文稿的读者能够向演示文稿作者提供反馈。每个注释都包含无格式文本字符串及有关其作者的信息，并附加到幻灯片上的特定位置。在编辑演示文稿时，注释是可见的，但在播放幻灯片时不会出现。显示幻灯片的应用程序决定何时显示注释并确定其外观。

如下面的 Open XML SDK 代码示例所示，Comment 类的每个实例均与 SlideCommentsPart 类的一个实例关联，该类表示一个幻灯片注释部件、PresentationML 演示文稿文件包的部件之一以及包含注释的演示文稿文件中每个幻灯片所需要的部件。每个 Comment 类实例还与 CommentAuthor 类的一个实例关联，该类实例又与名称类似并由 CommentAuthorsPart 类表示的演示文稿部件关联。演示文稿的注释作者在由 CommentAuthorList 类表示的注释作者列表中指定，而每个幻灯片的注释列位于该幻灯片的由 CommentList 类表示的注释列表中。

因此，表示 <cm> 元素的 Comment 类还与表示 <cm> 元素的子元素的其他类关联。如下面的代码示例所示，这些类包括用于指定注释相对于幻灯片的位置的 Position 类和用于指定注释的文本内容的 Text 类。

Open XML SDK 代码示例

来自如何：将注释添加到演示文稿中的幻灯片一文的以下代码段向演示文稿的现有幻灯片中添加一个新的注释部件（如果幻灯片尚未包含注释），并在幻灯片注释部件中创建 Open XML SDK 2.0 Comment 类的实例。如果尚不存在注释列表，它还通过创建 CommentList 类的实例来向注释部件中添加注释列表；为注释分配 ID；然后通过创建 Comment 类的实例并分配必需的属性值来向注释列表中添加注释。此外，该代码段还创建 Position 和 Text 类的实例，这些类实例与新的 Comment 类实例关联。有关完整的代码示例，请参阅上述文章。

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

生成的 PresentationML

在运行如何：将注释添加到演示文稿中的幻灯片中的 Open XML SDK 2.0 代码（包括本文所示的代码段）时，会将以下 XML 写入代码中引用的现有 PresentationML 文档中的新 CommentAuthors.xml 部件（假设在运行该代码之前，该文档不包含任何注释或注释作者）。

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

此外，还会将以下 XML 写入本文代码所引用的现有 PresentationML 文档中的新 Comments.xml 部件。

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

请参阅

概念

关于 Open XML SDK 2.0 for Microsoft Office

如何：通过提供文件名创建演示文稿

如何：将注释添加到演示文稿中的幻灯片

如何：按作者从演示文稿中的所有幻灯片中删除注释