root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6e20987d2f86c461de772a84b4a83f61df9076a8
Neo-ZQYY/apps/miniprogram - 副本/doc/h5-input-material-guide.md

14 KiB
Raw Blame History

H5 → 小程序转换：输入材料准备指南

本文档规范了每次将 H5 原型页面转换为微信小程序时，应提供的输入材料清单、格式要求和操作步骤。 目标：提高 AI 转换还原度，减少颜色/间距换算错误、交互逻辑遗漏、图标处理失误。

一、HTML 文件规范

问题背景

当前 H5 原型是 Tailwind CDN + 内联 SVG + 原生 JS 的单文件结构，存在以下转换障碍：

  • Tailwind 工具类需逐个手动展开为 WXSS，容易遗漏或换算错误
  • 内联 SVG 在小程序中完全不可用，但混在 HTML 里容易被"直译"
  • JS 交互逻辑和 DOM 操作对小程序没有参考价值，反而干扰判断

推荐做法

  1. 提供渲染后的最终 DOM（而非模板源码）

    • 浏览器中打开页面 → 右键 <body> → Copy → Copy outerHTML
    • 原因：Tailwind tailwind.config 中自定义颜色/间距在源码中只是类名，无法确定最终计算值
    • 保存为 docs/h5_ui/rendered/<page-name>.html

  2. 去掉所有 <script> 标签

    • JS 交互逻辑应单独用结构化文本描述（见第三节"交互描述规范"）
    • 不要让 AI 从 DOM 操作代码中反推意图

  3. 内联关键样式（二选一）

    方式 A：手动记录（少量元素时）

    Chrome DevTools 操作：
1. 打开 H5 页面
2. 右键目标元素 → 检查
3. 在 Styles 面板中，点击 Computed 标签
4. 勾选 "Show all"
5. 记录以下关键属性的计算值：
   - width / height / padding / margin / gap
   - font-size / font-weight / line-height / color
   - background / border-radius / box-shadow
   - display / flex-direction / align-items / justify-content

    方式 B：脚本批量导出（推荐） 在 Chrome Console 中执行以下脚本，批量导出关键元素的计算样式：

    function exportStyles() {
  const props = [
    'width','height','padding','margin','gap',
    'fontSize','fontWeight','lineHeight','color',
    'background','backgroundColor','borderRadius',
    'boxShadow','display','flexDirection','alignItems',
    'justifyContent','position','opacity'
  ];
  const elements = document.querySelectorAll('[class]');
  const result = [];
  elements.forEach((el, i) => {
    const cs = getComputedStyle(el);
    const styles = {};
    props.forEach(p => {
      const v = cs[p];
      if (v && v !== 'none' && v !== 'normal' && v !== '0px' && v !== 'auto') {
        styles[p] = v;
      }
    });
    if (Object.keys(styles).length > 0) {
      result.push({
        tag: el.tagName.toLowerCase(),
        classes: el.className,
        text: el.textContent?.trim().slice(0, 30),
        styles
      });
    }
  });
  console.log(JSON.stringify(result, null, 2));
}
exportStyles();

    将输出追加到 docs/h5_ui/computed-styles.json（按页面名分 key 存放）

二、CSS / 样式规范

当前状况

CSS 分两部分：Tailwind 工具类（占 90%）+ 少量自定义 <style> 块。无 SCSS/LESS 预处理器。

设计 Token 文件（做一次，全局复用）

将 Tailwind 自定义主题提取为设计 Token，保存为 docs/h5_ui/design-tokens.json：

{
  "colors": {
    "primary": "#0052d9",
    "primary-light": "#ecf2fe",
    "success": "#00a870",
    "warning": "#ed7b2f",
    "error": "#e34d59",
    "gray-1": "#f3f3f3",
    "gray-2": "#eeeeee",
    "gray-3": "#e7e7e7",
    "gray-4": "#dcdcdc",
    "gray-5": "#c5c5c5",
    "gray-6": "#a6a6a6",
    "gray-7": "#8b8b8b",
    "gray-8": "#777777",
    "gray-9": "#5e5e5e",
    "gray-10": "#4b4b4b",
    "gray-11": "#393939",
    "gray-12": "#2c2c2c",
    "gray-13": "#242424"
  },
  "spacing": {
    "comment": "Tailwind 默认 1 unit = 4px = 8rpx（基于 750rpx 设计稿）",
    "base": 8,
    "unit": "rpx"
  },
  "borderRadius": {
    "sm": "8rpx",
    "md": "16rpx",
    "lg": "24rpx",
    "xl": "32rpx",
    "2xl": "32rpx",
    "3xl": "48rpx"
  },
  "fontSize": {
    "xs": "24rpx",
    "sm": "28rpx",
    "base": "32rpx",
    "lg": "36rpx",
    "xl": "40rpx",
    "2xl": "48rpx"
  },
  "shadows": {
    "lg": "0 8rpx 32rpx rgba(0,0,0,0.06)",
    "xl": "0 16rpx 48rpx rgba(0,0,0,0.08)"
  }
}

自定义动画标注

对 <style> 块中的自定义 CSS，需标注处理方式：

CSS 特性 小程序支持 处理方式
@keyframes + animation ✅ 支持 直接迁移
transition ✅ 支持 直接迁移
linear-gradient ✅ 支持 直接迁移
backdrop-filter: blur() ❌ 不支持 改为半透明背景色 rgba()
blur-xl（Tailwind） ❌ 不支持 去掉或改为纯色
CSS 变量 var() ✅ 支持 直接迁移（TDesign 大量使用）

不需要做的事

  • 不需要展开 SCSS/LESS（当前未使用预处理器）
  • 不需要合并 CSS 文件（小程序每个页面有独立 .wxss）

三、交互描述规范

为什么需要单独描述

H5 原型中的 JS 交互（addEventListener、classList.toggle、innerHTML 等）在小程序中完全不可用。AI 需要从"用户意图"层面理解交互，而非从"DOM 操作"层面翻译。

格式模板

每个页面提供一份交互说明，保存为 docs/h5_ui/interactions/<page-name>.md：

# 页面名：<page-name>

## 状态变量
| 变量名 | 类型 | 初始值 | 说明 |
|--------|------|--------|------|
| agreed | boolean | false | 协议勾选状态 |
| loading | boolean | false | 登录请求中 |

## 用户操作 → 响应
| 操作 | 触发条件 | 响应行为 | 目标状态 |
|------|----------|----------|----------|
| 点击协议勾选框 | 无 | 切换 agreed | agreed=!agreed |
| 点击"使用微信登录" | agreed=true | 调用登录API | loading=true → 跳转 |
| 点击"使用微信登录" | agreed=false | 无响应（按钮禁用态） | 不变 |
| 登录成功 | API返回 | 按用户状态跳转 | 见流程7.1 |
| 登录失败 | API报错 | Toast提示错误 | loading=false |

## 页面状态枚举
| 状态名 | 视觉表现 | 触发条件 |
|--------|----------|----------|
| 默认态 | 按钮灰色禁用 | agreed=false |
| 可登录态 | 按钮蓝色渐变+阴影 | agreed=true |
| 加载中 | 按钮显示loading | loading=true |

必须覆盖的状态（每个页面都要考虑）

状态 说明 视觉表现参考
正常态（有数据） 页面主要功能正常展示 默认截图
空数据态 列表/卡片区域无数据 居中文案 暂无数据 / 暂无任务
加载中态 数据请求中 区域文案 加载中...
错误态 接口请求失败 文案 加载失败，请点击重试 + 重试按钮
登录态差异 如果页面因登录状态有不同表现 按实际描述

四、视觉截图规范

截图是校验还原度的唯一视觉参考

分辨率

  • 使用 iPhone 6/7/8 尺寸（375×667）
  • 这是小程序 750rpx 设计基准的 1:1 对应
  • Chrome DevTools → Toggle device toolbar → 选择 iPhone 6/7/8

每个页面至少截以下状态

状态 文件命名示例 说明
默认/正常态 login--default.png 有数据的主要展示
关键交互态 login--agreed.png 勾选协议后按钮变化
空数据态 task-list--empty.png 如果适用
弹窗/浮层 task-list--longpress-menu.png 弹窗打开状态
筛选展开 board-customer--filter-open.png 下拉筛选展开

命名规范

<page-name>--<state>.png
  • 页面名用小写连字符：board-customer、task-detail、my-profile
  • 状态名用小写连字符：default、empty、loading、error、filter-open、longpress-menu

存放目录

docs/h5_ui/screenshots/

长页面处理

如果页面有滚动内容，提供长截图：

  • Chrome DevTools → Ctrl+Shift+P → 输入 "Capture full size screenshot"

不需要的截图

  • 不需要暗色模式截图（PRD 无暗色模式需求）
  • 不需要多设备截图（仅面向手机竖屏）

五、资源文件规范

当前状况

docs/h5_ui/img/ 只有 2 张图片，大部分图标是内联 SVG。

图标处理优先级

  1. 优先使用 TDesign 内置图标（<t-icon name="xxx">），不需要提供文件
  2. TDesign 没有的图标，提取为独立 SVG 文件
  3. 复杂图形/Logo 使用 PNG/JPG 图片

图标文件规范

项目 规范
格式 SVG（图标）、PNG（带透明图片）、JPG（照片类）
命名 <category>-<name>.svg，如 icon-billiard.svg、icon-wechat.svg
目录 apps/miniprogram/miniprogram/assets/icons/（图标）
apps/miniprogram/miniprogram/assets/images/（图片）
尺寸 图片提供 2x 版本（750px 宽设计稿对应的实际像素）

图标映射表（每个页面提供）

| H5 中的图标描述 | 处理方式 | 小程序引用 |
|----------------|----------|-----------|
| Logo 台球图标 | 自定义SVG | /assets/icons/icon-billiard.svg |
| 任务管理图标 | TDesign | <t-icon name="task" /> |
| 数据看板图标 | TDesign | <t-icon name="chart-bar" /> |
| 智能助手图标 | TDesign | <t-icon name="chat" /> |
| 微信图标 | 自定义SVG | /assets/icons/icon-wechat.svg |
| 返回箭头 | TDesign | <t-icon name="chevron-left" /> |
| 右箭头 | TDesign | <t-icon name="chevron-right" /> |

保存为 docs/h5_ui/icon-mapping.md，或在每个页面的交互说明中附带。

六、目录结构总览

准备完成后，docs/h5_ui/ 目录结构应如下：

docs/h5_ui/
├── css/                          # 原有：自定义 CSS 文件
├── img/                          # 原有：图片资源
├── js/                           # 原有：JS 文件
├── pages/                        # 原有：H5 原型页面
│   ├── login.html
│   ├── board-customer.html
│   └── ...
├── rendered/                     # 新增：渲染后的 DOM（可选）
│   ├── login.html
│   └── ...
├── computed-styles.json          # 新增：计算样式（可选，按页面名分 key）
├── screenshots/                  # 新增：页面截图（必须）
│   ├── login--default.png
│   ├── login--agreed.png
│   ├── task-list--default.png
│   ├── task-list--empty.png
│   └── ...
├── interactions/                 # 新增：交互说明（必须）
│   ├── login.md
│   ├── task-list.md
│   └── ...
├── design-tokens.json            # 新增：设计 Token（必须，做一次）
├── icon-mapping.md               # 新增：图标映射表（必须，做一次）
└── index.html                    # 原有：入口页

七、操作步骤——"怎么喂料"

一次性准备（全局）

  1. 创建 docs/h5_ui/design-tokens.json（从 tailwind.config 提取，见第二节）
  2. 创建 docs/h5_ui/icon-mapping.md（全局图标映射表，见第五节）
  3. 创建目录：screenshots/、interactions/、rendered/（可选）

每个页面的准备流程

Step 1：准备 HTML + 计算样式

  1. 在 Chrome 中打开 docs/h5_ui/pages/<page>.html
  2. 切换到 iPhone 6/7/8 设备模式（375×667）
  3. 在 Console 中运行 exportStyles() 脚本（见第一节）
  4. 将输出追加到 docs/h5_ui/computed-styles.json（以页面名为 key）
  5. （可选）复制渲染后 DOM，保存为 docs/h5_ui/rendered/<page>.html

Step 2：截图

  1. Chrome DevTools → Ctrl+Shift+P → "Capture screenshot"
  2. 每个状态截一张，命名为 <page>--<state>.png
  3. 放入 docs/h5_ui/screenshots/

Step 3：写交互说明

  1. 按第三节格式模板，写出状态变量、操作→响应表、状态枚举
  2. 保存为 docs/h5_ui/interactions/<page>.md

Step 4：标注图标/图片

  1. 检查页面中的所有图标和图片
  2. 在图标映射表中补充新图标的处理方式
  3. 自定义资源放入小程序 assets/ 对应目录

Step 5：喂给 AI

在对话中提供以下信息：

请将 <page-name> 页面转换为小程序。
- HTML：docs/h5_ui/pages/<page>.html
- 计算样式：docs/h5_ui/computed-styles.json（页面 key: <page>）
- 截图：docs/h5_ui/screenshots/<page>__default.png（拖入对话）
- 交互说明：docs/h5_ui/interactions/<page>.md
- PRD 参考：P<N> spec <章节号>
- 图标映射：全部使用 TDesign / 见 icon-mapping.md

八、最低限度清单

如果时间有限，以下三项是"必须提供"的底线：

优先级 材料 作用 频率
P0 截图（默认态，375px 宽） 校验还原度的唯一视觉参考 每页
P0 交互说明（状态变量 + 操作响应表） 避免逻辑错误 每页
P0 设计 Token JSON 避免颜色/间距换算错误 一次
P1 计算样式 JSON 显著提高还原度 每页（可选）
P1 图标映射表 避免图标处理失误 一次 + 增量
P2 渲染后 DOM 复杂页面时有帮助 按需

附录：相关文档

Reference in New Issue View Git Blame Copy Permalink