# Lanhu Design To HTML

> 从蓝湖设计稿链接获取设计信息并还原为HTML页面。Invoke when user provides a lanhuapp.com link, asks to analyze/restore a Lanhu design mockup, or needs to extract design specs from Lanhu.

- Skill: `apeman1024/lanhu-design-to-html` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add apeman1024/lanhu-design-to-html`
- Raw SKILL.md: https://api.skillmd.com/api/skills/apeman1024/lanhu-design-to-html/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: apeman1024 (https://skillmd.com/u/apeman1024)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/apeman1024/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) — 设计稿还原的最佳实践