ContextQMD
Back to Plate

评论

docs/(plugins)/(collaboration)/comment.cn.mdx

1.0.010.5 KB
Original Source
<ComponentPreview name="discussion-demo" /> <PackageInfo>

功能特性

  • 文本评论: 将评论作为文本标记添加,支持内联注释
  • 重叠评论: 支持在同一文本上添加多个评论
  • 草稿评论: 在最终确认前创建草稿评论
  • 状态追踪: 追踪评论状态和用户交互
  • 讨论集成: 与讨论插件配合使用,实现完整的协作功能
</PackageInfo>

Kit 用法

<Steps>

安装

添加评论功能最快的方式是使用 CommentKit,它包含预配置的 commentPlugin 和相关组件,以及对应的 Plate UI 组件。

<ComponentSource name="comment-kit" />

添加 Kit

tsx
import { createPlateEditor } from 'platejs/react';
import { CommentKit } from '@/components/editor/plugins/comment-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...CommentKit,
  ],
});
</Steps>

手动用法

<Steps>

安装

bash
npm install @platejs/comment

扩展评论插件

创建带有扩展配置的评论插件以进行状态管理:

tsx
import { type ExtendConfig, type Path, isSlateString } from 'platejs';
import {
  type BaseCommentConfig,
  BaseCommentPlugin,
  getDraftCommentKey,
} from '@platejs/comment';
import { toTPlatePlugin } from 'platejs/react';
import { CommentLeaf } from '@/components/ui/comment-node';

type CommentConfig = ExtendConfig<
  BaseCommentConfig,
  {
    activeId: string | null;
    commentingBlock: Path | null;
    hoverId: string | null;
    uniquePathMap: Map<string, Path>;
  }
>;

export const commentPlugin = toTPlatePlugin<CommentConfig>(
  BaseCommentPlugin,
  ({ editor }) => ({
    options: {
      activeId: null,
      commentingBlock: null,
      hoverId: null,
      uniquePathMap: new Map(),
    },
    render: {
      node: CommentLeaf,
    },
  })
);
  • options.activeId: 当前激活的评论 ID,用于视觉高亮
  • options.commentingBlock: 当前正在评论的块的路径
  • options.hoverId: 当前悬停的评论 ID,用于悬停效果
  • options.uniquePathMap: 用于评论解析的唯一路径映射
  • render.node: 指定 CommentLeaf 来渲染评论文本标记

添加点击处理器

添加点击处理来管理激活评论状态:

tsx
export const commentPlugin = toTPlatePlugin<CommentConfig>(
  BaseCommentPlugin,
  ({ editor }) => ({
    handlers: {
      // Set active comment when clicking on comment marks
      onClick: ({ api, event, setOption, type }) => {
        let leaf = event.target as HTMLElement;
        let isSet = false;

        const unsetActiveComment = () => {
          setOption('activeId', null);
          isSet = true;
        };

        if (!isSlateString(leaf)) unsetActiveComment();

        while (leaf.parentElement) {
          if (leaf.classList.contains(`slate-${type}`)) {
            const commentsEntry = api.comment.node();

            if (!commentsEntry) {
              unsetActiveComment();
              break;
            }

            const id = api.comment.nodeId(commentsEntry[0]);
            setOption('activeId', id ?? null);
            isSet = true;
            break;
          }

          leaf = leaf.parentElement;
        }

        if (!isSet) unsetActiveComment();
      },
    },
    // ... previous options and render
  })
);

点击处理器追踪当前激活的评论:

  • 检测评论点击: 遍历 DOM 以找到评论元素
  • 设置激活状态: 点击评论时更新 activeId
  • 清除状态: 点击评论外部时取消 activeId
  • 视觉反馈: 在评论组件中启用悬停/激活样式

扩展 Transforms

扩展 setDraft transform 以增强功能:

tsx
export const commentPlugin = toTPlatePlugin<CommentConfig>(
  BaseCommentPlugin,
  ({ editor }) => ({
    // ... previous configuration
  })
)
  .extendTransforms(
    ({
      editor,
      setOption,
      tf: {
        comment: { setDraft },
      },
    }) => ({
      setDraft: () => {
        if (editor.api.isCollapsed()) {
          editor.tf.select(editor.api.block()![1]);
        }

        setDraft();

        editor.tf.collapse();
        setOption('activeId', getDraftCommentKey());
        setOption('commentingBlock', editor.selection!.focus.path.slice(0, 1));
      },
    })
  )
  .configure({
    node: { component: CommentLeaf },
    shortcuts: {
      setDraft: { keys: 'mod+shift+m' },
    },
  });

添加工具栏按钮

你可以将 CommentToolbarButton 添加到你的工具栏中,以便在选中文本上添加评论。

添加插件

tsx
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    commentPlugin,
  ],
});

讨论集成

评论插件与讨论插件配合使用,实现完整的协作功能:

tsx
import { discussionPlugin } from '@/components/editor/plugins/discussion-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    discussionPlugin,
    commentPlugin,
  ],
});
</Steps>

键盘快捷键

<KeyTable> <KeyTableItem hotkey="Cmd + Shift + M"> 在选中文本上添加评论。 </KeyTableItem> </KeyTable>

Plate Plus

<ComponentPreviewPro name="discussion-pro" />

插件

CommentPlugin

用于创建和管理文本评论的插件,支持状态追踪和讨论集成。

<API name="CommentPlugin"> <APIOptions> <APIItem name="activeId" type="string | null"> 当前激活的评论 ID,用于视觉高亮。内部用于追踪状态。 </APIItem> <APIItem name="commentingBlock" type="Path | null"> 当前正在评论的块的路径。 </APIItem> <APIItem name="hoverId" type="string | null"> 当前悬停的评论 ID,用于悬停效果。 </APIItem> <APIItem name="uniquePathMap" type="Map<string, Path>"> 用于评论解析的唯一路径映射。 </APIItem> </APIOptions> </API>

API

api.comment.has

检查编辑器中是否存在指定 ID 的评论。

<API name="has"> <APIParameters> <APIItem name="options" type="{ id: string }"> 包含要检查的评论 ID 的选项。 </APIItem> </APIParameters> <APIReturns type="boolean">评论是否存在。</APIReturns> </API>

api.comment.node

获取评论节点条目。

<API name="node"> <APIOptions type="EditorNodesOptions & { id?: string; isDraft?: boolean }" optional > 查找节点的选项。 </APIOptions> <APIReturns type="NodeEntry<TCommentText> | undefined"> 如果找到则返回评论节点条目。 </APIReturns> </API>

api.comment.nodeId

从叶子节点获取评论的 ID。

<API name="nodeId"> <APIParameters> <APIItem name="leaf" type="TCommentText"> 评论叶子节点。 </APIItem> </APIParameters> <APIReturns type="string | undefined">如果找到则返回评论 ID。</APIReturns> </API>

api.comment.nodes

获取匹配选项的所有评论节点条目。

<API name="nodes"> <APIOptions type="EditorNodesOptions & { id?: string; isDraft?: boolean }" optional > 查找节点的选项。 </APIOptions> <APIReturns type="NodeEntry<TCommentText>[]"> 评论节点条目数组。 </APIReturns> </API>

Transforms

tf.comment.removeMark

从当前选区或指定位置移除评论标记。

<API name="removeMark" />

tf.comment.setDraft

在当前选区设置草稿评论标记。

<API name="setDraft"> <APIOptions type="SetNodesOptions" optional> 设置草稿评论的选项。 </APIOptions> </API>

tf.comment.unsetMark

从编辑器中取消指定 ID 的评论节点。

<API name="unsetMark"> <APIParameters> <APIItem name="options" type="{ id: string; transient?: boolean }"> 取消评论标记的选项。 </APIItem> </APIParameters> <APIOptions type="object"> <APIItem name="id" type="string"> 要取消的评论 ID。 </APIItem> <APIItem name="transient" type="boolean" optional> 当为 true 时,一次性移除所有 AI 评论。 - **默认值:** `false` </APIItem> </APIOptions> </API>

工具函数

getCommentCount

获取评论节点中非草稿评论的数量。

<API name="getCommentCount"> <APIParameters> <APIItem name="node" type="TCommentText"> 评论节点。 </APIItem> </APIParameters> <APIReturns type="number">评论数量。</APIReturns> </API>

getCommentKey

根据提供的 ID 生成评论键。

<API name="getCommentKey"> <APIParameters> <APIItem name="id" type="string"> 评论的 ID。 </APIItem> </APIParameters> <APIReturns type="string">生成的评论键。</APIReturns> </API>

getCommentKeyId

从评论键中提取评论 ID。

<API name="getCommentKeyId"> <APIParameters> <APIItem name="key" type="string"> 评论键。 </APIItem> </APIParameters> <APIReturns type="string">提取的评论 ID。</APIReturns> </API>

getCommentKeys

返回给定节点中存在的评论键数组。

<API name="getCommentKeys"> <APIParameters> <APIItem name="node" type="TCommentText"> 要检查评论键的节点。 </APIItem> </APIParameters> <APIReturns type="string[]">评论键数组。</APIReturns> </API>

getDraftCommentKey

获取用于草稿评论的键。

<API name="getDraftCommentKey"> <APIReturns type="string">草稿评论键。</APIReturns> </API>

isCommentKey

检查给定的键是否是评论键。

<API name="isCommentKey"> <APIParameters> <APIItem name="key" type="string"> 要检查的键。 </APIItem> </APIParameters> <APIReturns type="boolean">是否是评论键。</APIReturns> </API>

isCommentNodeById

检查给定节点是否是具有指定 ID 的评论。

<API name="isCommentNodeById"> <APIParameters> <APIItem name="node" type="TNode"> 要检查的节点。 </APIItem> <APIItem name="id" type="string"> 评论的 ID。 </APIItem> </APIParameters> <APIReturns type="boolean"> 节点是否是具有指定 ID 的评论。 </APIReturns> </API>

类型

TCommentText

可以包含评论的文本节点。

<API name="TCommentText"> <APIAttributes> <APIItem name="comment" type="boolean" optional> 此文本节点是否包含评论。 </APIItem> <APIItem name="comment_<id>" type="boolean" optional> 按评论 ID 键入的评论数据。一个文本节点中可以存在多个评论。 </APIItem> </APIAttributes> </API>