GCExcel5.0新特性 - 上下文批注（Threaded Comments）

bakefish

本帖最后由 Winny 于 2022-1-27 09:45 编辑

常见的表格产品提供了插入批注的功能，具体的展现形式如下：
image.png46194457.png

使用该功能，不同的用户可以对同一区域的内容做出解释说明，建立对话。GCExcel5.0对该功能进行了支持。
下面介绍该功能的一些使用说明：
1. 使用IWorksheet.CommentsThreaded来获取工作表上的所有上下文批注集合，集合中的顺序先按行排序，再按列顺序；
2. 使用IRange.AddCommentThreaded(String text,String author)将新的批注添加到对应区域中，如果author为空，则批注会使用集合列表中的最后一位作者，如果集合列表为空，则添加一个空的author；
3. 使用Icommentsthread[int index]从上下文批准列表中按索引获取批注；
4. 使用ICommentsThreaded.Count可获取当前工作表中上下文批注的数量；
5. 使用ICommentThreaded.IsResolved获取或设置上下文批注的锁定状态，如果IsResolved为true，则禁止对批注进行编辑和回复；
6. 使用ICommentThreaded.Text获取或设置批注的文本内容。如果IsResolved为true，则在设置内容时抛出InvalideException；
7. 使用ICommentThreaded.Replies获取指定批注的所有答复，答复按照时间戳排序，如果某一批注本身是回复，则返回null；
8. 使用ICommentThreaded.Date以获取一个日期，该日期表示在本地时间中添加上下文批注的日期和时间；
9. 使用ICommentThreaded.Next()获取下一条上下文批注(答复)，如果当前sheet中只有一条批注或当前批注是最后一条，返回null。如果当前批注是某一个批注的最后一个回复，也返回null；
10. 使用ICommentThreaded.Previous()获取前一条批注（答复），如果当前sheet中只有一条批注，则返回null，如果当前批注是某一批注的第一条回复，也返回null;
11. 使用ICommentThreaded.Parent获取当前回复的父对象（如果当前批注是一个回复），如果该上下文批注为顶级批注，返回null;
12. 使用ICommentThreaded.AddReply（String text，String author=null）向上下文批注添加回复。如果当前批注是顶级批注，它将向其“回复”集合添加回复。
如果当前批注是回复，它将向其父级的回复集合添加回复；
13. 使用ICommentThreaded.Delete()删除指定的批注，如果当前批注是顶级批注，则删除该批注的同时，删除与之关联的回复。如果当前批注是一个回复，则从它的父级答复列别中删除本身；
14. 使用ICommentThreaded.Author来获取批注的作者。
15. 使用 IAuthor.Name来设置或获取批注的名称；
16. 导出Html时支持上下文批注；
17. 导出json时支持线程注释；
18. 导出PDF/图像时不支持上下文批注。

需要注意的是，由于SpreadJS目前并不支持上下文批注，因此在到处json时，GCExcel会将批注转为普通注释。
与之相关的API有以下几个：

public interface IWorksheet
{
//获取当前WorkSheet中的所有上下文对象
ICommentsThreaded CommentsThreaded { get; }
}

复制代码

public interface IRange
{
//清空当前区域的上下文批注
void ClearCommentsThreaded();
//当前区域添加批注
ICommentThreaded AddCommentThreaded(string text, string author = null);

复制代码

public interface IAuthor
{
//获取批注作者名称
string Name { get; set; }
}

复制代码

public interface ICommentsThreaded
{
//获取特定索引的批注
ICommentThreaded this[int Index] { get; }
//获取批注数量
int Count { get; }
}

复制代码

public interface ICommentThreaded
{
//当前批注添加回复
ICommentThreaded AddReply(string text, string author = null);
//删除批注或回复
void Delete();
// 设置或获取批注锁定状态
bool IsResolved { get; set; }
//获取或设置批注内容
string Text { get; set; }
//获取批注回复的集合
ICommentsThreaded Replies { get; }
//获取批注作者名称
IAuthor Author { get; }
//获取批注添加时间
DateTime Date { get; }//获取下一条批注，如果当前批注是sheet中的最后一个顶层批注，返回null。如果当前批注是最后一个回复，也返回null。
ICommentThreaded Next();//获取上一条批注，如果当前批注是sheet中第一个顶层批注，返回null。如果当前批注是第一个回复，也返回null。
ICommentThreaded Previous();
// 获取父级批注
ICommentThreaded Parent { get; }
}

复制代码

最后，提供一个简单的测试用例：

Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getActiveSheet();
//Add a threaded comment
ICommentThreaded commentThreaded =worksheet.getRange("A1").addCommentThreaded("Test CommentThreaded to json01","Winny");
ICommentThreaded reply = commentThreaded.addReply("hello Winny","memo");
workbook.save("out.xlsx");

复制代码

在搭建好的java项目中运行上述代码之后，将生成的文件打开，展示效果如下：
image.png353484801.png

相关的一些其它API如下所示：

Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getActiveSheet();
//添加批注
ICommentThreaded commentThreaded = worksheet.getRange("A1").addCommentThreaded("Test CommentThreaded to json01","Winny");
//当前批注添加回复
ICommentThreaded reply01 = commentThreaded.addReply("hello Winny","memo");
ICommentThreaded reply02 = commentThreaded.addReply("Hi memo","Winny");
ICommentThreaded reply03 = commentThreaded.addReply("this is a cat","Mario");
//添加批注
worksheet.getRange("B1").addCommentThreaded("Test CommentThreaded to json02", "Dextor");
//获取当前sheet中的所有批注
ICommentsThreaded comments = worksheet.getCommentsThreaded();
//获取批注数量
int count = comments.getCount();
//获取第一个批注
ICommentThreaded comment0 = comments.get(0);
//获取当前批注的所有回复
ICommentsThreaded replies = comment0.getReplies();
//获取当前批注的回复总数量
int count02 = replies.getCount();
//获取当前批注的第三个回复
ICommentThreaded replay01 = replies.get(2);
//获取当前批注（回复）的下一条批注（回复），如果已经是最后一条，返回null
ICommentThreaded nextComment = comment0.next();
//获取当前批注（回复）的上一条批注（回复），如果已经是最后一条，返回null
ICommentThreaded preComment = comment0.previous();
//获取回复的顶级批注
ICommentThreaded parent = replay01.getParent();