Back to Details

velt-comments-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Velt Comments Best Practices

Velt Comments 最佳实践

Comprehensive implementation guide for Velt's collaborative comments feature in React and Next.js applications. Contains 36 rules across 9 categories, prioritized by impact to guide automated code generation and integration patterns.
本文是针对React和Next.js应用中Velt协作评论功能的全面实现指南。包含9个类别共36条规则，按影响优先级排序，可指导自动化代码生成与集成模式。

When to Apply

适用场景

Reference these guidelines when:
  • Adding collaborative commenting to a React/Next.js application
  • Implementing any Velt comment mode (Freestyle, Popover, Stream, Text, Page, Inline)
  • Integrating comments with rich text editors (TipTap, SlateJS, Lexical)
  • Adding comments to media players (Video, Lottie animations)
  • Adding comments to charts (Highcharts, ChartJS, Nivo)
  • Building custom comment interfaces with standalone components
在以下场景中可参考这些指南：
  • 为React/Next.js应用添加协作评论功能
  • 实现任意Velt评论模式（自由样式、弹出框、信息流、文本、页面、内联）
  • 集成富文本编辑器评论（TipTap、SlateJS、Lexical）
  • 为媒体播放器添加评论（视频、Lottie动画）
  • 为图表添加评论（Highcharts、ChartJS、Nivo）
  • 使用独立组件构建自定义评论界面

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryImpactPrefix
1Core SetupCRITICAL
core-
2Comment ModesHIGH
mode-
3Standalone ComponentsMEDIUM-HIGH
standalone-
4Comment SurfacesMEDIUM-HIGH
surface-
5UI CustomizationMEDIUM
ui-
6Data ModelMEDIUM
data-
7Debugging & TestingLOW-MEDIUM
debug-
8Moderation & PermissionsLOW
permissions-
9Attachments & ReactionsMEDIUM
attach-
优先级类别影响程度前缀
1核心配置关键
core-
2评论模式高
mode-
3独立组件中高
standalone-
4评论界面载体中高
surface-
5UI定制中
ui-
6数据模型中
data-
7调试与测试中低
debug-
8审核与权限低
permissions-
9附件与互动中
attach-

Quick Reference

快速参考

1. Core Setup (CRITICAL)

1. 核心配置（关键）

  • core-provider-setup
    - Initialize VeltProvider with API key
  • core-authentication
    - Authenticate users before using comments
  • core-document-setup
    - Configure document context for comments
  • core-provider-setup
    - 使用API密钥初始化VeltProvider
  • core-authentication
    - 使用评论功能前先完成用户认证
  • core-document-setup
    - 配置评论的文档上下文

2. Comment Modes (HIGH)

2. 评论模式（高）

  • mode-freestyle
    - Pin comments anywhere on page
  • mode-popover
    - Google Sheets-style cell comments
  • mode-stream
    - Google Docs-style sidebar stream
  • mode-text
    - Text highlight comments
  • mode-page
    - Page-level comments via sidebar
  • mode-inline-comments
    - Traditional inline thread style
  • mode-tiptap
    - TipTap editor integration
  • mode-slatejs
    - SlateJS editor integration
  • mode-lexical
    - Lexical editor integration
  • mode-canvas
    - Canvas/drawing comments
  • mode-lottie-player
    - Lottie animation frame comments
  • mode-video-player-prebuilt
    - Velt prebuilt video player
  • mode-video-player-custom
    - Custom video player integration
  • mode-chart-highcharts
    - Highcharts data point comments
  • mode-chart-chartjs
    - ChartJS data point comments
  • mode-chart-nivo
    - Nivo charts data point comments
  • mode-chart-custom
    - Custom chart integration
  • mode-freestyle
    - 在页面任意位置固定评论
  • mode-popover
    - 类似Google Sheets的单元格评论
  • mode-stream
    - 类似Google Docs的侧边栏信息流评论
  • mode-text
    - 文本高亮评论
  • mode-page
    - 通过侧边栏添加页面级评论
  • mode-inline-comments
    - 传统内联线程式评论
  • mode-tiptap
    - TipTap编辑器集成
  • mode-slatejs
    - SlateJS编辑器集成
  • mode-lexical
    - Lexical编辑器集成
  • mode-canvas
    - 画布/绘图评论
  • mode-lottie-player
    - Lottie动画帧评论
  • mode-video-player-prebuilt
    - Velt预构建视频播放器
  • mode-video-player-custom
    - 自定义视频播放器集成
  • mode-chart-highcharts
    - Highcharts数据点评论
  • mode-chart-chartjs
    - ChartJS数据点评论
  • mode-chart-nivo
    - Nivo图表数据点评论
  • mode-chart-custom
    - 自定义图表集成

3. Standalone Components (MEDIUM-HIGH)

3. 独立组件（中高）

  • standalone-comment-pin
    - Manual comment pin positioning
  • standalone-comment-thread
    - Render comment threads
  • standalone-comment-composer
    - Add comments programmatically
  • standalone-comment-pin
    - 手动定位固定评论
  • standalone-comment-thread
    - 渲染评论线程
  • standalone-comment-composer
    - 以编程方式添加评论

4. Comment Surfaces (MEDIUM-HIGH)

4. 评论界面载体（中高）

  • surface-sidebar
    - Comments sidebar component
  • surface-sidebar-button
    - Toggle sidebar button
  • surface-sidebar
    - 评论侧边栏组件
  • surface-sidebar-button
    - 侧边栏切换按钮

5. UI Customization (MEDIUM)

5. UI定制（中）

  • ui-comment-dialog
    - Customize comment dialog
  • ui-comment-bubble
    - Customize comment bubble
  • ui-wireframes
    - Use wireframe components
  • ui-comment-dialog
    - 定制评论对话框
  • ui-comment-bubble
    - 定制评论气泡
  • ui-wireframes
    - 使用线框组件

6. Data Model (MEDIUM)

6. 数据模型（中）

  • data-context-metadata
    - Add custom metadata
  • data-comment-annotations
    - Work with annotations
  • data-filtering-grouping
    - Filter and group comments
  • data-context-metadata
    - 添加自定义元数据
  • data-comment-annotations
    - 处理注释内容
  • data-filtering-grouping
    - 过滤和分组评论

7. Debugging & Testing (LOW-MEDIUM)

7. 调试与测试（中低）

  • debug-common-issues
    - Common issues and solutions
  • debug-verification
    - Verification checklist
  • debug-common-issues
    - 常见问题及解决方案
  • debug-verification
    - 验证检查清单

8. Moderation & Permissions (LOW)

8. 审核与权限（低）

  • permissions-private-mode
    - Control global comment visibility with enablePrivateMode/disablePrivateMode and update per-annotation visibility with updateVisibility
  • permissions-comment-saved-event
    - Subscribe to the commentSaved event for reliable post-persist side-effects (webhooks, analytics, external sync)
  • permissions-private-mode
    - 使用enablePrivateMode/disablePrivateMode控制全局评论可见性，通过updateVisibility更新单个注释的可见性
  • permissions-comment-saved-event
    - 订阅commentSaved事件以实现可靠的持久化后副作用（Webhooks、分析、外部同步）

9. Attachments & Reactions (MEDIUM)

9. 附件与互动（中）

  • attach-download-control
    - Control attachment download behavior and intercept clicks
  • attach-download-control
    - 控制附件下载行为并拦截点击事件

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:
rules/shared/core/core-provider-setup.md
rules/shared/mode/mode-popover.md
Each rule file contains:
  • Brief explanation of why it matters
  • Incorrect code example with explanation
  • Correct code example with explanation
  • Source pointers to official documentation
阅读单个规则文件获取详细说明及代码示例：
rules/shared/core/core-provider-setup.md
rules/shared/mode/mode-popover.md
每个规则文件包含：
  • 规则重要性的简要说明
  • 错误代码示例及问题解释
  • 正确代码示例及解释
  • 官方文档的参考链接

Compiled Documents

编译文档

  • AGENTS.md
    — Compressed index of all rules with file paths (start here)
  • AGENTS.full.md
    — Full verbose guide with all rules expanded inline
  • AGENTS.md
    — 包含所有规则及文件路径的压缩索引（从这里开始）
  • AGENTS.full.md
    — 包含所有规则详细内容的完整指南