从 HTML 原型到 uni-app：单词学习页迁移踩坑复盘

给孩子的英语学习做个顺手的小工具，是很多开发者的起手式。最近一次实践里，手头有一份近百词的小学英语词汇表，需求很朴素：一个能搜索、看起来舒服的移动端页面。于是先用单文件 HTML 让 AI 快速迭代原型，四轮对话定型后，再迁到 uni-app 准备跨端。原型十分钟走完的路，迁移时翻了一次车：页面布局全乱。这篇复盘把这趟小而完整的迁移整理成一份清单，组件映射、单位换算、踩坑点，下次可以直接照抄。

一、原型阶段：单文件 HTML 的迭代节奏

对话式 AI 做这类原型非常合适：单文件 HTML 零依赖零构建，浏览器即开即验，每轮反馈立刻可见。四轮迭代的路径是这样的：

1. 列表加搜索：输入框加按钮，filter 过滤后重渲染列表，回车键同样触发；
2. 视觉收敛：网格卡片换掉朴素列表，浅色底、圆角、悬停微动效；
3. 一行一词、中英对照：把数据结构从字符串数组重构成 { en, zh } 对象数组；
4. 词条操作：每行加播放发音、查看详情、加入单词本三个入口。

四轮里最值钱的是第三轮的数据结构重构。字符串数组只支持英文搜索，换成对象数组后，一行代码就让搜索升级成双语匹配：

const filtered = words.filter(w =>
  w.en.toLowerCase().includes(term) || w.zh.includes(term)
);

输入"苹果"能命中 apple，输入 app 也能顺带命中其他含 app 的词——中文注释字段顺手变成了第二检索维度。原型阶段的经验只有一条：别急着堆视觉，先把数据结构的形状定对，它决定了后面功能的天花板；播放、收藏、详情，都只是往对象上加字段。

顺带一提，AI 给的按钮最初都用 alert 占位：点播放弹一句提示，点收藏弹一句确认。这看似敷衍，其实是合理的脚手架——先把交互契约立住，让每个入口"点了会发生什么"有明确预期，实现细节留到迁移后再补。原型允许糊弄，但要糊弄在正确的位置。

二、迁移清单：Web 到 uni-app 的对应关系

确定要一套代码同时跑小程序、App 和 H5，就得迁 uni-app。这一步不是改个后缀，而是一整套词汇替换：

逻辑层同步换成 Vue 3 的 <script setup>：原型里"过滤后重建 innerHTML"的命令式代码，换成 ref 状态加 computed 派生。搜索框 v-model 绑定关键词，filteredWords 作为计算属性自动跟随——数据驱动恰好替代了手写 DOM 操作，代码量反而更少。

单位换算值得单独强调：rpx 是小程序体系的响应式单位，规定任何屏幕宽度一律等于 750rpx。以 750px 设计稿为基准，换算就是一比二——间距 20px 写成 40rpx，字号 16px 是 32rpx。规则极简，但只要有一处漏换或 px、rpx 混用，页面在不同机型上立刻变形。

另一个迁移期值得顺手做的事是数据归位。百来条词条内联在组件里，原型期无伤大雅；正式迁移时就应该抽成独立的数据模块，页面组件只负责渲染与交互。这样将来接本地存储的单词本或远端接口时，改动只落在数据层，页面组件可以一行不动。

三、翻车与修复：布局为什么全乱了

迁移第一版跑起来，反馈只有四个字：布局全乱了。排查这类问题有个实用顺序：先骨架后皮肤。布局乱往往不是一处错，而是五处小错的叠加——先检查高度、flex 方向这类结构性属性，确认页面骨架立住了，再回头看阴影、圆角这些装饰；顺序反了，调半天细节也白费。逐项排查下来，这次是一整串 web 思维的惯性：

• button 的隐藏边框。小程序的 button 自带默认样式，边框还藏在 ::after 伪元素里，光设 background: none 去不掉，必须显式写 .btn::after { border: none }；
• scroll-view 拒绝滚动。web 容器有内容就撑开，scroll-view 必须拿到确定高度才肯滚，要么 calc(100vh - 头部高度)，要么交给 flex: 1 的父容器分配；
• :hover 全部失效。触屏没有悬停，桌面交互习惯整体作废，操作反馈改由 tap 时的状态变化承担；
• 装饰性样式降级。box-shadow 这类属性跨端表现不一，首屏先保布局，阴影能舍就舍；
• iconfont 引入成本高。字体图标要带字体文件、处理跨端加载，索性退回文字按钮——"播放 / 信息 / 加入 / 详情"四个字，可读性反而更好。

修复思路是回归最朴素的 flex：整页 flex-direction: column 撑满 100vh，分成头部、搜索区、列表三段，列表 flex: 1 吃掉全部剩余空间；卡片内部继续 flex 分行，操作按钮 flex: 1 均分等宽。改完在 H5 和小程序两端表现一致，这次翻车才算落地。

四、延伸思考：AI 协作与跨端策略

跳出这一页，有三点比页面本身更值得记录。

**其一，AI 迁移跨端代码的第一版往往"看起来对"。**组件名换对了，rpx 也换算了，但小程序运行时的默认样式、高度约束这些隐性知识容易被略过，于是产出一份在浏览器里说得过去、在真机上一塌糊涂的代码。此时"布局全乱了"这种强反馈比细致描述更高效——把现象原样丢回去，让 AI 在约束下重建布局，一轮就能收敛。对话式开发的有效循环正是：快速产出、强信号纠偏、再收敛。调试时还有个小技巧：用 uni.showToast 当临时日志，把关键状态直接吐在真机屏幕上，比连调试器看 console 更接近用户视角，小程序真机预览时尤其顺手。

**其二，如果一开始就确定跨端，应该直接用目标框架写原型。**HTML 单文件的价值在于验证周期最短：改一行、刷新即见，适合把交互和数据结构磨对；但定型后再迁移，等于把组件层和样式层重写一遍。两条路线的取舍，本质是验证速度与迁移成本之间的交换——需求越确定，越应该让 AI 直接在终点框架里起笔。顺带一提，若原型语言与目标框架同源（比如原型就用 Vue 写），迁移成本还能再降一档，组件逻辑几乎可以直接搬：AI 对哪套体系越熟，产出的代码离终点就越近。

**其三，小工具的完成度来自低成本增强。**发音不必接付费 TTS，浏览器的 Web Speech API（speechSynthesis）免费覆盖主流浏览器，小程序端再走音频文件兜底；单词本先用本地存储扛住单人使用，localStorage 与 uni.setStorage 都是一行调用；详情页的例句和词性可以交给 AI 批量预生成。这套组合拳不引入后端，就能把页面从"能看"推到"常用"。

一个单词学习页很小，却把前端跨端迁移的高频坑浓缩了一遍：组件词汇、事件模型、单位体系、默认样式。下次让 AI 写跨端页面，不妨先把这份映射清单喂给它——也许就少一轮"布局全乱了"。