🎉🎉🎉 移动端文档编辑器 Umo Editor Mobile 现已发布，了解更多 →
开发文档Umo Editor Next文档批注/评论

文档批注(评论)

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

效果截图

Umo Editor 文档批注

演示视频

特点及优势

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

使用场景

  • 评审与验收：对某段文字提出修改建议并跟踪是否已处理
  • 协作写作：边写边评论，避免在正文里反复插入说明性文字
  • 合同/制度审阅：按条款逐段提出问题与风险点
  • 文档走查：对目录、表格、图片、脚注等结构问题逐条标记
  • 教学/培训批改：对学员提交的文档逐点点评并留痕
  • 需求评审记录：把讨论结论沉淀为线程，便于后续追溯
  • 内容合规检查：对敏感表述/免责声明等关键点发起审查
  • 客服/知识库维护：对过时内容打标并分配处理人
  • 会议纪要确认：@ 相关负责人确认关键事项与责任人
  • AI 生成校对：对 AI 产出的段落逐条指出问题并要求修订

与其他功能协同使用

多人协作（collaboration）

  • 评论与正文编辑解耦，适合多人并行讨论与修改：多人协作编辑
  • 协作同步评论线程，避免“只在某个客户端可见”的信息孤岛

文档修订（revision）

  • 评论负责“讨论与决策”，修订负责“变更记录与定稿”：文档修订
  • 审阅阶段先按评论收敛结论，再对修订执行接受/拒绝

历史版本（versions）

  • 在关键节点创建版本，并将评论作为验收记录的一部分沉淀：文档历史版本
  • 对比版本差异时，可结合评论线程快速理解“为什么改”

AI（ai）

  • 用 AI 生成初稿后，用评论逐点指出需要修改之处，再由 AI/人工按点修订：AI 功能

核心概念

批注：文档批注功能中的线程表示一组与某个文档位置关联的评论消息，可以包含多个评论和创建时间，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,
  },
}

自 v10 开始，Umo Editor Next 文档保存配置 onSave 方法新增了 comments 参数，用于保存文档批注线程。

onSave 方法见 文档保存配置

以下是一个简单的 onSave 方法示例：

const onSave = async (content, page, document, comments) => {
  // 将文档和评论线程保存到 localStorage
  localStorage.setItem('document.content', content)
  localStorage.setItem('document.comments', JSON.stringify(comments))
 
  // 模拟保存等待过程
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log('onSave', { content, page, document, comments })
      resolve('操作成功')
    }, 1000)
  })
}

配置说明

comments

文档批注相关配置。

  • comments.enabled：

说明：是否开启批注功能

类型：Boolean

默认值：true

  • comments.threads：

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

类型：Array

默认值：[]

  • comments.onGetThreads：

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

类型：Function

参数：无

返回值：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;
多人协作编辑基本介绍