weaver-e10-builder 1.5.16 → 1.6.4

package/skill-docs/references/coding/guide-html-to-react.md

@@ -0,0 +1,250 @@
+# HTML 原型还原成 React
+
+> 用户给出 HTML 原型，要求「完整还原页面效果」时使用。目标是把原型的 DOM 和 CSS 原样搬进 Ecode React 页面，不是重新设计一套样式。
+>
+> 本流程不提供本地预览；样式以原型为准，部署后由用户在实际环境验收。
+
+---
+
+## 一、原则
+
+1. **CSS 原样复用**：原型 `<style>` 整段复制进代码，不改规则、不重写、不近似。
+2. **DOM 结构保留**：class 名、层级、标签尽量不动；React 只接管状态和事件。
+3. **不建独立 `.css` 文件**：ecode 没有 CSS 模块解析，`import './x.css'` 会静默丢失。
+4. **不逐条改内联 style**：把 CSS 原文放进字符串，比把每条规则翻译成 `style={{...}}` 更可靠。
+5. **平台组件只用于必须能力**：人员/部门选择、上传、文件预览；其余用原生 HTML + 原型 CSS。
+
+---
+
+## 二、提取 CSS
+
+原型里的：
+
+```html
+<style>
+  .auction-page { ... }
+  .auction-card { ... }
+  @media (max-width: 900px) { ... }
+</style>
+```
+
+原样放到 `styles/prototypeStyles.js`：
+
+```js
+export var PROTOTYPE_CSS = `
+  .auction-page { ... }
+  .auction-card { ... }
+  @media (max-width: 900px) { ... }
+`;
+```
+
+页面壳渲染一次：
+
+```js
+import { PROTOTYPE_CSS } from '../styles/prototypeStyles.js';
+
+export default function Page() {
+  return (
+    <div className="prototype-root">
+      <style>{PROTOTYPE_CSS}</style>
+      {/* 页面内容 */}
+    </div>
+  );
+}
+```
+
+注意：
+
+- 不要把 CSS 拆成多个 `.css` 文件。
+- 不要在 JS 里 `import './prototype.css'`。
+- 如果原型有多段 `<style>`，按原顺序拼进同一个字符串。
+- 原型的 `<link rel="stylesheet">` 外部样式：把内容下载后并入字符串；不要保留外链，也不要让平台去 CDN 拉。
+
+---
+
+## 三、收敛全局选择器
+
+原型可能直接写 `body`、`:root`、`*`、全局 `h1`。直接搬进平台会污染平台壳。处理方式：
+
+1. 给页面根加一个唯一类名，例如 `proto-auction`。
+2. 把 `body` / `:root` / `*` 规则改挂到根类名下，保持视觉等价。
+3. `:root` 的 CSS 变量移到根类名下。
+4. `@keyframes` 名称加页面前缀，避免与平台动画重名。
+5. `!important` 原样保留，不要自行删减。
+
+示例：
+
+```css
+/* 原型 */
+:root { --brand: #c9a227; }
+body { background: #f5f3ef; }
+
+/* 页面内 */
+.proto-auction { --brand: #c9a227; background: #f5f3ef; }
+```
+
+选择器收敛后要逐项核对：背景、字体、颜色、间距不能因为换父级而失效。
+
+---
+
+## 四、浮层 / Portal 与 CSS 作用域
+
+原型 CSS 收敛到 `.xxx-root` 后，**浮层的 DOM 必须仍在根容器内**。React 的 Provider / Portal 很容易把弹窗渲染成根容器的兄弟节点：
+
+```jsx
+// 错误：modal 在 .auction-root 外面，.auction-root .modal 不命中
+<>
+  <div className="auction-root"><Shell /></div>
+  <OverlayProvider />   {/* Portal 到 body 或兄弟节点 */}
+</>
+
+// 正确：把 Provider / Portal 容器放进根节点
+<div className="auction-root">
+  <OverlayProvider>
+    <Shell />
+  </OverlayProvider>
+</div>
+```
+
+如果平台或第三方 Provider 必须挂到 `body`，就不要把弹窗样式写成 `.root .modal`；改用唯一的全局类（如 `.auction-modal`）并确保它不会和平台样式冲突。**CSS 作用域一旦引入，DOM 层级就是隐式契约。**
+
+---
+
+## 五、HTML → JSX 的机械转换
+
+| HTML | JSX |
+|---|---|
+| `class="x"` | `className="x"` |
+| `for="x"` | `htmlFor="x"` |
+| `style="color: red; margin: 8px"` | `style={{ color: 'red', margin: 8 }}` |
+| `onclick="fn()"` | `onClick={fn}` |
+| `<input>` `<img>` `<br>` | 自闭合 `<input />` `<img />` `<br />` |
+| `<!-- 注释 -->` | `{/* 注释 */}` |
+| `data-x="1"` | `data-x="1"`（保留） |
+| `aria-*` | 保留 |
+| `innerHTML` 拼出的列表 | `array.map(...)` + `key` |
+
+**保留 class 名和层级**。不要为了“React 化”把 div 换成语义标签、不要重排 DOM、不要改 class 命名，否则原型 CSS 全部失效。
+
+---
+
+## 六、静态 DOM → 组件
+
+原型常见写法：
+
+```js
+function renderCard(item) {
+  return `<div class="auction-card">
+    <h3>${item.name}</h3>
+    <span>${item.price}</span>
+  </div>`;
+}
+el.innerHTML = list.map(renderCard).join('');
+```
+
+React 写法：
+
+```js
+function Card(props) {
+  return (
+    <div className="auction-card">
+      <h3>{props.item.name}</h3>
+      <span>{props.item.price}</span>
+    </div>
+  );
+}
+
+function List(props) {
+  return (
+    <div>
+      {props.items.map(function (item) {
+        return <Card key={item.id} item={item} />;
+      })}
+    </div>
+  );
+}
+```
+
+- 重复块抽成组件，不要保留 `innerHTML` 拼串。
+- 每个列表项必须有稳定 `key`（优先数据 ID，不要用下标）。
+- 不要在组件里 `document.getElementById` / `querySelector` 操作原型 DOM。
+- 弹窗、抽屉、Toast 用 state 控制显示，不要直接改 `style.display`。
+
+---
+
+## 七、状态与交互
+
+| 原型行为 | React 做法 |
+|---|---|
+| `onclick` 调全局函数 | 组件内事件处理函数 |
+| 直接改 DOM 文本/class | state + 条件渲染 |
+| 显示/隐藏弹窗 | `var [visible, setVisible] = useState(false)` |
+| 定时器刷新倒计时 | `useEffect` 中 `setInterval`，卸载时 `clearInterval` |
+| 表单输入 | 受控 `value` + `onChange` |
+| 页面切换 | 路由注册，或单页 state；优先路由，方便挂菜单 |
+
+`useEffect` 的清理函数必须写，避免页面切换后定时器还在跑。
+
+---
+
+## 八、数据接入
+
+静态原型的数据是写死的，接入时：
+
+1. 用 `formClient` 替换原型里的 seed 数据；字段 ID 来自 `app/fields.js`。
+2. 列表渲染用 `row.display`，表单回填用 `row.values`，人员/附件用 `row.items`。
+3. 原型里的 mock 数据可以保留为 `mockData.js`，只用于纯展示页或空态演示；正式页面不要同时保留两套数据源。
+4. 写操作要有 loading / error / 成功反馈；原型如果只做 toast，保留 toast 的样式和交互。
+
+详细数据规则见 `guide-form-crud.md`。
+
+---
+
+## 九、图片与资源
+
+- 原型里的 `<img src="...">`：本地图片放到 `resources/`，代码里写 `${appRes}/文件名`。
+- data URI 可以原样保留，但大图建议转成资源文件。
+- 背景图写在 CSS 字符串里时，路径同样写 `${appRes}/...`。`${appRes}` 是平台导入时替换的模板变量，不是 JS 变量；不要自己用 JS 变量拼接。
+- 不要引用 CDN、外链图片、在线字体。
+
+---
+
+## 十、还原核对清单
+
+- [ ] 原型 `<style>` 已整段复制，没有改写/删减
+- [ ] 没有独立 `.css` 文件，没有 `import` CSS
+- [ ] class 名和 DOM 层级与原型一致
+- [ ] 全局选择器已收敛到页面根，平台壳未被污染
+- [ ] 字体、字号、颜色、圆角、边框、阴影、间距一致
+- [ ] hover / active / disabled / 空态 / 加载态一致
+- [ ] 表格列宽、换行、横向滚动行为一致
+- [ ] 弹窗、抽屉、Toast 的层级和遮罩一致
+- [ ] 图片/资源路径使用 `${appRes}`
+- [ ] 列表有稳定 `key`，没有用下标
+- [ ] 定时器/监听在卸载时清理
+- [ ] 没有 `innerHTML` 拼布局，没有直接操作 DOM
+
+---
+
+## 十一、常见走样原因
+
+| 原因 | 表现 | 处理 |
+|---|---|---|
+| 把 CSS 规则翻译成内联 style | 伪类、媒体查询、层叠全丢 | 保留 CSS 字符串 |
+| 改了 class 名 | 原型样式全部不命中 | 原名保留 |
+| 给页面根加了额外 flex/grid | 间距、宽度变化 | 根容器只加作用域类，不加布局 |
+| 全局 `body` 规则直接搬入 | 平台头部/侧栏被改 | 收敛到页面根 |
+| 图片用相对路径 | 发布后 404 | `${appRes}` |
+| 用 `display` 回填表单 | 中文名写回 ID 字段 | 用 `values` |
+| 列表用 index 做 key | 删除/排序后状态错位 | 用数据 ID |
+
+---
+
+## 十二、验收方式
+
+本流程不提供本地预览。完成后：
+
+1. `e10-cli check <项目目录>` 扫描已知规则。
+2. `ecodecmd build <项目目录> --target=e10` 做真实编译。
+3. 按 `guide-page-export.md` 注册路由、部署。
+4. 由用户在实际环境逐项对照原型验收；发现偏差时回到本文件第九节定位。