velt-area-best-practices

Velt Area Comments 最佳实践是一份实现指南，针对 Velt 的矩形区域批注（Area Comments）功能：用户可以在页面上画出一个矩形框，并把一条评论线程附加到该区域上。

用途与定位

Area 建立在 Comments 功能之上，并不是一个独立组件，而是 <VeltComments> 的一种模式。该模式默认启用，可通过属性或运行时方法切换。因此相关的 SDK 句柄是 client.getCommentElement()（评论句柄），而不是假设中的 getAreaElement()。三个 Area 专属的公开元素（<velt-area-pin-portal>、<velt-area-tool>、<velt-area-container>）会在区域模式启用时由评论运行时自动渲染。

适用时机

在以下场景可参考这些指南：在应用中开启或关闭区域评论（默认开启）；在 <VeltComments> 上的声明式 areaComment 属性与命令式 commentElement.enableAreaComment() / disableAreaComment() API 之间做选择；通过线框表面构建自定义区域图钉（目前只有 <velt-area-pin-portal-wireframe> 会注册，工具与容器尚未注册）；读取 componentConfig.areaPinAnnotation、componentConfig.selected、componentConfig.isResizing、componentConfig.hideAreaAnnotation 或几何 / 缩放偏移变量；针对 AreaAnnotation、AreaProperty、AreaTargetAnnotation 或 AreaMetadata 进行类型标注；理解 AreaAnnotation 如何通过 targetAnnotations[] 关联回它所限定的评论线程。

规则分类与优先级

API（HIGH，前缀 api-）：api-toggle-area-comments —— 介绍 <VeltComments areaComment={false}> 属性与 commentElement.enableAreaComment() / disableAreaComment() 运行时方法；三个公开 Area 原语（tool / pin-portal / container）；以及“没有独立组件”的定位。
线框变量（MEDIUM，前缀 wireframe-variables-）：wireframe-variables-area —— 介绍 <velt-area-pin-portal-wireframe>（目前唯一注册了线框的 Area 原语）及其 componentConfig.* 参考项（areaPinAnnotation、selected、isResizing、hideAreaAnnotation、areaProperties、resizingOffset、offsetTop/Left、areaAnnotationColor、commentPinAnnotation 关联）。
类型（MEDIUM，前缀 types-）：types-area-annotation —— 介绍 AreaAnnotation 结构及其评论关联字段 targetAnnotations[]（AreaTargetAnnotation[]）；配套的 AreaProperty（几何）与 AreaMetadata（开放扩展字段）；以及区域图钉如何附加到评论线程。

使用方式

可阅读各规则文件获取详细说明与代码示例：rules/shared/api/api-toggle-area-comments.md、rules/shared/wireframe-variables/wireframe-variables-area.md、rules/shared/types/types-area-annotation.md。每条规则包含：为什么重要、React / Next.js 及其他框架的代码示例、常见陷阱、验证清单、指向官方文档的来源指引。

技能介绍