Archify 命名章节导轨Named Chapter Rail设计剖析让 guided views 在 0/N 之前即可被扫描、计数与直达【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify导读本文围绕 Archify 可视化查看器的「命名章节导轨Named Chapter Rail」展开讲解这一功能如何解决 guided views 在未选中章节时的可发现性缺口读者在0 / N状态下看不到各章节的编写者命名、也看不到每个章节的规模。全文以项目内研究文档 docs/research-visual-evolution-round-28.md 为主体骨架结合 archify/assets/template.html 中Archify.guidedViews的真实实现与 archify/test/chapter-rail.test.mjs 的契约测试讲清该功能的产品契约、6 个外部参照源的借/弃结论、32 条验收标准以及它在源码中如何以「零 schema 变更」的方式落地。读完后你将能理解 Archify 如何在保持单一状态所有者activeIndex、不新增动效、不改导出边界的前提下把章节名称、步数、键盘漫游、移动端触摸与辅助技术语义完整地集成进现有 Guided Views 面板。一、产品问题0/N 状态下的可发现性缺口Archify 已经具备完整的 guided views 能力编译编写者声明的guidedViews、渲染当前章节的 label 与 note、支持 Previous / Next / Play / Show all、提供[与]快捷键、聚焦当前章节的focus数组并为当前章节逐节点绘制故事轨迹story trail。剩余的缺口出现在章节被选中之前在0 / N状态下读者知道「存在 guided views」却无法一眼扫描这些视图的编写者命名也无法比较它们的规模只能逐个点击翻阅。因此本轮研究的产品问题被刻意限定为能否在不创建 dashboard、不引入第二套故事状态机、不增加任何新的环境动效的前提下让全部编写者命名的章节在现有 Guided Views 界面上一目了然、可计数、可直接选中研究结论为「可以」。方案是在现有 Guided Views 面板中加入一个紧凑的、由查看器自身拥有的命名章节导轨Named Chapter Rail——在0 / N时立即渲染展示每个编写者命名的 label以及由该视图focus数组直接推导出的步数激活行为则完全委托给现有activate(index)路径。需要明确边界这是可发现性与导航改进不是新的 guided view 模型、不是恢复restore系统、不是轮播自动播放模式也不是导出功能。二、现有架构证据导轨所需的原料已经全部存在2.1 编写者模型已包含导轨所需的全部字段Archify.guidedViewsarchify/assets/template.html把archify-guided-views-data载荷解析为有序的views数组。每条视图已经具备稳定的id用于#view深链编写者声明的label与可选的note有序的focus数组既定义高亮节点也定义当前章节故事轨迹的序列。导轨必须直接读取这些字段不得为显示顺序、计数、激活态、状态、图标、时长或视口新增任何 schema 属性。这一点在源码中得到印证buildChapterIndex()遍历views.forEach(...)直接读取view.id、view.label、view.note、view.focus.length没有任何新增字段见 archify/assets/template.html。2.2activeIndex是唯一的章节所有者模块初始化时activeIndex -1对应 Show all 状态只通过activate、activateById、showAll或 hash 恢复来改变可见计数、label、note、focus、URL、视口揭示viewport reveal、播放与分享提示均由该值派生。源码可见showAll()把activeIndex -1并重渲染archify/assets/template.htmlactivate(index, options)校验边界后写入activeIndex index随后统一走renderStoryTrail、beginHandoff、renderarchify/assets/template.htmlactivateById(id)只是views.findIndex(...)后转调activatearchify/assets/template.html。因此导轨必须从activeIndex渲染并调用现有所有者禁止引入selectedChapter、railIndex、DOM 持有的选中态或第二个 URL 解析器。漫游键盘焦点是「瞬时焦点」不是章节选中。测试中也显式断言doesNotMatch(/selectedChapter|visitedChapters|completedChapters/)确认源码不存在重复选中状态archify/test/chapter-rail.test.mjs。2.3 章节导轨与节点轨迹是两个层级现有guided-view-trail只为已选中的视图创建展示view.focus中的有序节点。新导轨位于其上一级章节导轨chapter rail选择要查看哪个编写者视图故事轨迹story trail当前视图由哪些 focus 节点组成。章节激活时两者应同时可见。用章节按钮替换节点轨迹会丢弃有价值的关系证据把每个章节下的节点步骤全部嵌套展开则会变成 dashboard。有界设计就是「一行浅层章节行 现有激活章节轨迹」。三、6 个参照源的借/弃分析研究文档对 6 个外部参照源做了固定版本的对比分析核心原则是「取其有界性弃其越界设计」。3.1 Fireworks Tech Graph保持查看器有界、导出干净参照源固定为yizhiyanhua-ai/fireworks-tech-graph50c819d。其交互式查看器暴露一个标题、一组聚焦的原生控件、可聚焦的舞台和aria-live缩放状态而不是一堆次要面板的 dashboard查看器持有唯一的可变的 pan/zoom 对象与重置路径导出序列化 SVG 而非周边的视口变换浏览状态不会变成图表内容在请求 reduced motion 时移除 CSS 过渡。借用单一查看器所有者、原生控件、干净的产物边界、小表面积。不借用缺失编写者章节发现能力、以及把「实时 SVG 序列化」当作 Archify 导出实现——Archify 的 canonical-clone 清理更强且必须保持不变。3.2 D2命名视图需要明确语义与密度护栏D2 给编写者的板子三种不同含义layers相互独立、scenarios从基础视图继承、steps从上一个步骤继承其内部链接与可点击的祖先导航让命名板子直接可达而不是强迫线性翻阅。D2 的导出指南同时指出动画 SVG 只适合少量 Steps/Scenarios板子太多会让查看者困惑或等待整个循环更大的组合应使用多个 SVG、PDF 页或 PowerPoint 幻灯片。借用让编写者命名直接可扫描、保持原有顺序、保留回到根 / Show all 状态的明显路径。不借用嵌套板子、继承语法、每章节重新布局、动画循环。导轨应保持为「编译后图之上的单行导航」窄屏上滚动而非换行成多行控件墙。3.3 Flourish Stories保存的视图通过命名、进度与直接控件变得可理解Flourish 把地图位置、菜单选择等交互保存进每个故事幻灯片而底层可视化数据与设置的更新继续流入所有派生幻灯片其播放器提供前进/后退导航、编写者字幕、过渡、网页嵌入与响应式桌面/平板/手机输出。默认故事导航包含原生 Previous/Next、当前/总数计数、字幕与进度条边界按钮在无意义时被禁用。借用编写者命名、直接选中、明确的当前/总进度、原生按钮与响应式处理。不借用通用匿名圆点、新的自动播放循环、附加在普通章节选中上的动画。Archify 已有刻意的 Play/Pause 所有权不应扩张。3.4 Mapbox Storytelling一个章节只应拥有一个连贯状态参照源固定为mapbox/storytelling04e6e37。每个章节记录拥有稳定 ID、可见标题、描述、位置与进入/退出效果渲染器把章节标题暴露为真正的标题而非藏在数字标记后面章节激活时由单个 handler 解析数组下标、标记激活并应用地图与图层状态退出 handler 移除激活所有权移动端规则加宽故事卡片并显式修复触摸滚动。该模板 README 还警告其全页滚动驱动界面在 iframe 中无法按预期工作。借用稳定编写者命名与单一下标拥有的激活章节。不借用滚动位置激活、隐藏触发章节、自动前进、环境旋转、全页布局。Archify 导轨必须通过显式按钮激活且不得改变现有 embed 边界。3.5 Cytoscape.js图、视口与导出是三个独立契约Cytoscape.js 通过cy.viewport()显式暴露视口状态通过cy.json()声明式保存/恢复图状态输入事件模型包含鼠标、触摸与捏合手势图片导出通过显式full选项区分当前视口与整图。借用把图选中、视口揭示与产物导出保持为独立职责。不借用本切片中的通用图状态快照或当前视口导出选项。当前 Archify 的activate(index)、Show all、canonical 导出与 embed 行为就是产品契约。3.6 WAI-ARIA 与 WCAG原生激活、有界焦点、无意外动效WAI-ARIA 轮播模式要求显式 Previous/Next 控件若存在自动旋转必须有可见的停止/开始控件且焦点进入或指针悬停时必须停止、不得未经显式请求重启。对「一次一个」的集合手动 Tabs 模式使用单个 Tab 停靠点、左右漫游、可选的 Home/End 边界、原生 Enter/Space 激活聚焦项toolbar 模式对分组控件遵循同样的单停靠点 方向键原则。由于视觉导轨是「图上的导航」而非一组 DOM 标签面板应使用带标签的 navigation/toolbar 组、真正的button元素并为选中章节使用aria-currentstep而不是在没有真实tabpanel关系时套用tablist语义。WCAG 要求交互触发的非必要动效必须可禁用持续超过 5 秒的自动移动内容需要暂停/停止/隐藏机制prefers-reduced-motion媒体特性传递「移除或替换非必要动效」的请求。借用真实按钮、单个漫游 Tab 停靠点、可见选中与显式播放。不借用仅因键盘焦点移动就自动激活——手动激活让读者能扫描长命名而不改变下方图表。四、推荐产品契约Recommended Product Contract4.1 结构与布局保留现有外层控件在「当前章节文案」与「激活节点轨迹」之间插入一行浅层章节导轨← 0 / 4 Explore this system → [01 Overview · 4 steps] [02 Trust boundary · 3] [03 Request path · 5] [04 Recovery · 3] Play story Show all章节激活时其现有 label、note、故事轨迹、Play/Pause、Previous、Next、[/]与 Show all 行为全部保持不变。导轨只是通往同一个activate(index)函数的额外直接路径。4.2 可见性与计数只要存在有效views就渲染导轨包括activeIndex -1、可见0 / N状态。保留源数组顺序不按字母或数量排序。每个view.label以可见文本展示不得用圆点、tooltip 或仅章节号替代名称。每个可见步数由view.focus.length推导不查询渲染后的 story-trail DOM、不数边、不重复steps字段。仅当当前数据契约允许时零步视图才保持「有名字但禁用/不可激活」导轨不得静默发明 focus 目标。4.3 选中与所有权每个章节项是原生 button数组下标是其稳定运行时映射。点击、触摸、原生 Enter 与原生 Space 都调用现有activate(index)路径。activeIndex仍是唯一选中章节状态选中样式、aria-current、计数、label、note、hash、focus 与故事轨迹都由它派生。Show all 继续调用现有showAll()路径并把导轨带回0 / N不销毁导轨。Previous、Next、[/]、hash 恢复与刻意的播放通过正常渲染路径更新同一个导轨没有导轨专属的选中事件去写图状态。不增加恢复栈现有 Guided Views 仲裁与 Show all 语义保持权威。4.4 键盘与辅助技术导轨是有可见标签的 navigation 或 toolbar 组。恰好一个可激活章节按钮tabindex0其余tabindex-1。左右方向键把焦点移到上一个/下一个可激活章节边界处有界它们不选中章节。Home/End 把焦点移到第一个/最后一个可激活章节它们不选中章节。Enter/Space 使用原生button激活不添加第二套合成键到点击处理器避免双重激活。选中通过 Previous、Next、直接激活、[/]、hash 恢复或播放改变时激活的导轨项获得aria-currentstep除非读者在导轨内操作否则不抢焦点。可见名称与计数构成可理解的可访问名例如Trust boundary, chapter 2 of 4, 3 steps, current。4.5 视觉语言与密度激活、过去与未来章节的提示在不依赖颜色的情况下仍然可区分激活更粗描边 CURRENT/当前标记过去勾选/完成标记 更安静的文字未来数字标记 常规描边。focus-visible必须与激活不同——读者可以键盘聚焦一个未来章节而当前章节仍保持选中。使用与现有查看器 token 一致的紧凑药丸/卡片不增加统计、缩略图、按类型图标、边数、完成百分比或第二个侧面板。保持单行桌面可显示全集或水平溢出窄屏必须滚动而不是换行成多行。4.6 移动端与触摸在现有窄断点下导轨水平可滚动支持触摸平移与滚动吸附scroll snapping。每个章节按钮至少 44 × 44 CSS 像素命中目标。直接触摸激活一次没有 hover-only 预览或「首次触摸变 hover」的陷阱。实际章节选中后用非动画/瞬时滚动把激活项居中到导轨仅因漫游焦点移动不得居中。导轨不得与底部控件重叠、不得制造页面级水平溢出、不得阻挡 SVG pan/zoom 手势。4.7 动效不动画章节按钮的进入、选中、完成、焦点、导轨滚动或 Show all。只保留现有刻意的 Play/Pause 进度动画与playing拥有的 story-beat 播放。手动点击/触摸/键盘选中保持静止。现有 reduced-motion 行为保持权威不新增计时器、过渡或 autoplay 分支。4.8 产物边界不需要 schema 或渲染器改动导轨由共享查看器中现有 guided-view JSON 派生。不为导轨新增或改动 canonical SVG 属性。不改Archify.exporter、导出清理、canonicality 回执、打印输出或图片尺寸。不改 embed 抑制或?play1分享播放语义。导轨保持为运行时 HTML遵守现有.guided-views/no-print边界它永远不会进入克隆后的 SVG 输出。五、源码级实现印证契约如何真实落地研究文档的契约并非停留在纸面——Archify.guidedViews模块在 archify/assets/template.html 中已完整实现archify/test/chapter-rail.test.mjs 用 4 组测试逐条验证。下面把契约与实现一一对应。5.1 构建buildChapterIndex()直接消费 views导轨由document.getElementById(guided-view-index)navaria-label来自 i18n 键viewer.guided.chapters与guided-view-chaptersol承载。buildChapterIndex()对每个 view 创建libutton classguided-view-chapterbutton.type button原生按钮语义data-guided-view-id view.id作为运行时稳定映射序号span classguided-view-chapter-index用(index 1 10 ? 0 : ) (index 1)补零aria-hiddentrue标题title.textContent view.label即编写者命名直接可见步数stops.textContent viewerCount(viewer.guided.chapter.stop, view.focus.length)即从focus.length推导计数初始tabindex首个0其余-1单 Tab 停靠点。见 archify/assets/template.html。5.2 同步syncChapterIndex()从 activeIndex 派生一切syncChapterIndex()在每次渲染时被调用render()内见 archify/assets/template.html是「单一状态所有者」原则的直接体现var current index activeIndex位置推导activeIndex 0 ? available : (current ? current : (index activeIndex ? before : after))写入data-chapter-position同时同步到li激活项aria-pressedtrue、aria-currentstep其余移除aria-current激活项展示步数文本并更新可访问名viewer.guided.chapter.current非激活项展示由chapterDeltastay/enter/leave 三段算出的增量摘要如2 1 −1并切换为viewer.guided.chapter.delta.*可访问名激活时centerChapterButton(chapterButtons[activeIndex])用behavior: auto非动画居中。见 archify/assets/template.html。注意契约允许的「过去/未来」视觉差异在实现中还扩展为对未来章节展示 stay/enter/leave 增量摘要——这是对「可扫描规模」的进一步深化依然没有新增状态变量。5.3 选中委托导轨按钮直接走 activate 路径chapterList的 click 委托chapterList.addEventListener(click, ...)里activateById(button.getAttribute(data-guided-view-id))即通过数组下标映射到现有activate所有者archify/assets/template.htmlEnter/Space 由原生button激活语义处理无合成 key-to-click 处理器与「不双重激活」契约一致Previous/Next、[/]、hash 恢复全部走既有路径prev/next的 click 直接activate(activeIndex ± 1)archify/assets/template.html全局 keydown 里]/[调activatearchify/assets/template.htmlsyncViewFromHash()通过activateById(initial, { updateUrl: false, restore: true })恢复并让syncChapterIndex()标记对应项为 currentarchify/assets/template.html。5.4 键盘漫游瞬时焦点不改变选中chapterList的 keydown 监听里ArrowRight / ArrowLeft / Home / End 只计算目标下标并调用focusChapterButton(target)后者更新tabindex分布、button.focus()并centerChapterButtonarchify/assets/template.html 与 L9347-L9356。漫游不触发激活与 WAI-ARIA toolbar 模式的单停靠点原则一致activeIndex不变因此测试断言「Left/Right rove focus without changing activeIndex」。5.5 动效、移动端、embed 与打印边界选中不带动画centerChapterButton使用behavior: auto无过渡prefers-reduced-motion: reduce时.guided-view-chapter { transition: none !important; }且模块内reducedMotion()守卫让scheduleStoryPlayback()直接返回 false——播放降级为静态路径移动端.guided-view-chapter { min-height: 2.75rem; }≈44px 命中目标、scroll-snap-type: x proximity、flex: 0 0 min(14rem, 78vw)保证单行滚动不换行embed 边界html[data-embedtrue] .guided-views { display: none !important; }导轨随面板整体抑制与?play1分享播放语义互不干扰打印边界.toolbar, .diagram-nav, .focus-chip, .guided-views, .archify-toast, .no-print { display: none !important; }导轨属于.guided-views/no-print运行时 HTML绝不进入 SVG 导出。5.6 一处超出原契约的深化hover/focus 章节预览实现还在原契约之上增加了showChapterPreview()/setChapterPreviewIntent()指针悬停或键盘聚焦仅(hover: hover)且非 touch可暂时在图上标出目标章节的 stay/enter/leave 角色同时chapterPreviewBlocked()在 playing、handoff、embed、print、route/lens/legend/relationship/intent-trace 激活时全部拦截focusin进导轨时若正在播放会pausePlayback()读者接管。这仍然遵守「手动点击才激活、预览不动效不写状态」的总原则——预览只改 SVG 上的data-chapter-preview-*属性不触碰activeIndex。六、借 / 弃矩阵Explicit Borrow / Skip Matrix参照源借用跳过Fireworks Tech Graph有界查看器控件单一所有者干净产物边界把匿名视口状态当故事live-SVG 导出改动D2编写者命名直接可达明显根路径密度克制嵌套板子新继承/schema动画板子循环Flourish Stories原生 Prev/Next可见计数/字幕/进度响应式导航匿名圆点新 autoplay/loop选中动画Mapbox Storytelling稳定章节 ID/命名单一下标拥有的激活态滚动驱动激活隐藏触发环境旋转Cytoscape.js图、视口与输出职责分离通用快照/恢复栈新当前视口导出WAI/WCAG原生激活漫游焦点无颜色状态显式播放焦点跟随选中意外或持续动效七、32 条验收标准从契约到可验证研究文档给出了完整的验收标准清单与 archify/test/chapter-rail.test.mjs 的断言一一呼应含有效 guided views 的文档每个视图渲染一个章节导轨项选中前、计数器显示0 / N时导轨可见每项可见地暴露编写者view.label每项暴露等于view.focus.length的步数导轨顺序与编译后views数组完全一致点击任一项通过现有activate(index)所有者恰好激活该下标粗指针上触摸任一项恰好激活一次聚焦项上原生 Enter 与 Space 恰好激活一次恰好一个合格项参与页面 Tab 序列左右方向键漫游焦点且不改变activeIndexHome/End 漫游到首/末合格项且不改变activeIndex直接导轨激活同步更新现有计数器、label、note、聚焦图、故事轨迹与#viewhashactiveIndex是唯一选中章节变量无重复导轨选中状态Previous/Next 通过现有渲染路径更新导轨激活态现有[/]快捷键更新同一激活态现有 hash 恢复把匹配的导轨项标记为 currentShow all 保持导轨可见、清除 current 状态、通过现有showAll()恢复0 / N激活项有aria-currentstep非激活项没有激活、过去、未来与键盘聚焦状态在不仅依赖颜色的情况下可区分手动章节选中无动画或计时器导轨旁唯一移动的进度仍是 Play/Pause 拥有的播放进度prefers-reduced-motion: reduce下导轨无动效、现有播放降级保持完整390 CSS 像素视口下导轨保持单行、可水平滚动、滚动吸附、每项至少 44×44 像素移动端选中章节居中激活项无页面水平溢出、不与底部控件重叠导轨不依赖 hover、不阻挡图触摸手势无 guided views 的文档渲染空导轨源码if (!views.length) return { count: 0, ... }直接短路archify/assets/template.html不引入渲染器、schema、校验器、fixture 模型或 guided-view JSON 形状改动canonical SVG 内容除无关既有生成改动外字节/结构等价导轨标记不进入 SVG 源SVG/图片导出与打印不含章节导轨 HTML 或运行时状态现有 embed 抑制与分享播放行为不变现有 Prev、Next、Play/Pause、Show all、故事轨迹、节点释放、presentation 与 URL 测试保持绿色新契约测试覆盖0 / N、命名/计数、激活委托、漫游焦点、无颜色状态、移动端几何、reduced motion 与产物边界。测试文件 archify/test/chapter-rail.test.mjs 的第 1 组测试直接对 5 种渲染模式architecture / workflow / sequence / dataflow / lifecycle见 archify/test/chapter-rail.test.mjs渲染 HTML 并断言导轨 nav/ol 结构、buildChapterIndex、views.forEach、补零序号、title.textContent view.label、viewerCount(viewer.guided.chapter.stop, view.focus.length)存在且 canonical SVG 中无guided-view-chapter/data-chapter-position第 2 组断言激活委托与aria-current管理、且无重复状态变量第 3 组断言键盘优先focusin 暂停播放、ArrowLeft/Right/Home/End、focusChapterButton、button.type button且无roletab/roletabpanel误用第 4 组断言位置样式、min-height: 2.75rem、scroll-snap-type: x proximity、flex: 0 0 min(14rem, 78vw)、behavior: auto、reduced-motion 过渡移除、embed 抑制与打印抑制。这些测试直接为上文 32 条验收标准中的第 1–30 条提供了可执行证据。八、决策与总结最终决策把Named Chapter Rail实现为Archify.guidedViews的一个浅层扩展。这里追求的「丰富」不是更多环境动画而是在承诺之前就让编写者已有的叙事结构变得可读读者能看见存在哪些故事、每个多长、直接跳到一个、知道自己在哪、并能回到整图。复用views、focus、activeIndex、activate、showAll、刻意的播放与现有导出边界使得结果既美观、稳定又一眼可辨是 Archify。从 docs/research-visual-evolution-round-28.md 到 archify/assets/template.html 与 archify/test/chapter-rail.test.mjs这条「产品问题 → 参照源研究 → 有界契约 → 源码落地 → 契约测试」的完整链路正是 Archify 每一轮视觉演化研究的标准范式也值得任何在既有查看器中新增导航能力的产品参考先证明原料已在手再限定边界最后让测试锁定契约。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考