Archify Reading Depth 实现解析：用 MAP / READ / FULL 三档缩放在不新增任何控件的前提下提升图表可读性
【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify
本篇技术文章聚焦 Archify（archify仓库内以 docs/research-visual-evolution-round-23.md 为核心的 Visual Evolution Round 23）引入的Reading Depth（阅读深度）机制：它把"缩放"从单纯放大画面的数字，变成一种分阶段揭示信息的状态描述。读完本文，你将理解 Archify 如何在零新增工具栏按钮、零新增 Schema 字段的前提下，通过渲染器声明的data-detail角色与共享查看器的MAP / READ / FULL三档映射，让结构、关系与细节按需呈现，并通过prefers-reduced-motion、打印与独立 SVG 导出等边界保证完整保真。
问题背景：同时竞争的信息密度
Round 22 解决了 Archify 丰富查看器操作的可发现性（discoverability）。但下一个问题不是缺少某个操作，而是同时存在的信息密度（simultaneous information density）：在整系统视图（whole-system view）下，每个节点的子标签（sublabel）、关系标签（relationship label）、标签（tag）、分类（classification）与注释（annotation）全部在同一时刻竞争视觉注意力，即便其中一部分文字小到毫无用处。此时放大只是在放大同一张拥挤的画面，而不是在**有意的阶段（deliberate stages）**中逐步揭示含义。
因此 Round 23 的目标非常克制：让现有图表更容易阅读，而不新增任何工具栏按钮、面板、查询语言或图模型。这正是 Reading Depth 与其他"锦上添花"功能最大的区别——它是纯查看器层面的层级细节渲染（level-of-detail）方案。
行业参考：从大型图可视化库借鉴可读性，而非渲染栈
研究文档考察了四个成熟的图可视化方案，提炼出对 Archify 有迁移价值的原则：
| 参考来源 | 核心教训 | 对 Archify 的迁移价值 |
|---|---|---|
| yFiles 特性指南（level-of-detail 渲染） | 将"概览-细节"渲染视为一等图能力：粗糙的概览可在读者放大时变得更细致 | 分层揭示细节是合理的图交互模式，而非妥协方案 |
| yFiles 大型图性能指南 | 小到无法阅读的标签在低缩放时无需显示；边标签制造大量视觉噪声；高缩放层级可恢复更丰富的样式 | 可读性值得专门设计；但 Archify 不需要 yFiles 的渲染或性能栈 |
Cytoscape.js 官方文档（min-zoomed-font-size） | 标签在物理上不可读时保持缺席，用户放大后才出现；边标签在概览中昂贵且通常不必要 | 印证"按缩放揭示标签"的方向 |
| Sigma.js 设置（rendered-size threshold + 密度标签剔除） | 暴露渲染尺寸阈值与基于密度的标签剔除 | Archify 图更小且确定性更强，可用显式的作者细节层级取代概率密度算法 |
| G6 的 FixElementSize 行为 | 监听视口变化，在缩放时保持标签与线宽可读 | 缩放控件应描述阅读状态（reading state），而非仅仅报告一个数字 |
研究文档明确强调：这些参考的可迁移价值是readability（可读性），而不是 yFiles、Cytoscape.js、Sigma.js 或 G6 的渲染器与性能技术栈。
被推迟的候选：Semantic Lens
平行竞品扫描同时识别出一个有价值的后续功能：Semantic Lens——一个基于现有data-node-kind值的交互式分类图例，可聚焦某一语义类型，或精确对比两类之间的有向跨类计数。其参考来源是 G6 的 Legend 插件、Cytoscape.js 的选择器与集合、以及 Linkurious 的过滤面板。
但 Semantic Lens被刻意推迟：它需要新增LENS控件、持久面板、URL 状态，以及在 Diagram Guide 刚解决控件可发现性问题之后又引入另一条交互仲裁路径。而 Reading Depth 不需要新增任何操作面就能改进所有现有操作。研究结论是：当"对比证据"的价值超过其 UI 成本时，Lens 仍是一个好的未来候选。
借 / 跳过决策：六条原则与明确的边界
Borrow now（立即采纳）
- 定义确定性的、由渲染器拥有的细节角色（detail roles），而非在运行时根据字体大小猜测；
- 在整系统视图中保持结构与节点主标签可见；
- 在第一个缩放阈值恢复节点上下文（context）与关系标签；
- 在第二个缩放阈值恢复标签（tag）、步骤号（step number）、分类（classification）与注释（note）；
- 让更强的语义意图——focus、Intent Trace、Route Probe、Story Trail、Relationship Preview——立即只揭示其精确匹配的细节；
- 在现有控件中命名缩放状态，使行为可读：
MAP、READ、FULL。
Skip（明确不做）
- 不做标签密度启发式、碰撞引擎、Canvas/WebGL 渲染器、图存储、运行时依赖、用户可配置阈值面板；
- 不改 Schema、不加 JSON IR 字段：渲染器已经知道哪段文本是主标签、上下文、关系标签或精细注释；
- 不删除元素、不变更几何：隐藏的细节仍留在 DOM 中，可访问的 native title 与 Semantic Passport 保持完整，所有作者坐标固定不变；
- 不产生不完整的打印或导出：这些表面必须始终包含完整图表，独立于当前查看器缩放。
Archify 实现：渲染器声明角色，查看器统一映射
1. 渲染器侧：两个显式查看器角色 + 一个锚点
每个类型化渲染器为文本元素发出两个显式角色：
data-detail="context"：节点子标签与关系标签；data-detail="fine"：标签、步骤号、分类与注释。
主标签保持未分类（unclassified）且始终可见。当节点带有上下文子标签时，其主标签会被标记为细节锚点data-detail-anchor；在 MAP 模式下，该标签会向视觉中心平移 8 个 SVG 单位（源码实现为transform: translateY(8px)，配合transform-box: fill-box; transform-origin: center），以补偿其下方子标签缺席造成的视觉重心偏移。
这一模式在全部五个类型化渲染器中保持一致：
- 工作流：archify/renderers/workflow/workflow-compiler.mjs 中，
sublabel输出为data-detail="context"，tag输出为data-detail="fine"，主标签在存在子标签时附加data-detail-anchor，边标签组为data-detail="context"； - 架构图：archify/renderers/architecture/render-architecture.mjs；
- 数据流：archify/renderers/dataflow/render-dataflow.mjs（额外把流的
classification输出为data-detail="fine"）； - 生命周期：archify/renderers/lifecycle/render-lifecycle.mjs（
step号输出为data-detail="fine"，迁移note亦为data-detail="fine"）； - 时序图：archify/renderers/sequence/render-sequence.mjs（消息
note为data-detail="fine"）。
2. 查看器侧：三档稳定映射
共享查看器（archify/assets/template.html）把缩放状态映射为三个稳定层级：
| 层级 | 触发条件 | 可见信息 |
|---|---|---|
MAP | 100% | 结构、车道/区域/阶段、节点、主标签 |
READ | 125%–150% | MAP 之外，再加节点上下文与关系标签 |
FULL | 175%+ | 全部作者文本，包括精细注释 |
查看器核心逻辑是模板中的detailLevel()函数（archify/assets/template.html#L11370-L11403）：
function detailLevel() { if (state.mode === 'semantic') return 'full'; // Semantic Camera 始终取 FULL if (state.scale >= 1.75) return 'full'; // 175% 及以上 if (state.scale >= 1) return 'read'; // 100% 以上 return 'map'; // 概览 }随后renderControls()把计算出的层级同时写回两处：resetBtn.setAttribute('data-detail-level', detail)与container.setAttribute('data-detail-level', detail)，后者驱动整份 CSS 规则。缩放百分比与层级名称一起展示在复位控件上：MAP 100%、READ 125%等（文案由 archify/renderers/shared/i18n.mjs#L531-L537 提供中英双语，例如 "Zoom in to reveal relationship labels and node context" / "放大以显示关系标签和节点上下文"）。
3. CSS 层：纯 opacity + 平移，绝不移动几何
Reading Depth 的样式块（archify/assets/template.html#L4004-L4022）是整个机制最精妙的部分：
svg [data-detail] { transition: opacity 160ms ease; } svg [data-detail-anchor] { transform-box: fill-box; transform-origin: center; transition: transform 160ms ease; } .diagram-container[data-detail-level="map"] svg [data-detail="context"], .diagram-container[data-detail-level="map"] svg [data-detail="fine"], .diagram-container[data-detail-level="read"] svg [data-detail="fine"] { opacity: 0; pointer-events: none; } .diagram-container[data-detail-level="map"] svg [data-detail-anchor] { transform: translateY(8px); }要点：
- MAP 隐藏
context与fine，READ 只隐藏fine，FULL 全部可见； - 隐藏时同时置
pointer-events: none，避免不可见文本拦截点击与悬停； - 过渡仅涉及opacity与主标签的8 单位平移，从不移动节点、边、路由或边界，因此不会与既有布局/动画系统产生几何冲突。
4. 语义意图优先：精确揭示，而非整体切换
更强的语义意图（focus、Intent Trace、Route Probe、Story Trail、Relationship Preview、Semantic Lens 的预览态等）拥有比全局缩放层级更高的优先级：它们通过svg[data-intent-active]这类状态选择器，把恰好匹配的元素从隐藏状态拉回可见（archify/assets/template.html#L4024-L4055）：
svg[data-focus-active] [data-focus-match][data-detail], svg[data-intent-trace-active] [data-intent-trace-match][data-detail], svg[data-route-active] [data-route-match][data-detail], svg[data-story-active] [data-story-step][data-detail], svg[data-relationship-preview-active] [data-relationship-preview][data-detail], svg [data-node-id]:hover [data-detail], svg [data-node-id]:focus-visible [data-detail] { opacity: 1; pointer-events: auto; } /* 对应的锚点复位 */ svg[data-focus-active] [data-focus-match] [data-detail-anchor], svg [data-node-id]:hover [data-detail-anchor], svg [data-node-id]:focus-visible [data-detail-anchor] { transform: none; }这意味着：当全局处于 MAP/READ 时，聚焦某个节点、追踪一条意图或悬停一个节点，只有精确匹配的细节被立即揭示，图的其余部分仍停留在当前全局层级。同时:hover与:focus-visible保证了键盘可达性与鼠标可用性并重。
Semantic Camera 则始终选择 FULL：detailLevel()第一行if (state.mode === 'semantic') return 'full'确保即使语义相机在拟合邻域时实际缩放低于 175%，被语义相机锁定的区域也永远展示完整细节——这正是"缩放控件描述阅读状态，而非仅仅报告数字"的落地体现。
5. 运动安全：prefers-reduced-motion
160ms 的 opacity / transform 过渡对prefers-reduced-motion: reduce的用户完全禁用（模板中对应媒体查询直接取消[data-detail]与[data-detail-anchor]的过渡），html[data-motion="still"]状态下同样静态呈现，尊重系统级动效偏好。
6. 打印与导出：永远完整
Reading Depth 是查看器专属层，绝不污染任何输出表面：
- 打印：
@media print强制svg [data-detail] { opacity: 1 !important }，并复位data-detail-anchor的 transform，打印结果始终包含完整图表； - 独立 SVG 导出：序列化前先克隆 DOM，再对克隆结果统一执行
removeAttribute('data-detail')与removeAttribute('data-detail-anchor')（archify/assets/template.html#L5999-L6001），因此导出产物包含完整图表且不含任何当前阅读深度状态——没有data-detail-level、没有data-detail角色残留。
测试验证：semantic-zoom.test.mjs
archify/test/semantic-zoom.test.mjs 用四个测试把上述承诺固化为回归防线，覆盖全部五种图表类型（architecture、workflow、sequence、dataflow、lifecycle）：
- 所有类型化渲染器都发出显式语义：每种模式渲染的 HTML 都必须同时包含
data-detail="context"、data-detail="fine"、data-detail-anchor，且主标签（t-primary）不得携带任何data-detail角色；容器默认带data-detail-level="read"； - 确定性阈值：断言
detailLevel()中存在semantic → 'full'、scale >= 1.75 → 'full'、scale >= 1 → 'read'、否则'map'的分支，且控件文案包含三档提示； - 概览安静、语义优先：断言 MAP 隐藏 context 与 fine、READ 隐藏 fine 的 CSS 规则存在，且 focus / intent-trace / route / story / relationship-preview 各自的
[data-detail]揭示规则齐备； - 动效安全与完整保真：断言 160ms 过渡、打印
opacity: 1 !important、prefers-reduced-motion禁用过渡、导出克隆移除data-detail与data-detail-anchor属性、导出 SVG 中不含data-detail-level。
这些测试同时印证了研究文档"无新 Schema 字段"的承诺：data-detail是渲染期属性而非 JSON IR 字段，五种渲染器在渲染管线末端即可产出，无需改动任何输入契约。
浏览器实测证据
研究文档在生成的Agent Tool Call workflow上记录了完整的浏览器验证序列：
- MAP：报出
MAP 100%；context 与 fine 的 computed opacity 均为0，主标签居中，控制台干净无报错； - READ：缩进一档报出
READ 125%；context opacity 变为1，fine 仍为0，主标签锚点回到作者编写位置； - FULL：再缩进两档报出
FULL 175%；两个细节层级全部可见； - 语义相机：重置后聚焦 Agent Planner，Semantic Camera 以
AUTO 132%激活，自动选择 FULL，并显示其子标签、tag、关系标签与 Semantic Passport，全程无控制台错误。
这条序列直观展示了三档状态的完整闭环：概览只留结构与主标签 → 放大还原上下文与关系 → 再放大补齐全部精细注释 → 语义聚焦则无视全局层级直接给足细节。
结语：把缩放从数字变成阅读状态
Reading Depth 是 Archify 查看器一次典型的"以零新增操作面换取系统性可读性提升"的设计：渲染器通过data-detail="context"、data-detail="fine"与data-detail-anchor三个显式角色声明细节归属，共享查看器以MAP / READ / FULL三档阈值统一映射（archify/assets/template.html#L11370-L11403），CSS 仅用 opacity 与 8 单位平移完成过渡，语义意图与:hover/:focus-visible则提供精确到元素的即时揭示。打印、独立 SVG 导出、prefers-reduced-motion与五渲染器回归测试共同保证了它"只在查看器内生效、永不伤害任何输出表面"。对使用 Archify 生成自包含 HTML 图表的读者而言，这意味着：同一份图表既能作为整页概览被快速扫读，也能在放大后逐层展开到全量注释，而图表本身与导出产物始终保持完整与干净。
【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
