472 lines
11 KiB
Markdown
472 lines
11 KiB
Markdown
# shopxo-uniapp 前端编译与自定义
|
||
|
||
> 调研时间：2026-04-14
|
||
> 源码位置：`council-research/shopxo-eval/.worktrees/shopxo-evaluator/shopxo-uniapp-src/`
|
||
> 官方仓库：https://gitee.com/zongzhige/shopxo-uniapp
|
||
|
||
---
|
||
|
||
## 一、项目概述
|
||
|
||
shopxo-uniapp 是 ShopXO 官方出品的 uni-app 前端，支持：
|
||
- ✅ 微信小程序（MP-WEIXIN）
|
||
- ✅ QQ 小程序（MP-QQ）
|
||
- ✅ 百度小程序（MP-BAIDU）
|
||
- ✅ 支付宝小程序（MP-ALIPAY）
|
||
- ✅ 抖音/头条小程序（MP-TOUTIAO）
|
||
- ✅ 快手小程序（MP-KUAISHOU）
|
||
- ✅ H5
|
||
- ✅ APP（iOS/Android）
|
||
|
||
**README 原文**：> 已支持小程序（微信、QQ、百度、支付宝、头条&抖音、快手）+ H5 + APP
|
||
|
||
---
|
||
|
||
## 二、编译到微信小程序
|
||
|
||
### 2.1 编译工具
|
||
|
||
**HBuilderX**（uni-app 官方 IDE）
|
||
|
||
### 2.2 编译步骤
|
||
|
||
1. 用 HBuilderX 导入 `shopxo-uniapp-src` 项目
|
||
2. 修改 `App.vue` 中的接口地址：
|
||
```javascript
|
||
// globalData 配置
|
||
request_url: 'https://your-shopxo-domain.com/', // 你的 ShopXO 域名
|
||
static_url: 'https://your-shopxo-domain.com/static/'
|
||
```
|
||
3. 修改 `manifest.json` 中的 AppID（微信小程序配置）：
|
||
```json
|
||
{
|
||
"mp-weixin": {
|
||
"appid": "wx YOUR APPID",
|
||
"setting": {
|
||
"urlCheck": false
|
||
}
|
||
}
|
||
}
|
||
```
|
||
4. 顶部菜单 → **发行** → **微信小程序**
|
||
5. 用微信开发者工具打开发行目录
|
||
|
||
### 2.3 条件编译指令
|
||
|
||
在 `.vue` 文件和 `pages.json` 中使用：
|
||
|
||
```vue
|
||
<!-- #ifdef MP-WEIXIN || MP-BAIDU || MP-QQ || MP-KUAISHOU || H5 || APP -->
|
||
<view class="top-nav">微信/百度/QQ/快手/H5/APP 专属内容</view>
|
||
<!-- #endif -->
|
||
|
||
<!-- #ifdef MP-ALIPAY -->
|
||
<view>支付宝专属内容</view>
|
||
<!-- #endif -->
|
||
|
||
<!-- #ifndef H5 -->
|
||
<!-- 非 H5 平台（小程序）专属内容 -->
|
||
<uni-icons type="scan" @tap="scan_event"></uni-icons>
|
||
<!-- #endif -->
|
||
```
|
||
|
||
在 `pages.json` 中：
|
||
```json
|
||
{
|
||
"path": "pages/goods-detail/goods-detail",
|
||
"style": {
|
||
"// #ifdef MP-WEIXIN": "",
|
||
"navigationStyle": "custom",
|
||
"// #endif": "",
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、pages.json 路由与全局组件
|
||
|
||
### 3.1 核心页面
|
||
|
||
```json
|
||
{
|
||
"pages": [
|
||
{ "path": "pages/index/index" }, // 首页（含 DIY）
|
||
{ "path": "pages/goods-category/goods-category" }, // 分类
|
||
{ "path": "pages/cart/cart" }, // 购物车
|
||
{ "path": "pages/user/user" } // 用户中心
|
||
],
|
||
"subPackages": [
|
||
{
|
||
"root": "pages/diy", // DIY 页面
|
||
"pages": [{ "path": "diy" }]
|
||
},
|
||
{
|
||
"root": "pages/goods-detail", // 商品详情
|
||
"pages": [{ "path": "goods-detail" }]
|
||
},
|
||
{
|
||
"root": "pages/goods-search", // 搜索
|
||
"pages": [{ "path": "goods-search" }]
|
||
},
|
||
{
|
||
"root": "pages/user-order-detail", // 订单详情
|
||
"pages": [{ "path": "user-order-detail" }]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 3.2 全局注册的自定义组件
|
||
|
||
在 `pages/index/index` 的 `style.usingComponents` 中全局注册：
|
||
|
||
```json
|
||
{
|
||
"component-diy": "/pages/diy/components/diy/diy",
|
||
"component-form-input": "/pages/form-input/components/form-input/form-input",
|
||
"component-layout": "/pages/design/components/layout/layout",
|
||
"component-goods-comments": "/pages/goods-detail/components/goods-comments/goods-comments",
|
||
"component-coupon-card": "/pages/plugins/coupon/components/coupon-card/coupon-card",
|
||
"component-form-input-base": "/pages/form-input/components/form-input/form-input-base"
|
||
}
|
||
```
|
||
|
||
其他页面按需引入。
|
||
|
||
---
|
||
|
||
## 四、商品详情页改造
|
||
|
||
### 4.1 商品详情页位置
|
||
|
||
`pages/goods-detail/goods-detail.vue`
|
||
|
||
### 4.2 添加票务条件渲染
|
||
|
||
在 `<template>` 中添加：
|
||
|
||
```vue
|
||
<template>
|
||
<view :class="theme_view">
|
||
<!-- 顶部导航（始终显示）-->
|
||
<view class="page ...">
|
||
<top-nav></top-nav>
|
||
|
||
<!-- 票务商品：完全自定义页面结构 -->
|
||
<block v-if="goods && goods.item_type === 'ticket'">
|
||
<ticket-header :goods="goods"></ticket-header>
|
||
<ticket-seat-selector
|
||
:goods-id="goods.id"
|
||
:spec-data="goods_spec_data"
|
||
@select="on_seat_select"
|
||
></ticket-seat-selector>
|
||
<ticket-info :goods="goods"></ticket-info>
|
||
<ticket-attendee-form
|
||
:max-count="selected_seats.length"
|
||
@submit="on_attendee_submit"
|
||
></ticket-attendee-form>
|
||
<ticket-purchase-bar
|
||
:goods="goods"
|
||
:selected-seats="selected_seats"
|
||
:attendees="attendees"
|
||
@buy="ticket_buy"
|
||
></ticket-purchase-bar>
|
||
</block>
|
||
|
||
<!-- 普通商品：原有完整 UI -->
|
||
<block v-else>
|
||
<goods-photo :photos="goods_photo"></goods-photo>
|
||
<goods-price :goods="goods"></goods-price>
|
||
<goods-spec-select
|
||
v-if="goods.is_exist_many_spec == 1"
|
||
:spec-data="goods_spec_data"
|
||
></goods-spec-select>
|
||
<goods-buy-nav :buy-button="buy_button"></goods-buy-nav>
|
||
<goods-tabs :tabs="tabs"></goods-tabs>
|
||
</block>
|
||
</view>
|
||
</view>
|
||
</template>
|
||
```
|
||
|
||
### 4.3 后端配合（可选）
|
||
|
||
如果需要完全不同的页面结构，可以：
|
||
|
||
**方案 A：插件钩子替换**
|
||
- 在 `plugins_view_goods_detail_base_sku_top` 注入跳转按钮
|
||
- 点击后用 `uni.reLaunch` 跳转到 `pages/ticket-buy/ticket-buy`
|
||
|
||
**方案 B：修改 Goods.php 控制器（1 行）**
|
||
```php
|
||
// app/index/controller/Goods.php Index() 方法
|
||
if($goods['item_type'] == 'ticket') {
|
||
return MyView('/goods/ticket_detail'); // 自定义模板
|
||
}
|
||
return MyView();
|
||
```
|
||
|
||
**推荐方案 A**（通过插件机制，不修改核心代码）。
|
||
|
||
---
|
||
|
||
## 五、新建票务专属页面
|
||
|
||
### 5.1 在 pages.json 中添加路由
|
||
|
||
```json
|
||
{
|
||
"subPackages": [
|
||
{
|
||
"root": "pages/ticket-buy",
|
||
"pages": [
|
||
{
|
||
"path": "ticket-buy",
|
||
"style": {
|
||
"navigationBarTitleText": "选择座位",
|
||
"navigationStyle": "custom"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"root": "pages/ticket-verify",
|
||
"pages": [
|
||
{
|
||
"path": "ticket-verify",
|
||
"style": {
|
||
"navigationBarTitleText": "票务核销",
|
||
"enablePullDownRefresh": false
|
||
}
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"root": "pages/ticket-wallet",
|
||
"pages": [
|
||
{
|
||
"path": "ticket-wallet",
|
||
"style": {
|
||
"navigationBarTitleText": "我的票夹"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 5.2 页面目录结构
|
||
|
||
```
|
||
pages/ticket-buy/
|
||
├── ticket-buy.vue # 选座 + 购票主流程
|
||
└── components/
|
||
├── seat-selector.vue # 座位选择器
|
||
├── attendee-form.vue # 观演人表单
|
||
└── purchase-bar.vue # 购买栏
|
||
|
||
pages/ticket-wallet/
|
||
├── ticket-wallet.vue # 票夹主页面
|
||
└── components/
|
||
└── ticket-card.vue # 电子票卡片（含 QR 码）
|
||
|
||
pages/ticket-verify/
|
||
└── ticket-verify.vue # B 端核销页面（参考 realstore/check.vue）
|
||
```
|
||
|
||
---
|
||
|
||
## 六、uni.scanCode 扫码能力
|
||
|
||
### 6.1 基础用法
|
||
|
||
```javascript
|
||
// 扫码
|
||
uni.scanCode({
|
||
onlyFromCamera: true, // 只允许相机扫码
|
||
success: (res) => {
|
||
console.log('扫码结果:', res.result);
|
||
// res.result: 扫码内容
|
||
// res.scanType: 二维码类型（QR_CODE 等）
|
||
},
|
||
fail: (err) => {
|
||
console.error('扫码失败', err);
|
||
}
|
||
});
|
||
```
|
||
|
||
### 6.2 在 H5 平台的处理
|
||
|
||
```vue
|
||
<!-- #ifndef H5 -->
|
||
<uni-icons type="scan" size="56rpx" @tap="scan_event"></uni-icons>
|
||
<!-- #endif -->
|
||
|
||
<!-- H5 平台提示手动输入 -->
|
||
<!-- #ifdef H5 -->
|
||
<view class="cr-grey text-size-sm" @tap="show_manual_input">
|
||
请输入核销码
|
||
</view>
|
||
<!-- #endif -->
|
||
```
|
||
|
||
### 6.3 参考实现
|
||
|
||
ShopXO 的 `realstore/check/check.vue` 已完整实现：
|
||
- 扫码触发 → 自动提交验证
|
||
- 手动输入兼容
|
||
- 成功/失败状态显示
|
||
- 连续扫描（核销后清空输入框）
|
||
|
||
---
|
||
|
||
## 七、QR 码展示
|
||
|
||
### 7.1 后端生成 QR 码图片 URL
|
||
|
||
```javascript
|
||
// 生成票务 QR 码 URL
|
||
function getTicketQrUrl(ticketId) {
|
||
const baseUrl = app.globalData.request_url;
|
||
const ticketData = JSON.stringify({
|
||
id: ticketId,
|
||
exp: Date.now() + 30 * 86400 * 1000 // 30天有效期
|
||
});
|
||
const encoded = encodeURIComponent(
|
||
uni.base64ToString(
|
||
uni.stringToBase64(ticketData)
|
||
)
|
||
);
|
||
return `${baseUrl}?s=index/qrcode/index&content=${encoded}&size=8&level=H`;
|
||
}
|
||
```
|
||
|
||
### 7.2 在页面中展示
|
||
|
||
```vue
|
||
<template>
|
||
<view class="ticket-card">
|
||
<image :src="qrCodeUrl" mode="aspectFit" class="qr-image" />
|
||
<view class="ticket-code">{{ ticket.code }}</view>
|
||
</view>
|
||
</template>
|
||
```
|
||
|
||
---
|
||
|
||
## 八、manifest.json 关键配置
|
||
|
||
### 8.1 多端配置
|
||
|
||
```json
|
||
{
|
||
"name": "ShopXO",
|
||
"appid": "__UNI__50E3C11",
|
||
"description": "ShopXO开源商城...",
|
||
"transformPx": false,
|
||
"app-plus": {
|
||
"usingComponents": true,
|
||
"nvueCompiler": "uni-app",
|
||
"distribute": {
|
||
"android": { ... },
|
||
"ios": { ... },
|
||
"mp-weixin": {
|
||
"appid": "wx YOUR APPID",
|
||
"setting": {
|
||
"urlCheck": false,
|
||
"es6": true,
|
||
"minified": true
|
||
},
|
||
"usingComponents": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.2 权限配置（微信小程序）
|
||
|
||
```json
|
||
"mp-weixin": {
|
||
"permission": {
|
||
"scope.userLocation": {
|
||
"desc": "用于场馆定位"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 九、自定义组件注册
|
||
|
||
### 9.1 全局注册（所有页面可用）
|
||
|
||
在 `pages/index/index.vue` 的 `style.usingComponents` 中添加：
|
||
|
||
```json
|
||
"component-ticket-seat": "/pages/ticket-buy/components/seat-selector/seat-selector",
|
||
"component-ticket-card": "/pages/ticket-wallet/components/ticket-card/ticket-card",
|
||
"component-attendee-form": "/pages/ticket-buy/components/attendee-form/attendee-form"
|
||
```
|
||
|
||
### 9.2 页面级注册
|
||
|
||
在单个页面的 `pages.json` 中：
|
||
```json
|
||
{
|
||
"path": "pages/ticket-wallet/ticket-wallet",
|
||
"style": {
|
||
"usingComponents": {
|
||
"component-ticket-card": "/pages/ticket-wallet/components/ticket-card/ticket-card"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 十、ShopXO API 调用
|
||
|
||
### 10.1 请求封装
|
||
|
||
ShopXO uni-app 使用全局封装的请求方法：
|
||
|
||
```javascript
|
||
uni.request({
|
||
url: app.globalData.get_request_url('action', 'controller', 'module'),
|
||
method: 'POST',
|
||
data: { ... },
|
||
success: (res) => {
|
||
if (res.data.code == 0) {
|
||
// 成功
|
||
} else {
|
||
// 失败
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
### 10.2 插件 API 路径
|
||
|
||
对于插件的 API：
|
||
```javascript
|
||
// 格式：get_request_url(action, controller, plugins_name)
|
||
const url = app.globalData.get_request_url(
|
||
'verify', // action
|
||
'adminverify', // controller
|
||
'vrticket' // 插件名（apps 目录下的目录名）
|
||
);
|
||
```
|
||
|
||
### 10.3 鉴权
|
||
|
||
请求自动带上登录态：
|
||
```javascript
|
||
// 已在全局封装，每次请求自动附加：
|
||
// Header: Authorization / Token
|
||
// 或者通过 Session/Cookie
|
||
```
|