设计稿还原 H5 与 Python 资料整理流程

约 1576 字大约 5 分钟

2026-09-23

这次蓝牙音乐 H5 的实现路径是：浏览器观察设计稿 → 导出页面和组件资源 → 明确状态与事件 → 编写组件和样式 → 对照效果图检查 → 操作验证 → 构建交付。Python 可以整理输入资料，但静态效果图不能替代交互规范。

写代码前需要哪些数据

数据	本项目中的例子	获取方式
页面整体效果图	开屏、蓝牙引导、播放页、音乐库、设置	在设计稿中选中完整页面，右侧导出切换 PNG，点击导出，通过浏览器下载
独立视觉资源	唱片、封面、手机图标、USB 卡片、皮肤缩略图	选中对应图层，通过浏览器导出透明 PNG；不能拆出的图层暂用原图图集裁切
布局和样式参数	1920×1080 画布、坐标、字体、颜色、圆角	读取设计工具属性栏、对照原尺寸效果图；未标注的数据需要记录为假设
组件状态	未上焦、上焦、次焦、禁用、已连接	查看同组件不同状态稿，结合用户说明确认
页面事件与转换	手机开始播放才进入播放器，连接成功仍留在引导页	设计标注和用户补充，写成状态转换表
动画数据	68 张音符帧、栏位收起和页面渐隐	通过浏览器下载帧资源；帧序、帧率、时长、启停条件另行确认
范围和验收条件	不接入真实蓝牙、USB、熄屏；只实现首个皮肤	用户要求和实际操作验收

PNG 是视觉基准，并不包含真实 DOM、组件关系或业务规则。导出倍率也需要记录：例如 @2x 图片尺寸不能直接当作 CSS 尺寸。动画采用的 30 fps、页面停留时长等演示参数，需要与设计明确标注的数值区分。

代码如何组织

本项目使用 Vite 和原生 JavaScript。图片保留为本地资源，文字、按钮和状态反馈由 HTML/CSS 实现；需要交互的页面不能只铺一张截图。按原稿 1920×1080 坐标组织主体，窗口变化时等比缩放。

设备按钮封装焦点配色，Toast 封装提示与确认交互，播放源和皮肤列表封装侧栏。引导状态、歌曲模拟事件、栏位显隐和动画生命周期各自管理，并通过事件关联。焦点只改变视觉属性，避免修改布局尺寸导致图标文字移动。

检查不仅比较静态截图，还操作状态转换：连接不自动播放、切换来源清除连接、关闭弹层恢复焦点、收起 tab 时销毁提示、离开页面停止帧更新。构建检查用于确认资源引用和产物可用，不能替代视觉验收。

Python 脚本覆盖的范围

项目中的 scripts/design_intake.py 使用 Python 3.9 以上标准库，Windows 与 macOS 均可运行，无需 pip 安装依赖。

它提供三个命令：

init：创建 design-data/brief.json，记录画布、实现范围、页面状态、事件、组件状态、动画参数和验收条件。初始内容是待确认示例，不是设计稿自动识别结果。
import：导入浏览器已下载的 PNG 或动画 ZIP，检查 PNG 文件头和尺寸，记录 SHA256、来源说明和原始文件名，不覆盖已有文件。
scan：扫描 design-reference 和 public/assets，生成 inventory.json 与可双击打开的 index.html 预览目录。

ZIP 中仅读取 PNG 内容，使用生成的文件名保存，不直接解压原始路径。动画按文件名自然排序，并保存原始文件名对应关系；如果设计图层叫“容器 2”或存在特殊顺序，仍必须人工核对。PNG 检查是头部检查，不是完整图像解码或视觉质量检查。

脚本不接管浏览器登录、不获取账户令牌、不调用未验证的设计工具私有接口，也不自动推断交互。来源建议填写“MasterGo / 页面名称 / 图层名称”，不要放含访问令牌的完整 URL。已有资源若没有导入记录，目录中会明确显示“未记录，需人工补充”。

使用方式

在项目目录运行以下命令；Windows 将 python3 替换为 python。init 只需运行一次，本项目已生成模板。

python3 scripts/design_intake.py init

# 先在浏览器按“选中页面 → 导出 PNG → 下载”取得文件
python3 scripts/design_intake.py import ~/Downloads/player.png --kind page --name player --origin "MasterGo / 播放页"

# 单独导出的组件图片
python3 scripts/design_intake.py import ~/Downloads/record.png --kind asset --name record-new --origin "MasterGo / 唱片图层"

# 浏览器下载的动画帧 ZIP
python3 scripts/design_intake.py import ~/Downloads/notes.zip --kind frames --name notes-new --origin "MasterGo / 加载动画"

python3 scripts/design_intake.py scan

文件名 --name 使用英文字母、数字、短横线或下划线。页面进入 design-reference，组件和动画进入 public/assets，来源记录进入 design-data/provenance.json。已有目标会拒绝导入，避免误改正在使用的资源。双击 design-data/index.html 可以查看缩略图并打开原图。

若项目不在当前目录，可在子命令前添加 --root：

python3 scripts/design_intake.py --root "/path/to/project" scan

还能自动化到什么程度

若要进一步把设计工具导出也纳入 Python，需要明确设计平台、可用的官方 API、文件与节点标识、导出权限，以及安全的登录方式。有稳定 API 时可以扩展为节点导出；只有浏览器界面时，需要另做针对该平台的浏览器自动化，并处理图层选择、导出格式和下载完成确认。不能把当前会话中的浏览器工具直接当成普通 Python 库使用。

即使取得所有图层数据，也仍需要交互需求和验收标准。更可靠的目标是自动生成可审查的开发资料包，让编码阶段明确知道哪些是事实、哪些是估计、哪些尚未确认。