128 lines
4.7 KiB
Markdown
128 lines
4.7 KiB
Markdown
# Mosaic 低代码 H5 Demo
|
||
|
||
一个可运行的低代码 H5 模板示例，包含 Web 编辑器、独立 H5 Renderer、轻量 API、JSON 持久化、不可变发布版本以及端到端测试。
|
||
|
||
## 启动项目
|
||
|
||
环境要求：Node.js 20 或更高版本。
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
启动后可访问：
|
||
|
||
- Web 编辑器：<http://localhost:5173>
|
||
- 已发布 H5：<http://localhost:5174/?id=demo-store>
|
||
- API 服务：<http://localhost:3000>
|
||
|
||
## 局域网访问
|
||
|
||
开发服务默认监听所有网络接口。正常运行 `npm run dev` 后，将地址中的 `localhost` 替换为当前电脑的局域网 IP：
|
||
|
||
- Web 编辑器：`http://<本机局域网IP>:5173`
|
||
- 已发布 H5：`http://<本机局域网IP>:5174/?id=demo-store`
|
||
- API 服务：`http://<本机局域网IP>:3000`
|
||
|
||
macOS 可使用以下命令查看 Wi-Fi 局域网 IP：
|
||
|
||
```bash
|
||
ipconfig getifaddr en0
|
||
```
|
||
|
||
编辑器、iframe 预览和 H5 API 会自动跟随浏览器当前访问的主机名。访问设备需要与电脑处于同一局域网，并允许 Node.js 通过系统防火墙。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 同时启动 API、编辑器和 H5
|
||
npm run dev
|
||
|
||
# ESLint、TypeScript、Prettier 和构建检查
|
||
npm run check
|
||
|
||
# 构建全部工作区
|
||
npm run build
|
||
|
||
# 检查独立 H5 产物不包含编辑器或拖拽依赖
|
||
npm run check:h5
|
||
|
||
# 运行 Playwright 端到端测试
|
||
npm run test:e2e
|
||
```
|
||
|
||
## 组件库
|
||
|
||
编辑器顶部可以切换左侧物料面板。切换组件库不会删除画布中已有的区块，因此两套组件也可以在同一个 Schema 中混合使用。
|
||
|
||
### 营销组件
|
||
|
||
- 横幅 Banner
|
||
- 标题
|
||
- 文本
|
||
- 图片
|
||
- 按钮
|
||
- 商品列表
|
||
- 分割线
|
||
- 间距
|
||
- 双列容器
|
||
|
||
### 直充 / 卡密组件
|
||
|
||
- 权益商品卡片
|
||
- 兑换操作区
|
||
- 兑换说明
|
||
- 权益商品列表
|
||
|
||
点击“添加业务示例组合”可以一次插入四种数字权益组件，快速生成可编辑的直充/卡密页面原型。
|
||
|
||
## 组件配置能力
|
||
|
||
- Banner：标题、副标题、多图片、图片说明、轮播开关、循环播放、自动播放间隔、高度、遮罩、对齐和文字颜色。
|
||
- 标题：文字、字号、字重、对齐、内边距和颜色。
|
||
- 文本：多行内容、字号、行高、对齐、内边距、文字和背景颜色。
|
||
- 图片：图片地址、无障碍说明、高度、裁切方式和圆角。
|
||
- 按钮：文字、尺寸、圆角、颜色和安全链接交互。
|
||
- 商品列表：商品增删、名称、价格、图片、列数、间距、图片高度和颜色。
|
||
- 分割线：粗细、间距、线型和颜色。
|
||
- 间距：高度和背景颜色。
|
||
- 双列容器：左右栏独立内容、间距、高度、内边距、对齐和背景颜色。
|
||
- 权益商品卡片：直充/卡密方式、名称、说明、价格、图片、标签、VIP 标识、按钮文案和品牌色。
|
||
- 兑换操作区：主次按钮文案、显隐、圆角和颜色。
|
||
- 兑换说明：栏目标签、标题、多行说明和强调样式。
|
||
- 权益商品列表：权益增删、交付方式、名称、价格、数量显示和卡片样式。
|
||
|
||
## 工程结构
|
||
|
||
- `apps/editor`：Vue 3 Web 编辑器，包含物料、图层、iframe 画布、属性面板、历史记录、草稿和发布操作。
|
||
- `apps/h5`：独立 H5 入口，只读取已发布 Schema，并提供会话级 Schema 缓存。
|
||
- `apps/server`：Express API，使用 JSON 文件持久化草稿和不可变发布版本。
|
||
- `packages/page-schema`：Schema 类型、组件白名单和运行时校验工具。
|
||
- `packages/materials`：统一注册组件名称、默认值和组件库分组。
|
||
- `packages/renderer`：编辑器预览与移动端 H5 共用的安全 Renderer。
|
||
- `packages/shared`：共享的预览通信协议。
|
||
|
||
## 数据与发布流程
|
||
|
||
1. 编辑器从 API 获取草稿。
|
||
2. 编辑操作通过 iframe 实时发送给共用 Renderer。
|
||
3. “保存草稿”只更新草稿数据。
|
||
4. “发布”创建新的不可变版本，并返回成功版本号。
|
||
5. 移动端 H5 只读取已发布 Schema，草稿修改不会影响线上版本。
|
||
6. 再次发布后，移动端读取最新发布版本。
|
||
|
||
## 安全约束
|
||
|
||
- 使用纵向流式区块编排和有限容器嵌套，不支持整页任意绝对定位。
|
||
- Schema 不允许任意 JavaScript、`eval`、动态组件路径或任意 API 定义。
|
||
- 组件类型需要同时通过前端和服务端白名单校验。
|
||
- 交互只允许 `http://`、`https://` 或站内相对路径。
|
||
- H5 独立构建，不包含编辑器和拖拽依赖。
|
||
|
||
## Demo 边界
|
||
|
||
- JSON 持久化面向本地演示，不适用于生产环境的并发写入。
|
||
- 当前未包含登录鉴权、租户隔离、资源上传、CDN 转换、协同编辑和数据库迁移。
|
||
- 图片使用固定尺寸与浏览器原生懒加载；生产环境建议接入 WebP/AVIF 图片处理链路。
|