lanhu-design-to-html

# Lanhu Design to HTML 从蓝湖设计稿链接自动获取设计数据、分析图层结构、提取元素样式，并还原为 HTML 页面。 ## When to Use 当用户提供 `lanhuapp.com` 链接，或要求分析/还原蓝湖设计稿时调用此 skill。 ## Prerequisites - `playwright-cli` 已安装（运行 `npx --no-install playwright-cli --version` 检查） - Node.js 已安装（用于解析设计数据） ## Workflow Overview ``` 蓝湖链接 → 打开浏览器 → 获取Sketch JSON → 解析图层/样式 → 下载切图到本地 → 分析结构 → 生成HTML → 验证效果 ``` ## 核心原则：切图本地化（必须遵守） **所有切图必须下载到本地 `assets/images/` 目录，HTML 中只引用本地相对路径，禁止使用蓝湖 CDN 链接**（如 `lanhu.oss-cn-beijing.aliyuncs.com`、`alipic.lanhuapp.com`）。原因： - CDN 链接可能因权限/防盗链/链接失效导致图片无法显示 - 本地化后页面可离线运行、便于部署、加载更稳定 - 切图通过 `download-images.js` 统一下载，并生成 `image-map.json`（URL → 本地路径映射），生成 HTML 时按映射表替换为本地路径 ## Quick Start ### Step 1: 打开蓝湖设计稿（含登录检测） ```bash # 1. 以持久化模式打开浏览器（默认 headless，高效） playwright-cli open --persistent # 2. 导航到蓝湖链接（URL含&时必须用双引号包裹） playwright-cli goto "https://lanhuapp.com/web/#/item/project/detailDetach?pid=XXX&image_id=XXX&project_id=XXX&fromEditor=true&type=image" # 3. 等待页面加载后检测登录状态 Start-Sleep -Seconds 3 playwright-cli eval "document.querySelector('.layers_item, .image-wrapper, canvas') ? 'logged-in' : 'NOT-logged-in'" ``` **关键点**： - URL 中的 `&` 在 PowerShell 中会被解释为命令分隔符，必须用双引号 `"..."` 包裹整个 URL - 使用 `--persistent` 保持登录状态（蓝湖需要登录才能查看设计稿） - 等待 3-5 秒让页面完全加载 #### 未登录处理（自动切换 headed 模式） 如果 Step 3 返回 `NOT-logged-in`，说明用户未登录蓝湖。此时关闭 headless 浏览器，切换到 `--headed` 模式，让用户在可见的浏览器窗口中手动登录： ```bash # 1. 关闭 headless 浏览器 playwright-cli close # 2. 以 headed + persistent 模式重新打开浏览器（窗口可见，用户可操作） playwright-cli open --persistent --headed # 3. 重新导航到蓝湖设计稿链接 playwright-cli goto "https://lanhuapp.com/web/#/item/project/detailDetach?pid=XXX&image_id=XXX&project_id=XXX&fromEditor=true&type=image" # 此时浏览器窗口可见，页面显示蓝湖登录界面 # 提示用户：请在弹出的浏览器窗口中登录蓝湖（支持扫码 / 账号密码登录） # 4. 轮询检测登录是否完成（每 3-5 秒重复执行，直到返回 logged-in） playwright-cli eval "document.querySelector('input[type=password], .login-form, .login-container') ? 'waiting' : 'logged-in'" # 5. 登录完成后，重新导航到设计稿链接（登录后页面会跳转到蓝湖首页） playwright-cli goto "https://lanhuapp.com/web/#/item/project/detailDetach?pid=XXX&image_id=XXX&project_id=XXX&fromEditor=true&type=image" Start-Sleep -Seconds 3 ``` **注意**： - `--headed` 让浏览器窗口可见，用户可在页面上操作登录（扫码、输入账号密码等） - `--persistent` 确保登录状态保存到磁盘，下次运行自动保持登录（headless 即可） - 登录完成后必须重新导航到设计稿链接，因为登录后页面会跳转到蓝湖首页 - 登录只需一次，后续运行会自动保持登录状态 ### Step 2: 获取 Sketch JSON 设计数据 蓝湖页面加载时会通过 API 请求获取完整的 Sketch JSON 数据，包含所有图层、样式、切图信息。 ```bash # 查看网络请求，找到 SketchJSON URL playwright-cli requests # 找到包含 "SketchJSON" 或 "alipic.lanhuapp.com" 的请求编号 # 获取响应体（文本类型直接显示，二进制保存到文件） playwright-cli response-body <request-number> ``` **识别 Sketch JSON 请求**： - URL 通常包含 `alipic.lanhuapp.com` 或 `SketchJSON` - Content-Type 为 `application/json` 或 `application/octet-stream` - 文件较大（通常 100KB+） ### Step 3: 解析设计数据 使用辅助脚本解析 Sketch JSON，提取所有图层信息。 ```bash # 将响应体文件路径传给解析脚本 node .trae/skills/lanhu-design-to-html/scripts/parse-design.js <response-file-path> ``` 脚本会生成： - `design-analysis.txt` - 人类可读的图层分析报告 - `design-layers.json` - 结构化的图层数据（供 HTML 生成使用） ### Step 4: 下载切图到本地（必做） **生成 HTML 之前，必须先把所有切图下载到本地。** 解析脚本会在控制台末尾打印下载命令，直接复制执行即可： ```bash # 将 design-layers.json 中的所有切图下载到本地 assets/images/ node .trae/skills/lanhu-design-to-html/scripts/download-images.js <design-layers.json> <output-dir> ``` 脚本会： - 读取 `design-layers.json`，按优先级 SVG > PNG > DDS 收集所有切图 URL - 下载到 `<output-dir>/assets/images/` 目录（文件名取自图层名，自动去重） - 生成 `image-map.json` — 原始 URL 到本地相对路径的映射表（如 `{"https://lanhu.../SketchPngxxx": "./assets/images/apeman.png"}`） - 失败的切图单独记录到 `image-download-failures.json`，可重试 **生成 HTML 时，所有 `<img src>` 必须查 `image-map.json` 替换为本地路径，不得直接写蓝湖 CDN 链接。** ### Step 5: 分析图层结构 根据解析结果，识别页面的组成结构： 1. **画板信息**：尺寸、名称 2. **文本图层**：内容、字体、字号、颜色、对齐方式、行高 3. **图片/切图图层**：图片 URL、尺寸、位置 4. **形状图层**：填充色、圆角、边框、阴影 5. **分组图层**：层级关系 **重点：检查切图可用性**。解析报告会为每个图层标注 `⭐ 切图可用` 字段，并在末尾汇总"切图实现建议"。凡是标记为"是"的图层，说明设计稿已提供切图，**必须直接用 `<img>` 实现，不要用 CSS 还原**。 ### Step 6: 生成 HTML 使用 `generate-html.js` 自动生成 HTML 文件，遵循"切图优先"原则： ```bash # 自动生成 index.html（切图优先 + Flexbox 布局 + 切图本地化校验） node .trae/skills/lanhu-design-to-html/scripts/generate-html.js <design-layers.json> <image-map.json> [output.html] ``` 脚本会： - 读取 `design-layers.json` 与 `image-map.json`，自动构建图层树 - 按 SVG > PNG > DDS 优先级选取切图，用 `<img>` 引用本地路径（从 image-map.json 查找） - 无切图的文本用 CSS 文字样式还原，无切图的形状用 CSS div 还原 - 对同组元素进行布局分析，优先使用 Flexbox 排列（自动检测行/列、计算 gap） - 生成 375×812px 容器的自包含 `index.html`（CSS 内嵌于 `<style>`） - 自动校验 HTML 中是否残留蓝湖 CDN 链接，发现则警告 **生成原则**（脚本已内置，无需手动处理）： - 画板尺寸作为容器（通常 375x812px，对应 750x1624rpx） - 使用绝对定位或 Flexbox 布局 **⭐ 切图优先原则（最重要）**： - **凡有切图的元素，直接用 `<img>` 实现，不要用 CSS 还原。** 切图能 100% 还原设计稿视觉效果，CSS 还原常有偏差。 - 切图来源优先级：`image.svgUrl`（SVG 矢量，最清晰）> `image.imageUrl`（PNG）> `ddsImage.imageUrl`（DDS 渲染图） - 适用所有图层类型，包括： - **文本图层有切图**（如特殊字体标题）→ 用切图，不用 CSS 文字 - **形状图层有切图**（如带边框的按钮）→ 用切图，不用 CSS div - **分组图层有切图**（如整组编组导出的复合元素）→ 用整组一张切图，不要拆分实现 - **图标有切图** → 用切图，不用 CSS/SVG 手绘 - 仅当元素**没有切图**时，才用 CSS 实现（文本用 CSS 文字样式，形状用 background/border/border-radius） **⭐ 切图本地化（硬性要求）**： - `<img src>` 一律使用 `image-map.json` 中的本地相对路径（如 `./assets/images/apeman.png`） - **严禁在 HTML 中出现蓝湖 CDN 链接**（`lanhu.oss-cn-beijing.aliyuncs.com`、`alipic.lanhuapp.com`、`SketchPng`、`SketchSvg` 等） - 若某切图下载失败，需手动下载补齐后再引用本地路径，不得回退到 CDN 链接 - 无切图的文本样式完整还原（字体、字号、颜色、行高、对齐） - 无切图的形状使用 CSS 实现（border-radius, background, box-shadow 等） ### Step 7: 验证效果 ```bash # 启动本地 HTTP 服务器（file:// 协议被浏览器阻止） python -m http.server 8765 # 在浏览器中打开 HTML playwright-cli goto "http://localhost:8765/<html-file>" # 调整视口为移动端尺寸 playwright-cli resize 375 812 # 截图对比 playwright-cli screenshot --filename=preview.png ``` ## Platform Switching (微信小程序) 蓝湖支持多平台样式切换。在设计稿标注视图中： 1. 点击任意设计元素，右侧弹出样式信息面板 2. 面板顶部有平台切换器，点击展开下拉菜单 3. 选择 "微信小程序" (rpx) — 所有尺寸自动转为 rpx 单位 4. **不要切换到"代码"视图**，保持在"标注"视图 平台选项： - iOS (pt) - Android (dp) - Web (px) - 微信小程序 (rpx) — 1px = 2rpx - 像素 (px) ## Detailed References - [蓝湖设计稿分析工作流](references/lanhu-workflow.md) — 详细的操作步骤和技巧 - [设计数据解析指南](references/design-data-parser.md) — Sketch JSON 结构和解析方法 - [HTML 实现指南](references/html-implementation.md) — 设计稿还原的最佳实践