命令

Comments 插件提供以下 TinyMCE 命令。

命令描述

tc-delete-conversation-at-cursor

尝试删除当前光标位置处的评论。删除前将显示确认对话框。

tc-try-delete-all-conversations

尝试删除编辑器中的所有评论。删除前将显示确认对话框。

ToggleSidebar

切换指定侧边栏的打开或关闭状态。当与 'showcomments' 参数一起使用时，此命令会打开评论侧边栏。

示例
tinymce.activeEditor.execCommand('tc-delete-conversation-at-cursor');
tinymce.activeEditor.execCommand('tc-try-delete-all-conversations');
tinymce.activeEditor.execCommand('ToggleSidebar', false, 'showcomments');

事件

以下事件由 Tiny Comments 插件提供。

名称数据描述

mce-tinycomments-update

不适用（N/A）

当评论侧边栏打开或关闭时触发。

CommentChange

{ getEventLog: () ⇒ EventLog[] }

当评论被添加、解决、删除、编辑或回复时触发。

CommentChange 事件

当评论被添加、解决、删除、编辑或回复时触发。包含用于检索评论更改日志的 getEventLog API。

示例：CommentChange 事件

tinymce.init({
  selector: 'textarea',
  plugins: 'tinycomments',
  toolbar: 'addcomment showcomments',
  init_instance_callback: (editor) => {
    editor.on('CommentChange', (evt) => {
      console.log(evt.getEventLog());
    });
  }
});

API

Comments 插件提供了 getEventLog() API，以及一个名为 'tinycomments' 的 annotator，该 annotator 是通过 editor.annotator API创建的。

getEventLog()

getEventLog返回一个日志，其中包含评论所有更改的信息和时间戳，包括以下情况：

  • 添加了新评论。

{
  "type": "create",
  "timestamp": "2024-10-01T03:07:53.771Z",
  "conversationUid": "annotation-r1nn5xdo5ye",
  "conversationContext": "Welcome",
  "conversationContent": "new comment",
  "conversationAuthor": {
      "author": "DEMO USER",
      "authorName": "DEMO USER"
  }
},

  • 编辑了评论。

{
  "type": "edit-comment",
  "timestamp": "2024-10-01T03:08:06.551Z",
  "conversationUid": "annotation-r1nn5xdo5ye",
  "commentUid": "annotation-r1nn5xdo5ye",
  "conversationContext": "Welcome",
  "conversationContent": "new comment",
  "conversationCreatedAt": "2024-10-01T03:07:53.771Z",
  "commentContent": "new comment (Edit comment)",
  "commentAuthor": {
      "author": "DEMO USER",
      "authorName": "DEMO USER"
  },
  "conversationAuthor": {
      "author": "DEMO USER",
      "authorName": "DEMO USER"
  }
},

  • 添加了对评论的回复。

{
  "type": "reply",
  "timestamp": "2024-10-01T03:07:53.771Z",
  "conversationUid": "annotation-r1nn5xdo5ye",
  "commentUid": "annotation-uh00rb41kma",
  "conversationContext": "Welcome",
  "conversationContent": "new comment (Edit comment)",
  "conversationCreatedAt": "2024-10-01T03:07:53.771Z",
  "commentContent": "reply to existing comment",
  "commentAuthor": {
      "author": "DEMO USER",
      "authorName": "DEMO USER"
  },
  "conversationAuthor": {
      "author": "DEMO USER",
      "authorName": "DEMO USER"
  }
},

  • 评论已解决。

{
  "type": "resolve",
  "timestamp": "2024-10-01T03:08:25.783Z",
  "conversationUid": "annotation-r1nn5xdo5ye",
  "conversationContext": "Welcome",
  "conversationContent": "new comment (Edit comment)",
  "conversationAuthor": {
      "author": "DEMO USER",
      "authorName": "DEMO USER"
  }
},

  • 评论被删除。

{
  "type": "delete-comment",
  "timestamp": "2024-10-01T03:08:23.292Z",
  "conversationUid": "annotation-r1nn5xdo5ye",
  "commentUid": "annotation-uh00rb41kma",
  "conversationContext": "Welcome",
  "conversationContent": "new comment (Edit comment)",
  "commentContent": "reply to existing comment",
  "commentAuthor": {
      "author": "DEMO USER",
      "authorName": "DEMO USER"
  },
  "conversationAuthor": {
      "author": "DEMO USER",
      "authorName": "DEMO USER"
  }
},

事件日志可以全部检索，也可以通过 after 选项进行检索，该选项将返回的列表限制为 ISO-8601格式的时间戳日期之后的评论事件，如下所示：

使用 Mentions 插件

当启用 Mentions插件时，上述每个事件都将包含 mentionedUids 属性，该属性包含评论中提到的 UID 数组。只有在启用 Mentions插件时，才会包含 mentionedUids 属性。

建议使用此 API 来检索评论中提到的用户。

mentionedUids 数组会捕获 @ 符号后面的字符串，而不会验证它们是否对应于有效的用户 ID。集成商有责任根据数据库验证这些字符串，以确保它们代表有效的用户。

有关检索和验证 mentionedUids 数组的指导，请参阅 getEventLog 示例。

示例：使用 getEventLog()

// Sample user database
const userDb = {
    "johnsmith": {
        "id": "johnsmith",
        "name": "John Smith",
        "fullName": "John Smith",
        "description": "Company Founder",
        "image": "https://i.pravatar.cc/150?img=11"
    },
    "jennynichols": {
        "id": "jennynichols",
        "name": "Jenny Nichols",
        "fullName": "Jenny Nichols",
        "description": "Marketing Director",
        "image": "https://i.pravatar.cc/150?img=10"
    }
};

const comments = tinymce.activeEditor.plugins.tinycomments;

console.log(comments.getEventLog());
console.log(comments.getEventLog(
  { after: '2022-02-22T12:34:56Z' }  // ISO-8601 standard: YYYY-MM-DDThh:mm:ssZ
));

const eventLog = comments.getEventLog();
const events = eventLog.events;

// 确保被提及的用户是数据库中的有效用户
const validatedEvents = JSON.parse(JSON.stringify(events));
validatedEvents.forEach((event) => {
  // 过滤掉无效用户 - 将此替换为您自己的验证逻辑
  event.mentionedUids = event.mentionedUids ? event.mentionedUids.filter((uid) => userDb[uid]) : undefined;
});

const mentionedUsers = validatedEvents.flatMap(({ mentionedUids }) => mentionedUids || []);
console.log(mentionedUsers);

let whoMentionedWho = {};
validatedEvents.forEach((event) => {
  if ((event.type === "create" || event.type === "reply") && event.mentionedUids !== undefined) {
    console.log(event);
    if (whoMentionedWho[event.conversationAuthor.author] === undefined) {
      whoMentionedWho[event.conversationAuthor.author] = [...event.mentionedUids];
    } else {
      whoMentionedWho[event.conversationAuthor.author].push(...event.mentionedUids);
    }
  }
});
console.log(whoMentionedWho);

'tinycomments' 标注器

Comments 插件提供了一个名为 'tinycomments' 的标注器，该标注器使用 editor.annotator API 构建。

'tinycomments' 标注器用于标注带有对话的内容，并可在 editor.annotator API 的每个方法中使用。

与所有 editor API 一样，'tinycomments' 标注器只能在编辑器初始化后访问。

示例：使用 'tinycomments' 标注器在选中对话时发出通知

此示例使用 editor.annotator API 中的 annotationChanged 方法来创建一个自定义通知。

下面的通知示例会在每次选中带有 'tinycomments' 标注的任何内容时显示五秒钟。

tinymce.init({
  selector: 'textarea',
  plugins: 'tinycomments',
  toolbar: 'addcomment showcomments',
  setup: (editor) => {
    editor.on('init', () => {
      editor.annotator.annotationChanged('tinycomments', (selected, annotatorName, context) => {
        if (selected) {
          editor.notificationManager.open({
            text: `The content you have selected contains a conversation. ${annotatorName}: ${context.uid}.`,
            type: 'info',
            timeout: 5000
          });
        }
      });
    });
  }
});

示例：使用 'tinycomments' 标注器高亮显示对话而不显示评论

此示例使用 editor.annotator API 中的 getAll 方法来高亮显示 'tinycomments' 标注的每个元素。

当工具栏上的 'highlightcomments' 按钮切换为开启状态时，每个标注的元素都会以 aquamarine 高亮显示，而无需用户显示评论。

tinymce.init({
  selector: 'textarea',
  plugins: 'tinycomments',
  toolbar: 'addcomment showcomments highlightcomments',
  setup: (editor) => {
    editor.ui.registry.addToggleButton('highlightcomments', {
      icon: 'highlight-bg-color',
      onAction: (api) => {
        api.setActive(!api.isActive());
        const conversations = editor.annotator.getAll('tinycomments');
        for (const [conversation, elements] of Object.entries(conversations)) {
          elements.forEach((element, _) => {
            if (api.isActive()) {
              element.style.setProperty('background-color', 'aquamarine');
            } else {
              element.style.removeProperty('background-color');
            }
          });
        }
      }
    });
  }
});