一个HTML文件构建可交互原型：Effective HTML从加载到错误恢复的状态机详解

一个HTML文件构建可交互原型Effective HTML从加载到错误恢复的状态机详解【免费下载链接】effective-htmlAgent skills for useful HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.项目地址: https://gitcode.com/gh_mirrors/ef/effective-htmlEffective HTML 是一个面向 AI 智能体的技能集合帮你用单个 HTML 文件构建可交互原型、线框图、方案文档和示意图。本篇以仓库中的发布就绪Release Readiness示例为蓝本拆解一个完整状态机是如何在零构建工具、零外部依赖的前提下从加载、失败到错误恢复逐步实现的。为什么一个 HTML 文件就能做交互原型Effective HTML 的核心构建约定只有一句话交付一个自包含的.html文件CSS 和 JavaScript 全部内联。不依赖构建工具、认证、实时 API 或任何外部服务双击即可在浏览器打开复制就能改键盘、焦点管理、响应式布局都要真实可用。这套约定写在 skills/html-prototype/SKILL.md 的 Build contract 一节。正因为没有运行时和后端原型里的数据和服务都是用 JavaScript 模拟的——这让加载态、错误态这些真实产品中最难展示的状态反而变得容易演示。动手前先用表格定义状态原型质量的差异往往不在代码而在动手前是否列出了状态清单。Effective HTML 要求先列状态再写代码并明确列出常见状态loading加载、empty空态、error错误、success成功、disabled禁用、mobile移动端以及业务特有状态。本例的状态清单完整记录在 examples/release-readiness/states.md 中状态触发条件用户看到什么可用操作Blocked受阻iOS 冒烟测试失败失败项和决策原因高亮记录重跑Saving保存中提交重跑表单表单禁用进度被播报等待Save error保存失败模拟服务拒绝更新弹窗保留已填内容并解释失败重试或取消Ready就绪4 项检查全部通过摘要变为 4 of 4发布按钮解锁申请生产发布注意一个关键设计取舍不要为了凑齐清单而把无关状态硬塞进主流程。空笔记态之所以存在是因为清空备注这个操作真实可达而登录、持久化则被明确划出原型边界在 examples/release-readiness/brief.md 的 Non-goals 中写明。状态机全景Blocked → Saving → 错误 → Ready整个状态机由一个数据属性驱动body.dataset.releaseState在blocked和ready之间切换其余 UI决策印章、检查计数、风险提示、按钮可用性全部跟随它联动。状态流转如下Blocked ──打开弹窗──▶ 填写表单 ──提交──▶ Saving ▲ │ │ 模拟失败 ◀──┤──▶ 成功 │ ▼ │ └──重跑失败── Ready ◀──重试成功──────────────────┘ │ └──申请发布──▶ 生产边界弹窗明确原型止步于此三个值得新手记住的设计决策失败不丢数据模拟服务拒绝更新时弹窗不关闭、已填值保留只把焦点移到错误提示上用户可以直接重试。边界诚实点击生产发布后原型弹出一个解释框说明真实的发布系统从这里接管而不是假装部署成功。无效操作宁可不放也不造假。每个状态都有可见结果状态表里的 Visible result 一列就是验收标准。加载态实现禁用、Spinner 与 aria-busy加载态的完整实现不到 10 行核心在 prototype.html 的 setSaving 函数function setSaving(saving) { isSaving saving; // 禁用除提交按钮外的所有控件 saveRerun.innerHTML saving ? span classloading-labelspan classspinner/spanSaving evidence/span : Save rerun; rerunForm.setAttribute(aria-busy, String(saving)); }新手容易漏掉的三个细节禁用一切可操作控件保存期间表单不能动连关闭弹窗都被拦截cancel事件在isSaving时调用preventDefault防止用户在请求中途离开导致状态错乱按钮文案换成动词 进行中spinner 旁边显示 Saving evidence视觉反馈和文案反馈一致aria-busy通知屏幕阅读器加载态不只是看起来在转圈读屏软件也能感知。提交后的分流逻辑在 表单 submit 处理器用setTimeout模拟 750ms 网络延迟再根据复选框决定走向错误分支还是成功分支。错误恢复路径保留输入 显式重试错误态最容易做成弹个红色 Toast 然后消失Effective HTML 的做法是把错误恢复当成一条完整路径触发表单里有一个让下一次保存失败一次的复选框专门供评审演示错误路径呈现错误提示formAlert显示说明失败原因保护已填的重跑结果和证据 ID 原样保留用户不必重填引导formAlert.focus()把焦点直接落到错误信息上同时用announce()向辅助技术播报你的输入已保留可以重试。重试成功后的跳转由updateRelease()处理它不只改一个按钮而是同步更新决策印章Blocked → Ready、检查计数3 of 4 → 4 of 4、风险卡片红色感叹号 → 绿色对勾、活动日志和 Toast让状态变化在全页范围内可被看见。反过来如果重跑结果还是失败状态机会从 Ready 回落到 Blocked发布按钮重新禁用——状态机是双向的这比一条道走到成功的原型可信得多。可复制的动手指南想在自己的项目里复用这套做法按下面三步走克隆仓库把示例文件复制为起点git clone https://gitcode.com/gh_mirrors/ef/effective-html cd effective-html cp examples/release-readiness/prototype.html my-prototype.html替换业务保留状态模型先改 brief用户、任务、非目标、标签和数据再碰视觉。参考 examples/release-readiness/README.md 中的 Clone and adapt 说明。按验收清单自测宽屏 窄屏两种宽度、每个建模过的状态都走一遍、Tab/ShiftTab/Enter/Space/Escape全键盘操作、控制台无报错、减少动态效果reduced motion模式下的表现。完整检查记录见 examples/release-readiness/validation.md。相关文档索引原型技能规范skills/html-prototype/SKILL.md线框图技能原型的前置阶段skills/html-wireframe/SKILL.md线框图示例examples/release-readiness/wireframe.html总技能路由与更多场景参考skills/html/references/interfaces.md小结Effective HTML 用发布就绪示例演示了一个可交互原型的标准状态机先定义状态表再让加载、错误、恢复、禁用、空态逐一可触达最后用键盘、焦点和屏幕阅读器检查收尾。单个 HTML 文件不是限制而是它的优势——没有构建链状态机的每一步都能被评审者亲手点出来。【免费下载链接】effective-htmlAgent skills for useful HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.项目地址: https://gitcode.com/gh_mirrors/ef/effective-html创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考