在 Java 中管理簡報註解

概觀

本文說明如何使用 Aspose.Slides for Java 來管理簡報註解。它會介紹與註解相關的主要型別,並示範如何在投影片上加入註解、存取現有註解、處理回覆與現代註解,以及如何從簡報中移除註解。

這些範例涵蓋 PowerPoint 中常見的審閱與協作情境,例如指派註解給作者、讀取註解文字與中繼資料、建構回覆鏈,以及移除選取的註解或全部註解。

在 PowerPoint 中,註解會顯示為投影片上的標註。選取註解時會顯示其文字與相關討論。

若要在開啟簡報時要求顯示或隱藏註解(而不變更註解本身),請參閱顯示或隱藏開啟簡報時的註解。

為何要在簡報中加入註解?

在審閱簡報時,您可以使用註解提供回饋並與同事協作。

Aspose.Slides for Java 提供以下 API 以處理註解:

  • Presentation 類別,提供存取簡報的註解作者。
  • ICommentCollection 介面,代表與單一作者相關的註解集合。
  • IComment 介面,提供註解的相關資訊,包括作者、建立時間、位置與文字。
  • CommentAuthor 類別,提供作者資訊,包括名稱、縮寫與相關註解。

新增投影片註解

此範例建立兩張投影片,並使用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 java.awt.geom.Point2D;
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");
    Point2D.Float position = new Point2D.Float(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 java.awt.geom.Point2D;
import java.util.Date;

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

String inputFile = "input.pptx";
Point2D.Float position = new Point2D.Float(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 建立回覆,包括對另一回覆的回覆。傳遞 null 給getSlideComments 會取得所有作者的註解;主控台會依回覆階層深度縮排顯示。範例儲存完整的討論串,對第一個根註解呼叫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 java.awt.geom.Point2D;
import java.util.Date;

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

    Point2D.Float position = new Point2D.Float(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(null 檢查)以及錨定註解的 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 java.awt.geom.Point2D;
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();
    Point2D.Float slideCommentPosition = new Point2D.Float(20, 20);
    Point2D.Float shapeCommentPosition = new Point2D.Float(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 java.awt.geom.Point2D;
import java.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");

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

    String imageBase64 = "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAFklEQVR4nGP8//8/AwMDEwMDAwMDAwAkBgMB/DXemwAAAABJRU5ErkJggg==";
    byte[] imageData = Base64.getDecoder().decode(imageBase64);
    IPPImage image = presentation.getImages().addImage(imageData);
    IPictureFrame pictureFrame = slide.getShapes().addPictureFrame(ShapeType.Rectangle, 220, 20, 120, 80, image);
    Point2D.Float pictureCommentPosition = new Point2D.Float(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);
    Point2D.Float groupCommentPosition = new Point2D.Float(40, 150);
    author.getComments().addModernComment("Comment on a group.", slide, groupShape, groupCommentPosition, createdTime);

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

    IChart chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 400, 20, 250, 180);
    Point2D.Float chartCommentPosition = new Point2D.Float(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 java.awt.geom.Point2D;
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");
    Point2D.Float commentPosition = new Point2D.Float(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 shape 表示投影片層級的註解。對於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 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 java.awt.geom.Point2D;
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();

    Point2D.Float firstCommentPosition = new Point2D.Float(0.2f, 0.2f);
    Point2D.Float secondCommentPosition = new Point2D.Float(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。此狀態會儲存在簡報中,重新開啟檔案後仍可讀取。

是否支援串接式討論(回覆鏈),且有巢狀深度限制嗎?

支援。每則註解皆可參照其父註解,從而形成回覆鏈。API 未定義特定的巢狀深度上限。

註解標記在投影片上的座標系統是什麼?

標記位置以浮點座標定義於投影片座標系統中,讓您能精確地將其放置於投影片上。