15 KiB

Raw Blame History

ShopXO × uni-app 前端架构调研报告

调研时间：2026-04-17 13:20–13:53 GMT+8 调研人：西莉雅（Sileya）参与：大头（Joery HU）文档版本：v1.0.0 状态：阶段性结论，待美在二次深度调研后更新

一、执行摘要

核心结论

在 ShopXO 生态下，票务小程序的前端开发不应该走 ShopXO 后台 DIY 设计器路线，而应该：

fork shopxo-uniapp → 直接在 Vue/uni-app 源码层修改页面
    ↓
票务页面（首页/商品详情）完全自研
    ↓
商城标准页面（周边/分类/购物车）复用 shopxo-uniapp 原生实现
    ↓
H5 预览 = 小程序编译效果，CSS 完全一致

路径选择理由

维度	DIY 设计器路线	直接改 Vue 源码路线
开发速度	❌ 慢（需开发 shopxo-diy 组件再同步）	✅ 快（直接写 Vue）
自定义自由度	⚠️ 受限（只能嵌入静态区块）	✅ 完全自由
H5/小程序一致性	⚠️ 中间层 JSON 可能产生差异	✅ 同一套 CSS，两端一致
票务交互（选座等）	❌ 无法可视化编辑	✅ 完整自定义
学习成本	高（需理解 shopxo-diy 注册机制）	低（标准 Vue 3）

二、实证调研结果

2.1 ShopXO 自定义模板 → uni-app 的编译关系

结论：不存在"模板配置 → 编译成 uni-app"的链路。

ShopXO 的"模板配置"是 PHP 后台渲染 Web 端（H5/PC）的概念。uni-app 前端是完全独立的项目，通过 API 对接 ShopXO 后端。两者是两套平行代码，不存在编译关系。

2.2 官方 uni-app 端：shopxo-uniapp

源码地址：

GitHub: github.com/gongfuxiang/shopxo-uniapp
Gitee: gitee.com/zongzhige/shopxo-uniapp
DCloud 插件市场: ext.dcloud.net.cn/plugin?id=6380（可一键导入 HBuilderX）

支持平台：

微信小程序（MP-WEIXIN）
QQ 小程序（MP-QQ）
百度小程序（MP-BAIDU）
支付宝小程序（MP-ALIPAY）
抖音/头条小程序（MP-TOUTIAO）
快手小程序（MP-KUAISHOU）
H5
APP（iOS/Android）

主题机制：

内置 8 种配色，默认红色（red）
主题在 App.vue 中改 default_theme 配置
也支持从 ShopXO 后台远程控制主题配色

使用方式：

安装 ShopXO 后端系统（install.shopxo.net）
HBuilderX 导入 shopxo-uniapp 源码
修改 App.vue 的 request_url + static_url 为目标商城地址
运行/发行到目标平台

GitHub Forks：100+，说明大量企业在使用，但绝大多数是私人 fork，公开的票务类二次开发项目不存在。

2.3 DIY 装修组件：shopxo-diy

源码地址：

GitHub: github.com/gongfuxiang/shopxo-diy
Gitee: gitee.com/zongzhige/shopxo-diy

技术栈：

Vue 3 + Vite + TypeScript + SCSS
MIT 开源协议

版本对应表（关键发现）：

shopxo-diy（DIY端）	ShopXO 后端版本
v1.0.0	v6.3.0
v1.1.0	v6.4.0
v1.2.0	v6.5.0
v1.3.0	v6.6.0
v1.4.0	v6.7.0
v1.4.1	v6.7.1
v1.4.2	v6.8.0

说明：shopxo-diy 和 ShopXO 后端必须版本匹配，不能混用。

DIY 设计器的真实能力：

支持拖拽的标准组件：商品、文章、图片魔方、热区、视频、轮播、自定义 HTML
不支持：在设计器里可视化编辑自定义 Vue 组件（座位图、QR 票等）
自定义组件只能以"静态自定义 HTML 区块"方式嵌入设计器，无法参数化配置

三层渲染架构：

ShopXO PHP 后台（DIY 设计器）
    │
    │ 输出：页面配置 JSON → 存入数据库
    ↓
shopxo-diy（Vue 3 组件库）
    │ 负责渲染标准 DIY 组件
    ↓
ShopXO Web（H5/PC） + shopxo-uniapp（小程序/APP）
    │  两个端读同一份 JSON，各自渲染
    ↓
效果一致性由"同一套 JSON + 同一套 Vue 组件库"保证

APP 预览能力：

ShopXO 后台 DIY 设计器只能在 Web 端（H5）预览
shopxo-uniapp 的 /pages/diy/diy.vue 独立渲染同样 JSON
不存在"设计后一键自动编译到 uni-app"的机制

2.4 第三方付费主题

来源：ShopXO 应用商店（store.shopxo.net）

开发者	版本	平台支持	特色
chuyin	1.0.0–2.2.1	微信/支付宝/QQ/百度小程序 + H5 + Android/iOS APP	重构 UI、8种配色、一站一授权、永久免费适配官方插件

注意： shopro（ITmonkey-cn/shopro-uniapp）是独立电商系统，不是 ShopXO 的 fork，不完全兼容 ShopXO API，不能作为 ShopXO 的 uni-app 主题使用。

2.5 给 shopxo-diy 开发自定义组件的可行性

技术层面：可以，但流程较长：

1. fork shopxo-diy
2. 在 src/components/ 下开发 Vue 组件（如 SeatMap.vue）
3. 在 src/config/components.js 里注册组件名+配置
4. npm run build → 生成发布产物
5. ShopXO 后台加载新组件 → DIY 设计器以"自定义区块"嵌入
6. shopxo-uniapp 同步更新 shopxo-diy 版本

限制：

每次改组件都要 rebuild + 同步版本
DIY 设计器里无法可视化配置组件参数（座位数、排数等）
对于票务选座这种复杂交互，自定义 HTML 区块的能力不足以支持

2.6 关键问题：H5 预览 = 小程序编译效果？

是的，可以做到。

uni-app 在 H5 和小程序上的 CSS 渲染完全一致，因为两者都基于 WebView：

H5 端：Chrome/WebView → CSS 引擎（标准浏览器）
小程序端：微信 WebView → 同样的 CSS 引擎

uni-app CSS 规范注意事项：

做法	说明
用 `rpx` 不用 `vw/vh`	rpx 是 uni-app 的响应式单位，H5/小程序都支持
用 `view` 不用 `div`	uni-app 跨平台标签
避免 `calc()` 混用单位	`calc(100% - 215px)` 而非 `calc(100% - 215)`
避免浏览器私有前缀	小程序不需要
`position: fixed` 吸顶	H5 用 `fixed`，小程序用 `absolute` + scroll-view 模拟（shopxo-uniapp 已有解决方案）

不需要 DIY 设计器作为中间层。 shopxo-uniapp 里的页面就是标准 Vue 文件，直接修改即可。

三、设计路径决策

3.1 推荐架构

┌─────────────────────────────────────────────────────┐
│  fork shopxo-uniapp（vr-shopxo-uniapp）             │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │ DIY 设计器（ShopXO 后台）                      │  │
│  │  → 管理：普通商城首页楼层、分类页、活动页       │  │
│  │  → 输出：JSON → shopxo-uniapp /pages/diy/    │  │
│  └──────────────────────────────────────────────┘  │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │ 直接修改 shopxo-uniapp 源码                   │  │
│  │                                              │  │
│  │ pages/index/index.vue → 首页双 Tab（票/周边）  │  │
│  │ pages/goods-detail/goods-detail.vue → 票务   │  │
│  │ pages/ticket-buy/ → 选座+购票主流程（新建）   │  │
│  │ pages/ticket-wallet/ → 票夹（新建）           │  │
│  │ pages/ticket-verify/ → B 端核销（新建）        │  │
│  └──────────────────────────────────────────────┘  │
│                                                     │
│  H5 预览 = 小程序编译效果（CSS 完全一致）           │
└─────────────────────────────────────────────────────┘

3.2 页面职责划分

页面	来源	修改方式
首页（票务 Tab）	shopxo-uniapp 改写	完全自研，座位图/场次组件
首页（周边 Tab）	shopxo-uniapp 改写	复用商品列表，DIy 数据输出
商品详情（票务）	shopxo-uniapp 改写	自定义跳转选座流程
商品详情（周边）	shopxo-uniapp 原生	复用原生 UI
分类/搜索/购物车/订单	shopxo-uniapp 原生	复用原生流程
票夹（我的票）	新建	票务专属页面
B 端核销	新建	扫码 + API 验证

3.3 技术选型

技术项	选型	理由
前端框架	shopxo-uniapp（fork）	完整对接 ShopXO API，节省 80% 开发量
CSS 方案	纯 CSS / SCSS	与官方一致，不需要 Tailwind 等新框架
主题色	CSS Custom Properties	shopxo-uniapp 已有 8 色体系，可复用
响应式	rpx	uni-app 标准响应式单位，H5/小程序一致
打包工具	HBuilderX	uni-app 官方 IDE
开发模式	直接改 Vue 源码	不走 DIY 设计器，完全控制

3.4 与 vr-shopxo-plugin 的关系

shopxo-uniapp（H5/小程序/APP 前端）
    │
    │ API 调用（GET/POST）
    ↓
ShopXO PHP 后端 + vr-shopxo-plugin（票务插件）
    │
    │ 数据库读写
    ↓
vr_sessions / vr_tickets / vr_seat_templates / vr_attendees 等表

uniapp 前端通过 API 调用 ShopXO 后端接口，vr-shopxo-plugin 的数据库表通过插件自定义接口暴露，前端无需感知底层 PHP 实现。

四、原始调研资料清单

4.1 线上资料

编号	来源	URL	关键内容
R1	GitHub shopxo-uniapp	`github.com/gongfuxiang/shopxo-uniapp`	官方 uni-app 端，支持全平台，8种配色
R2	GitHub shopxo-diy	`github.com/gongfuxiang/shopxo-diy`	DIY 组件库，Vue 3+Vite+TypeScript，版本对应表
R3	GitHub shopxo	`github.com/gongfuxiang/shopxo`	ShopXO 主仓库，v6.8.0
R4	DCloud 插件市场	`ext.dcloud.net.cn/plugin?id=6380`	一键导入 HBuilderX
R5	ShopXO 文档	`doc.shopxo.net/article/2.html`	uni-app 使用教程，request_url 配置
R6	ShopXO 文档	`doc.shopxo.net/article/4/265292898306621440.html`	目录结构（v2.2.0+）
R7	ShopXO 文档	`doc.shopxo.net/article/3.html`	插件开发文档索引
R8	uni-app 官网	`zh.uniapp.dcloud.io/matter.html`	跨端注意事项，H5/小程序 CSS 一致性说明
R9	uni-app 文档	`zh.uniapp.dcloud.io/tutorial/syntax-css.html`	rpx/calc 等 CSS 规范
R10	微信开放社区	`developers.weixin.qq.com/community/develop/article/doc/0000a6de494e78235c3dc87b75b013`	第三方开发者分享的 shopxo 小程序主题（黄色主题）
R11	掘金	`juejin.cn/post/7043972891381071880`	ShopXO uni-app 主题分享
R12	ShopXO 应用商店	`store.shopxo.net/goods-41.html`	第三方付费主题（chuyin，v1.0.0-2.2.1）
R13	GitHub shopxo-uniapp	`github.com/gongfuxiang/shopxo-uniapp/network/members`	100+ forks 列表（2026-04-17 采集）
R14	CSDN	`blog.csdn.net/qq_35393869/article/details/114523844`	ShopXO 开发文档目录

4.2 本地 vr-shopxo-plugin 文档

编号	文件	关键内容
L1	`docs/07_SHOPXO_PLUGIN_MECHANISM.md`	插件开发机制、config.json、钩子系统、生命周期事件
L2	`docs/09_SHOPXO_HOOKS_REFERENCE.md`	完整钩子清单（v6.8.0），商品详情页/用户中心/订单等注入点
L3	`docs/02_FRONTEND_CUSTOMIZATION.md`	shopxo-uniapp 编译流程、pages.json 路由、条件编译指令、商品详情页改造方案
L4	`docs/09_SHOPXO_HOOKS_REFERENCE.md`	票务插件推荐钩子（`plugins_service_order_pay_success_handle_end` 等）
L5	`ARCHITECTURE.md`	整体架构，读写分离，商品模型（ticket/physical/bundle）

五、关键发现汇总

5.1 关于 ShopXO DIY 设计器

不支持直接把自定义 Vue 组件导入设计器
不支持设计后自动编译到 uni-app（需手动同步版本）
支持以"自定义 HTML"方式嵌入静态区块（但无法参数化）
适合场景：非技术人员修改标准商城页面（首页楼层/分类等）
不适合场景：票务选座交互、QR 票卡片等复杂自定义 UI

5.2 关于 shopxo-diy

Vue 3 + Vite + TypeScript + SCSS 技术栈
与 ShopXO 后端版本强绑定（v1.4.2 ↔ v6.8.0）
可开发自定义组件，但注册机制复杂，改完需 rebuild
组件风格：CSS Custom Properties 主题切换，SCSS 变量

5.3 关于 shopxo-uniapp

完整独立项目，通过 API 对接 ShopXO 后端
App.vue 改 request_url / static_url 即可连接任意 ShopXO 实例
页面是标准 Vue 文件，直接修改，不需要经过 DIY 设计器
支持全平台（小程序/H5/APP），CSS 在 H5 和小程序间完全一致

5.4 关于 H5 和小程序的一致性

uni-app 的 H5 和小程序都基于 WebView，CSS 渲染一致
关键：用 rpx 不用 vw/vh，用 view 不用 div，避免混用单位
不需要任何中间层即可实现"预览=发行效果"

六、待美在深度调研事项

以下事项需美在从代码层面做二次深入解析，待完成后更新本文档：

shopxo-uniapp 源码结构扫描
- 关键页面文件位置（index/goods-detail/cart/user）
- API 层封装方式（get_request_url 全局方法）
- 全局组件注册机制（pages/index/index.vue 的 usingComponents）
- 主题色 CSS 变量体系（8 色实现方式）
shopxo-diy 组件注册机制
- src/config/ 目录的组件配置格式
- 如何注册一个自定义组件（如 SeatMap.vue）
- 与 ShopXO 后端的 JSON 数据格式对接方式
票务商品详情页的 Hook 注入点
- plugins_view_goods_detail_base_sku_top 的实际返回位置
- 是否存在从 Hook 跳转到独立页面的成熟方案
- 商品详情页完整模板继承链（从哪个基文件继承）
支付成功回调到票务记录的完整链路
- plugins_service_order_pay_success_handle_end 钩子的触发时机
- 订单数据中如何区分票务商品和普通商品
- 观演人信息的存储位置（订单扩展字段还是独立表）
B 端核销页面的权限控制
- 后台核销员角色（vr_verifiers）如何与 ShopXO 后台用户关联
- 核销 API 的鉴权方式（后台登录态还是独立 token）

七、版本历史

版本	日期	修改内容
v1.0.0	2026-04-17	初始版本，涵盖本次调研全部发现

八、参考链接（快速访问）

shopxo-uniapp GitHub:   https://github.com/gongfuxiang/shopxo-uniapp
shopxo-diy GitHub:      https://github.com/gongfuxiang/shopxo-diy
ShopXO 文档目录:        https://doc.shopxo.net/
uni-app CSS 规范:       https://zh.uniapp.dcloud.io/tutorial/syntax-css.html
uni-app 跨端注意:       https://zh.uniapp.dcloud.io/matter.html
DCloud 插件市场:        https://ext.dcloud.net.cn/plugin?id=6380
ShopXO 安装包:          https://install.shopxo.net/

15 KiB Raw Blame History Unescape Escape