976b48a09d
|
||
|---|---|---|
| apps | ||
| packages | ||
| tests | ||
| .gitignore | ||
| .prettierignore | ||
| .prettierrc.json | ||
| README.md | ||
| eslint.config.mjs | ||
| package-lock.json | ||
| package.json | ||
| playwright.config.ts | ||
README.md
Mosaic 低代码 H5 Demo
一个可运行的低代码 H5 模板示例，包含 Web 编辑器、独立 H5 Renderer、轻量 API、JSON 持久化、不可变发布版本以及端到端测试。
启动项目
环境要求：Node.js 20 或更高版本。
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：
ipconfig getifaddr en0
编辑器、iframe 预览和 H5 API 会自动跟随浏览器当前访问的主机名。访问设备需要与电脑处于同一局域网，并允许 Node.js 通过系统防火墙。
常用命令
# 同时启动 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：共享的预览通信协议。
数据与发布流程
- 编辑器从 API 获取草稿。
- 编辑操作通过 iframe 实时发送给共用 Renderer。
- “保存草稿”只更新草稿数据。
- “发布”创建新的不可变版本，并返回成功版本号。
- 移动端 H5 只读取已发布 Schema，草稿修改不会影响线上版本。
- 再次发布后，移动端读取最新发布版本。
安全约束
- 使用纵向流式区块编排和有限容器嵌套，不支持整页任意绝对定位。
- Schema 不允许任意 JavaScript、
eval、动态组件路径或任意 API 定义。 - 组件类型需要同时通过前端和服务端白名单校验。
- 交互只允许
http://、https://或站内相对路径。 - H5 独立构建，不包含编辑器和拖拽依赖。
Demo 边界
- JSON 持久化面向本地演示，不适用于生产环境的并发写入。
- 当前未包含登录鉴权、租户隔离、资源上传、CDN 转换、协同编辑和数据库迁移。
- 图片使用固定尺寸与浏览器原生懒加载；生产环境建议接入 WebP/AVIF 图片处理链路。