在 Android 上管理演示文稿批注

概述

本文介绍了如何使用 Aspose.Slides for Android via Java 管理演示文稿批注。它说明了主要的批注相关类型,并演示了如何向幻灯片添加批注、访问现有批注、处理回复和现代批注以及从演示文稿中删除批注。

示例覆盖了 PowerPoint 中常见的审阅和协作场景,例如为作者分配批注、读取批注文本和元数据、构建回复链,以及删除选定的批注或全部批注。

在 PowerPoint 中,批注显示为幻灯片上的注释。选择批注后会显示其文本和相关讨论。

如需在打开演示文稿时请求显示或隐藏批注(而不更改批注本身),请参阅Show or Hide Comments When Opening a Presentation。

为什么向演示文稿添加批注?

在审阅演示文稿时,您可以使用批注提供反馈并与同事协作。

Aspose.Slides for Android via Java 提供了以下用于操作批注的 API:

  • The Presentation class, which provides access to the presentation’s comment authors. 类,提供对演示文稿批注作者的访问。
  • The ICommentCollection interface, which represents the comments associated with an individual author. 接口,表示与单个作者关联的批注。
  • The IComment interface, which provides information about a comment, including its author, creation time, position, and text. 接口,提供有关批注的信息,包括作者、创建时间、位置和文本。
  • The CommentAuthor class, which provides information about an author, including their name, initials, and associated comments. 类,提供有关作者的信息,包括名称、缩写和关联的批注。

添加幻灯片批注

示例创建了两张幻灯片,并使用addAuthor注册了一个批注作者。它使用addComment在每张幻灯片上放置一个批注,然后使用getSlideComments检索该作者在第一张幻灯片上的批注。控制台两次显示第一条批注的文本,演示了通过幻灯片和作者两种方式的访问,保存的演示文稿中包含这两个批注。

import com.aspose.slides.IComment;
import com.aspose.slides.ICommentAuthor;
import com.aspose.slides.ISlide;
import com.aspose.slides.Presentation;
import com.aspose.slides.SaveFormat;
import android.graphics.PointF;
import java.util.Date;

Presentation presentation = new Presentation();
try {
    ISlide firstSlide = presentation.getSlides().get_Item(0);
    ISlide secondSlide = presentation.getSlides().addEmptySlide(presentation.getLayoutSlides().get_Item(0));

    ICommentAuthor author = presentation.getCommentAuthors().addAuthor("Jawad", "MF");
    PointF position = new PointF(0.2f, 0.2f);
    Date createdTime = new Date();

    author.getComments().addComment("Hello Jawad, this is a slide comment", firstSlide, position, createdTime);
    author.getComments().addComment("Hello Jawad, this is the second slide comment", secondSlide, position, createdTime);

    IComment[] comments = firstSlide.getSlideComments(author);
    if (comments.length > 0) {
        IComment firstComment = comments[0];
        System.out.println(firstComment.getText());

        String commentText = firstComment.getAuthor().getComments().get_Item(0).getText();
        System.out.println(commentText);
    }

    presentation.save("Comments_out.pptx", SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

查找或创建批注作者

在自动化审阅反复处理同一演示文稿时,先使用getCommentAuthors返回的集合进行搜索,然后再添加作者。findByNameAndInitials同时匹配名称和缩写并返回匹配作者的数组,若无匹配则返回空数组。相对地,findByName仅按名称搜索,不考虑缩写。使用已在集合中存在的名称和缩写调用addAuthor会抛出异常。

示例需要一个至少包含一张幻灯片的演示文稿文件。两次遍历中,它复用第一匹配的作者,只有在结果为空时才创建新作者。如果有多个匹配,则选取数组的第一个元素,不合并或删除其他作者。随后为选定的作者调用addComment并保存演示文稿。第二次遍历打开第一次的输出并重复该操作。

import com.aspose.slides.ICommentAuthor;
import com.aspose.slides.Presentation;
import com.aspose.slides.SaveFormat;
import android.graphics.PointF;
import java.util.Date;

final String authorName = "Reviewer";
final String authorInitials = "RV";

String inputFile = "input.pptx";
PointF position = new PointF(20, 20);

for (int pass = 1; pass <= 2; pass++) {
    Presentation presentation = new Presentation(inputFile);
    try {
        ICommentAuthor[] matches = presentation.getCommentAuthors().findByNameAndInitials(authorName, authorInitials);

        ICommentAuthor author = matches.length > 0 ? matches[0] : presentation.getCommentAuthors().addAuthor(authorName, authorInitials);
        author.getComments().addComment("Please review this slide.", presentation.getSlides().get_Item(0), position, new Date());

        String outputFile = "review_pass_" + pass + ".pptx";
        presentation.save(outputFile, SaveFormat.Pptx);
        inputFile = outputFile;
    } finally {
        presentation.dispose();
    }
}

第二次遍历添加另一个批注,但不添加新作者,也不删除已有批注。最终文件review_pass_2.pptx同时包含这两个新批注以及任何原始批注。复用作者不会去重批注:若要避免重复添加相同批注,需要在添加前自行实现去重检测。

访问幻灯片批注

示例打开现有演示文稿并读取getCommentAuthors返回的集合。对每个作者,遍历getComments返回的集合,打印幻灯片编号、批注文本、作者名称和创建时间。输入的演示文稿必须包含批注,否则不会产生控制台输出。

import com.aspose.slides.IComment;
import com.aspose.slides.ICommentAuthor;
import com.aspose.slides.Presentation;

Presentation presentation = new Presentation("Comments1.pptx");
try {
    for (ICommentAuthor author : presentation.getCommentAuthors()) {
        for (IComment comment : author.getComments()) {
            System.out.println("Slide: " + comment.getSlide().getSlideNumber());
            System.out.println("Comment: " + comment.getText());
            System.out.println("Author: " + comment.getAuthor().getName());
            System.out.println("Posted at: " + comment.getCreatedTime());
            System.out.println();
        }
    }
} finally {
    presentation.dispose();
}

回复批注

父批注是回复层级顶部的原始批注。IComment.getParentComment和IComment.setParentComment方法允许获取或设置批注的父级。

示例创建了来自两个作者的批注,并使用setParentComment构建回复,包括对另一回复的再回复。向getSlideComments传递null可检索所有作者的批注;控制台根据回复层级深度缩进每条记录。示例保存完整讨论,调用remove删除第一个根批注,并保存第二个演示文稿,其中该批注及其所有回复已被移除。

import com.aspose.slides.IComment;
import com.aspose.slides.ICommentAuthor;
import com.aspose.slides.ISlide;
import com.aspose.slides.Presentation;
import com.aspose.slides.SaveFormat;
import android.graphics.PointF;
import java.util.Date;

Presentation presentation = new Presentation();
try {
    ISlide slide = presentation.getSlides().get_Item(0);

    PointF position = new PointF(10, 10);
    Date createdTime = new Date();

    ICommentAuthor originalAuthor = presentation.getCommentAuthors().addAuthor("Author_1", "A.A.");
    IComment rootComment = originalAuthor.getComments().addComment("comment 1", slide, position, createdTime);

    ICommentAuthor reviewer = presentation.getCommentAuthors().addAuthor("Author_2", "B.B.");
    IComment firstReply = reviewer.getComments().addComment("reply 1 for comment 1", slide, position, createdTime);
    firstReply.setParentComment(rootComment);

    IComment secondReply = reviewer.getComments().addComment("reply 2 for comment 1", slide, position, createdTime);
    secondReply.setParentComment(rootComment);

    IComment subReply = originalAuthor.getComments().addComment("subreply 3 for reply 2", slide, position, createdTime);
    subReply.setParentComment(secondReply);

    reviewer.getComments().addComment("comment 2", slide, position, createdTime);
    IComment separateComment = reviewer.getComments().addComment("comment 3", slide, position, createdTime);

    IComment separateReply = originalAuthor.getComments().addComment("reply 4 for comment 3", slide, position, createdTime);
    separateReply.setParentComment(separateComment);

    IComment[] comments = slide.getSlideComments(null);
    for (int i = 0; i < comments.length; i++) {
        IComment comment = comments[i];
        while (comment.getParentComment() != null) {
            System.out.print("\t");
            comment = comment.getParentComment();
        }

        System.out.println(comments[i].getAuthor().getName() + ": " + comments[i].getText());
    }

    presentation.save("parent_comment.pptx", SaveFormat.Pptx);

    rootComment.remove();
    presentation.save("remove_comment.pptx", SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

添加现代批注

现代批注可以关联到幻灯片本身、特定形状或 AutoShape 内的文本范围。ICommentCollection.addModernComment方法除了接受幻灯片和批注标记坐标外,还接受IShape参数。

当形状参数为null时,批注为幻灯片级批注。其标记由提供的坐标定位,但不关联特定形状,因此IModernComment.getShape返回null。当提供IShape时,批注锚定到该形状。坐标仍定义批注标记在幻灯片上的位置,而形状关联可通过IModernComment.getShape获取。

将现代批注锚定到形状

示例两次调用addModernComment:一次使用null形状创建幻灯片级批注,一次使用矩形作为锚点。读取getShape时,幻灯片级批注的空检查返回true,锚定批注返回Revenue title。两个批注均随演示文稿一起保存。

import com.aspose.slides.IAutoShape;
import com.aspose.slides.ICommentAuthor;
import com.aspose.slides.IModernComment;
import com.aspose.slides.ISlide;
import com.aspose.slides.Presentation;
import com.aspose.slides.SaveFormat;
import com.aspose.slides.ShapeType;
import android.graphics.PointF;
import java.util.Date;

Presentation presentation = new Presentation();
try {
    ISlide slide = presentation.getSlides().get_Item(0);

    ICommentAuthor author = presentation.getCommentAuthors().addAuthor("Reviewer", "RV");

    IAutoShape shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 50, 50, 300, 80);
    shape.setName("Revenue title");
    shape.getTextFrame().setText("Quarterly revenue");

    Date createdTime = new Date();
    PointF slideCommentPosition = new PointF(20, 20);
    PointF shapeCommentPosition = new PointF(60, 60);
    IModernComment slideComment = author.getComments().addModernComment("Review the overall slide layout.", slide, null, slideCommentPosition, createdTime);
    IModernComment shapeComment = author.getComments().addModernComment("Check this title.", slide, shape, shapeCommentPosition, createdTime);

    System.out.println(slideComment.getShape() == null);
    System.out.println(shapeComment.getShape().getName());

    presentation.save("modern_comments.pptx", SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

将批注锚定到不同的形状类型

任何实现IShape的幻灯片对象都可以用作形状锚点。常见示例包括IAutoShape、IPictureFrame、IGroupShape、IConnector以及IGraphicalObject实例(如图表)。

示例使用addModernComment将批注关联到五种形状类型:AutoShape、图片框、组合、连接线和图表。图片使用嵌入的图像数据,无需外部图像文件。每个批注都有各自的标记位置,保存的演示文稿保留所有五种形状的关联。

import com.aspose.slides.ChartType;
import com.aspose.slides.IAutoShape;
import com.aspose.slides.IChart;
import com.aspose.slides.ICommentAuthor;
import com.aspose.slides.IConnector;
import com.aspose.slides.IGroupShape;
import com.aspose.slides.IPPImage;
import com.aspose.slides.IPictureFrame;
import com.aspose.slides.ISlide;
import com.aspose.slides.Presentation;
import com.aspose.slides.SaveFormat;
import com.aspose.slides.ShapeType;
import android.graphics.PointF;
import android.util.Base64;
import java.util.Date;

Presentation presentation = new Presentation();
try {
    ISlide slide = presentation.getSlides().get_Item(0);

    ICommentAuthor author = presentation.getCommentAuthors().addAuthor("Reviewer", "RV");
    Date createdTime = new Date();

    IAutoShape autoShape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 20, 20, 180, 60);
    autoShape.getTextFrame().setText("AutoShape");

    PointF autoShapeCommentPosition = new PointF(30, 30);
    author.getComments().addModernComment("Comment on an AutoShape.", slide, autoShape, autoShapeCommentPosition, createdTime);

    String imageBase64 = "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAFklEQVR4nGP8//8/AwMDEwMDAwMDAwAkBgMB/DXemwAAAABJRU5ErkJggg==";
    byte[] imageData = Base64.decode(imageBase64, Base64.DEFAULT);
    IPPImage image = presentation.getImages().addImage(imageData);
    IPictureFrame pictureFrame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 220, 20, 120, 80, image);
    PointF pictureCommentPosition = new PointF(230, 30);
    author.getComments().addModernComment("Comment on a picture.", slide, pictureFrame, pictureCommentPosition, createdTime);

    IGroupShape groupShape = slide.getShapes().addGroupShape();
    groupShape.getShapes().addAutoShape(ShapeType.Rectangle, 0, 0, 80, 40);
    groupShape.getShapes().addAutoShape(ShapeType.Ellipse, 100, 0, 80, 40);
    PointF groupCommentPosition = new PointF(40, 150);
    author.getComments().addModernComment("Comment on a group.", slide, groupShape, groupCommentPosition, createdTime);

    IConnector connector = slide.getShapes().addConnector(ShapeType.StraightConnector1, 220, 150, 140, 40);
    PointF connectorCommentPosition = new PointF(240, 150);
    author.getComments().addModernComment("Comment on a connector.", slide, connector, connectorCommentPosition, createdTime);

    IChart chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 400, 20, 250, 180);
    PointF chartCommentPosition = new PointF(420, 40);
    author.getComments().addModernComment("Comment on a graphical object.", slide, chart, chartCommentPosition, createdTime);

    presentation.save("modern_comment_shape_types.pptx", SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

将批注锚定到文本并设置其状态

对于与IAutoShape关联的现代批注,IModernComment.getTextSelectionStart和IModernComment.setTextSelectionStart访问形状文本框中所选文本的起始位置。IModernComment.getTextSelectionLength和IModernComment.setTextSelectionLength访问选区长度。两者共同将批注关联到 AutoShape 内的特定文本范围。

IModernComment.getStatus和IModernComment.setStatus访问ModernCommentStatus 常量中的值:

  • NotDefined — 未定义特定的现代批注状态。
  • Active — 批注处于活动状态。
  • Resolved — 批注已解决。
  • Closed — 批注已关闭。

示例将现代批注锚定到矩形文本中的“quarterly revenue”词组。它根据文本计算零基的选择起始位置并传递给setTextSelectionStart,再使用setTextSelectionLength设置选中字符数。调用setStatus并传入Resolved后,保存并重新打开演示文稿。四个控制台检查均应打印true,确认形状锚点、文本范围和状态均已保留。

import com.aspose.slides.IAutoShape;
import com.aspose.slides.IComment;
import com.aspose.slides.ICommentAuthor;
import com.aspose.slides.IModernComment;
import com.aspose.slides.ISlide;
import com.aspose.slides.ModernCommentStatus;
import com.aspose.slides.Presentation;
import com.aspose.slides.SaveFormat;
import com.aspose.slides.ShapeType;
import android.graphics.PointF;
import java.util.Date;

String outputFile = "modern_comment_text_anchor.pptx";
String shapeText = "Review the quarterly revenue forecast.";
String selectedText = "quarterly revenue";
int expectedSelectionStart = shapeText.indexOf(selectedText);

Presentation presentation = new Presentation();
try {
    ISlide slide = presentation.getSlides().get_Item(0);

    IAutoShape shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 50, 50, 400, 100);
    shape.setName("Forecast text");
    shape.getTextFrame().setText(shapeText);

    ICommentAuthor author = presentation.getCommentAuthors().addAuthor("Reviewer", "RV");
    PointF commentPosition = new PointF(60, 60);
    IModernComment comment = author.getComments().addModernComment("Verify this forecast wording.", slide, shape, commentPosition, new Date());
    comment.setTextSelectionStart(expectedSelectionStart);
    comment.setTextSelectionLength(selectedText.length());
    comment.setStatus(ModernCommentStatus.Resolved);

    presentation.save(outputFile, SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

Presentation reopenedPresentation = new Presentation(outputFile);
try {
    ISlide reopenedSlide = reopenedPresentation.getSlides().get_Item(0);
    IComment[] reopenedComments = reopenedSlide.getSlideComments(null);

    for (IComment reopenedComment : reopenedComments) {
        if (!(reopenedComment instanceof IModernComment)) {
            continue;
        }

        IModernComment modernComment = (IModernComment) reopenedComment;
        boolean shapeMatches = modernComment.getShape() != null && "Forecast text".equals(modernComment.getShape().getName());
        boolean selectionStartMatches = modernComment.getTextSelectionStart() == expectedSelectionStart;
        boolean selectionLengthMatches = modernComment.getTextSelectionLength() == selectedText.length();
        boolean statusMatches = modernComment.getStatus() == ModernCommentStatus.Resolved;

        System.out.println("Shape anchor preserved: " + shapeMatches);
        System.out.println("Text selection start preserved: " + selectionStartMatches);
        System.out.println("Text selection length preserved: " + selectionLengthMatches);
        System.out.println("Resolved status preserved: " + statusMatches);
    }
} finally {
    reopenedPresentation.dispose();
}

检查现有的现代批注

示例需要一个包含现代批注的已有演示文稿,并打印其文本、状态和锚点详情。检查时,先确认哪些批注实现了IModernComment,然后检查IModernComment.getShape、IModernComment.getTextSelectionStart、IModernComment.getTextSelectionLength以及IModernComment.getStatus。null形状表示幻灯片级批注。对于IAutoShape锚点,文本选择方法可标识形状文本框中的关联范围。

import com.aspose.slides.IAutoShape;
import com.aspose.slides.IComment;
import com.aspose.slides.IModernComment;
import com.aspose.slides.IShape;
import com.aspose.slides.ISlide;
import com.aspose.slides.Presentation;

Presentation presentation = new Presentation("comments.pptx");
try {
    for (ISlide slide : presentation.getSlides()) {
        IComment[] comments = slide.getSlideComments(null);
        for (IComment comment : comments) {
            if (!(comment instanceof IModernComment)) {
                continue;
            }

            IModernComment modernComment = (IModernComment) comment;
            System.out.println("Slide: " + slide.getSlideNumber());
            System.out.println("Text: " + modernComment.getText());
            System.out.println("Status: " + modernComment.getStatus());

            IShape shape = modernComment.getShape();
            if (shape == null) {
                System.out.println("Anchor: slide level");
            } else {
                System.out.println("Anchor shape: " + shape.getName());
                System.out.println("Anchor type: " + shape.getClass().getSimpleName());

                if (shape instanceof IAutoShape) {
                    System.out.println("Text selection start: " + modernComment.getTextSelectionStart());
                    System.out.println("Text selection length: " + modernComment.getTextSelectionLength());
                }
            }

            System.out.println();
        }
    }
} finally {
    presentation.dispose();
}

删除批注

Aspose.Slides for Android via Java 允许您删除演示文稿中的所有批注及其作者,或在保留其余内容的情况下删除选定的批注。以下示例演示了这两种方法并保存更新后的演示文稿。

删除所有批注及批注作者

示例打开已有演示文稿,对每位作者调用ICommentCollection.clear,随后调用ICommentAuthorCollection.clear删除作者本身。保存的演示文稿既不包含批注,也不包含批注作者。请使用包含批注的演示文稿观察删除效果。

import com.aspose.slides.ICommentAuthor;
import com.aspose.slides.Presentation;
import com.aspose.slides.SaveFormat;

Presentation presentation = new Presentation("example.pptx");
try {
    for (ICommentAuthor author : presentation.getCommentAuthors()) {
        author.getComments().clear();
    }

    presentation.getCommentAuthors().clear();

    presentation.save("example_out.pptx", SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

删除特定批注

示例在同一幻灯片上创建了两个批注,并使用getSlideComments分别查找每个作者的批注。它收集文本等于“comment 1”的批注,然后调用ICommentCollection.remove进行删除,避免在选择期间修改集合。保存的演示文稿仅保留“comment 2”。

import com.aspose.slides.IComment;
import com.aspose.slides.ICommentAuthor;
import com.aspose.slides.ISlide;
import com.aspose.slides.Presentation;
import com.aspose.slides.SaveFormat;
import android.graphics.PointF;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

Presentation presentation = new Presentation();
try {
    ISlide slide = presentation.getSlides().get_Item(0);

    ICommentAuthor author = presentation.getCommentAuthors().addAuthor("Author", "A");
    Date createdTime = new Date();

    PointF firstCommentPosition = new PointF(0.2f, 0.2f);
    PointF secondCommentPosition = new PointF(0.3f, 0.2f);
    author.getComments().addComment("comment 1", slide, firstCommentPosition, createdTime);
    author.getComments().addComment("comment 2", slide, secondCommentPosition, createdTime);

    for (ICommentAuthor commentAuthor : presentation.getCommentAuthors()) {
        List<IComment> commentsToRemove = new ArrayList<IComment>();
        IComment[] comments = slide.getSlideComments(commentAuthor);

        for (IComment comment : comments) {
            if ("comment 1".equals(comment.getText())) {
                commentsToRemove.add(comment);
            }
        }

        for (IComment comment : commentsToRemove) {
            commentAuthor.getComments().remove(comment);
        }
    }

    presentation.save("pres.pptx", SaveFormat.Pptx);
} finally {
    presentation.dispose();
}

常见问题

Aspose.Slides 是否支持现代批注的已解决状态?

是的。IModernComment.getStatus和IModernComment.setStatus可访问ModernCommentStatus中的值,包括 Resolved。该状态会存储在演示文稿中,文件重新打开后仍可读取。

是否支持线程式讨论(回复链),并且有嵌套层级限制吗?

是的。每个批注都可以引用其parent comment,从而实现回复链。API 并未定义具体的嵌套深度限制。

批注标记在幻灯片上的位置使用哪种坐标系定义?

标记位置使用幻灯片坐标系中的浮点坐标,您可以精确地将其放置在幻灯片的任意位置。