文档批注(评论)

文档批注功能允许用户在文档中添加批注，同时支持在多人协作编辑时进行批注。

效果截图

文档批注

特点及优势

支持私有化部署，您可以通过私有化部署，实现数据的安全性和可控性；
支持在线协作，您可以在多人协作编辑时，添加批注；
支持离线批注，您可以在离线时，仍然可以添加批注，批注内容会在您重新连接时，自动同步到服务器端；
支持各种节点类型和内联添加批注，您可以在文档中添加和管理各类批注；
评论中支持 @ 功能，您可以在评论中@其他用户，实现对其他用户的提醒；
支持标记已完成/未完成、编辑或删除评论，您可以在批注线程中，对评论进行编辑、删除或标记；
支持回复评论，您可以在批注线程中，回复其他评论；
支持向评论中添加自定义数据。

核心概念

批注：文档批注功能中的线程表示一组与某个文档位置关联的评论消息，可以包含多个评论和创建时间，ID 等元数据。线程绑定到文档的某个范围，单条评论包含在线程中。

评论：是指批注线程中的单条评论。

示例：一个典型的批注线程示例如下：

{
  id: '7ihgradlfp',
  data: {
    user: { id: 'c6x2', name: '用户-c6x2', color: '#7fe67f' },
    ref: '被引用的文字',
  },
  comments: [
    {
      id: 'wls7unwl2t',
      data: { 
        user: { id: 'c6x2', name: '用户-c6x2', color: '#7fe67f' } 
      },
      content: '<p>这是一条批注信息</p>',
      createdAt: '2025-04-14T06:37:12.835Z',
    },
    {
      id: 'v9eabcjenh',
      data: {
        user: { id: 'c6x2', name: '用户-c6x2', color: '#7fe67f' },
        replyId: 'wls7unwl2t',
      },
      content: '<p>这是一条回复信息</p>',
      createdAt: '2025-04-14T06:37:30.035Z',
    },
  ],
  createdAt: '2025-04-14T06:37:12.833Z',
}

接口定义：线程和评论的接口格式定义如下：

// 定义线程的接口，包含线程的基本信息和评论列表
interface Thread {
  id: string // 线程唯一标识符
  data: any
  comments: Comment[] // 线程中的评论列表
  createdAt: string // 线程创建时间
  updatedAt?: string // 线程更新时间
  resolvedAt?: string // 线程解决时间
}
 
// 定义评论的接口，包含评论的基本信息
interface Comment {
  id: string // 评论唯一标识符
  data: any
  content: string // 评论内容
  createdAt: string // 评论创建时间
  updatedAt?: string // 评论更新时间
}

默认配置

const defaultOptions = {
  // 文档批注相关配置
  comments: {
    enabled: false,
    threads: [], 
    onGetThreads: undefined,
    onSetThread: undefined,
    onCreateThread: undefined,
    onUpdateThread: undefined,
    onDeleteThread: undefined,
    onCreateComment: undefined,
    onUpdateComment: undefined,
    onDeleteComment: undefined,
  },
}

配置说明

comments

文档批注相关配置。

comments.enabled：

说明：是否开启批注功能

类型：Boolean

默认值：true

comments.threads：

说明：批注线程的初始数据。在开启了多人协作编辑时，该选项不生效，线程列表默认从服务商获取。

类型：Array

默认值：[]

comments.onGetThreads：

说明：获取批注线程列表的回调函数。

类型：Function

参数：undefined

返回值：Array，批注线程列表。

默认值：undefined

comments.onSetThread：

说明：设置批注线程的回调函数。

类型：Function

参数：thread，新设置的批注线程。

默认值：undefined

comments.onCreateThread：

说明：创建批注线程的回调函数。

类型：Function

参数：thread，新创建的批注线程。

默认值：undefined

comments.onUpdateThread：

说明：更新批注线程的回调函数。

类型：Function

参数：thread，更新后的批注线程。

默认值：undefined

comments.onDeleteThread：

说明：删除批注线程的回调函数。

类型：Function

参数：threadId，已删除的批注线程 ID。

默认值：undefined

comments.onCreateComment：

说明：创建批注的回调函数。

类型：Function

参数：comment，新创建的批注信息。

默认值：undefined

comments.onUpdateComment：

说明：更新批注的回调函数。

类型：Function

参数：comment，更新后的批注信息。

默认值：undefined

comments.onDeleteComment：

说明：删除批注的回调函数。

类型：Function

参数：{threadId, commentId}，已删除的批注线程 ID 和评论 ID。

默认值：undefined

方法列表

方法的使用示例请参考：方法列表。

getComments

说明：获取批注相关信息。在开启了多人协作编辑功能时，您也可以通过 getCollaboration方法，获取到 provider 后，通过 provider 来获取或设置更多的批注的信息，这要求您对Hocuspocus有比较深入的了解。

参数：无

返回值：Object 或 undefined，Object 包含以下信息：

connect：Boolean，是否与服务商连接成功；
threads：Array，当前文档批注线程列表。

主题定制

CSS 变量

您可以通过修改以下 CSS 变量来修改批注的样式。

--umo-thread-background: #ffcc00;
--umo-thread-hover-background: #ffcc0040;
--umo-thread-inline-background: #ffcc00;
--umo-thread-resolved-background: #63c493;
--umo-thread-resolved-hover-background: #63c49340;

多人协作编辑导出为 Word