使用批注

项目
01/21/2025

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

PresentationML 中的注释

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

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

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>

下表列出了处理注释时使用的元素的 <cm/> 子元素以及与之对应的 Open XML SDK 类。

PresentationML 元素	Open XML SDK 类
`<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) 定义。

Open XML SDK 注释类

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

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

ExtensionListWithModification 类

类 ExtensionListWithModification 对应于 <extLst/>元素。 ISO/IEC 29500 规范中的以下信息介绍了元素<extLst/>：

此元素指定具有修改能力的扩展列表，在该列表中定义元素类型 <ext/> 的所有未来扩展。扩展列表以及相应的未来扩展用于扩展 PresentationML 框架的存储功能。这允许在框架中本机存储各种新类型的数据。

注意

使用此 extLst 元素，生成应用程序可以存储是否已修改此扩展属性。结束注释

Position 类

类 Position 对应于 <pos/>元素。 ISO/IEC 29500 规范中的以下信息介绍了元素<pos/>：

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

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

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

[示例： <p：pos x=“1426” y=“660”/> end example]

Text 类

类 Text 对应于 <text/> 元素。 ISO/IEC 29500 规范中的以下信息介绍了元素<text/>：

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

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

使用 Comment 类

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

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

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

Open XML SDK 代码示例

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

C#
Visual Basic

生成的 PresentationML

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

    <?xml version="1.0" encoding="utf-8"?>
    <p:cmAuthorLst xmlns:p="http://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="http://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 for Office 如何：通过提供文件名创建演示文稿如何：向演示文稿中的幻灯片添加注释如何：删除作者从演示文稿中的所有幻灯片中的所有批注

通过