HTML 原型标注

解决什么问题

给 HTML 原型写标注（数据来源、联动规则、校验逻辑）时，常见做法是截图画红框，再附一份 Word 文档。这类产物和原型是分离的，开发要来回对照，需求一改就得重新标注。

本技能直接输出一份带标注层的 HTML 文件：元素旁出现编号角标，点击弹出注释卡片；标注数据写在 HTML 内部，随文件分发，谁打开都看到同一份说明。

核心能力

• 独立标注层：CSS 与 JS 全部带 anno- 前缀并包裹在 IIFE 中，对原型唯一改动是给目标元素加 data-anno 属性，不碰原有结构、样式与脚本。
• 四类标注内容：数据规范（来源、公式、初始值）、交互表现（联动、显隐、自动带出）、处理逻辑（校验时机、提示文案、只读生成规则）、备注。无内容的类别整体省略。
• 上下文感知：多页签、多弹窗页面为每个上下文生成声明式可见性规则，支持 hasClass、属性判断、元素存在三种方式，只显示当前活跃上下文的角标。
• 行内编辑与持久化：编辑写回标注数据并存进 localStorage，刷新后恢复；右上角绿色按钮把最终结果导回 HTML 文件。
• 两种标注模式：仅标注重点 只标页面看不出来的联动、计算与数据来源；应标尽标 覆盖所有有业务含义的元素。两者都遵循"不重复页面已表达的信息"。

三个致命陷阱

文档反复强调、实际失败率最高的点：

• </script> 字符串截断脚本块：即使写在注释、字符串或正则里，解析器也会立即关闭脚本块，角标、开关、卡片全部失效。必须转义为 <\/script>。
• 标注数据写成二维数组：[[{...}, {...}]] 会让所有角标定位失败，必须是一维数组 [{...}, {...}]，不要依赖模板的降维容错。
• 对象括号未闭合：groups 的值本身是对象，容易漏掉闭合 } 或在末尾多加逗号。

适用边界

• 标注层不是需求管理工具，不做版本对比、权限或评论。
• 静态原型最省事；依赖运行时 DOM 的框架页面，可见性规则需按真实 class 和属性单独配置。
• 重复表格行只标表头一行，纯静态文案与装饰元素不标。