葫芦生《赵籁》小程序单页面组件化架构设计
🎯 单页面组件化架构，打造沉浸式历史文化体验
设计理念：采用单页面多组件架构，通过状态管理控制整个体验流程，实现无缝的AR+LBS历史文化交互体验。从摘星选择到历史对话，从两难抉择到哲思领悟，所有交互都在一个页面内完成。
技术优势：交互连贯性强、状态一致性好、动画流畅自然、开发效率高。支持21-29分钟的单章节深度体验，完整7章节可提供2.5-3.5小时的历史文化之旅。
1. 架构概述
🎯 核心理念
- 一个主页面：
pages/explore/explore作为唯一的体验页面 - 组件化交互：所有交互环节都是组件，通过状态管理切换
- 流畅过渡：组件间无缝切换，保持沉浸感
- 状态驱动：全局状态管理控制整个体验流程
🌟 设计优势
- ✅ 交互连贯性：无页面跳转，保持沉浸式体验
- ✅ 状态一致性：全局状态管理，数据同步简单
- ✅ 动画流畅性：组件间过渡动画更自然
- ✅ 开发效率：组件复用，逻辑集中
2. 页面架构关系
📱 页面结构
pages/
小程序页面目录
index/index
启动检查页（简单登录检查）
explore/explore
核心体验页（主战场）
核心
profile/profile
用户档案页（独立功能）
achievements/achievements
成就页面（独立功能）
🏗️ 核心页面架构图
index 启动页
explore 核心体验页
摘星选择组件
葫芦创建组件
地图探索组件
AR识别组件
历史交互组件群
profile 用户档案
achievements 成就页
3. 组件设计
🧩 组件层级结构
components/
核心组件目录
initialization/
初始化组件群
star-selector/
摘星选择组件
gourd-creator/
葫芦生成组件
exploration/
探索组件群
map-explorer/
地图探索组件（基础层）
ar-scanner/
AR识别组件
interaction/
历史交互组件群
chapter-prologue/
篇章报幕组件
npc-presenter/
NPC展示组件
dilemma-solver/
两难问题组件
regret-comforter/
遗憾安慰组件
wisdom-receiver/
哲思领悟组件
chapter-epilogue/
篇章总结组件
growth-summary/
成长总结组件
common/
通用组件
floating-modal/
浮动弹窗
progress-bar/
进度条
attribute-display/
属性展示
loading-spinner/
加载动画
transition-wrapper/
过渡动画包装器
⚙️ 组件职责划分
基础层组件
- map-explorer：地图显示、定位、点位标记
- floating-modal：承载所有历史交互内容的弹窗容器
初始化组件
- star-selector：北斗七星选择，Canvas绘制
- gourd-creator：葫芦生成动画，属性展示
交互流程组件
- chapter-prologue：篇章开场，历史背景介绍
- npc-presenter：历史人物展示，时空连线动画
- dilemma-solver：两难问题展示，策略选择
- regret-comforter：人生遗憾倾听，安慰选择
- wisdom-receiver：哲思智慧获得，礼物接收
- chapter-epilogue：篇章总结，历史教育价值
- growth-summary：属性成长，奖励展示
4. 状态管理
🗂️ 全局状态结构
const globalState = {
// 用户状态
user: {
isLoggedIn: false,
hasGourd: false,
userInfo: {},
currentGourd: {
id: null,
name: '',
attributes: {
strategy: 0, // 谋略
warfare: 0, // 兵法
benevolence: 0, // 仁德
chivalry: 0, // 侠义
versatility: 0 // 纵横
}
}
},
// 体验进度状态
experience: {
currentStage: 'map_explore', // 当前体验阶段
currentChapter: null, // 当前篇章
currentNPC: null, // 当前NPC
currentDilemma: null, // 当前两难问题
completedChapters: [], // 已完成篇章
totalProgress: 0 // 总体进度百分比
},
// 交互数据状态
interaction: {
isActive: false, // 是否正在交互
sessionData: {}, // 当前会话数据
accumulatedRewards: { // 累积奖励
attributes: {},
experience: 0,
items: [],
achievements: []
}
},
// UI状态
ui: {
showModal: false, // 是否显示弹窗
modalContent: '', // 弹窗内容类型
loading: false, // 加载状态
currentAnimation: null, // 当前动画
backgroundMusic: null // 背景音乐状态
}
}
5. 体验流程
🎮 体验阶段流程图
摘星选择
葫芦生成
地图探索
AR识别
篇章报幕
NPC展示
两难问题
遗憾安慰
哲思领悟
篇章总结
成长总结
📊 用户全流程时序图
sequenceDiagram
participant U as 用户
participant MP as 小程序
participant CS as 组件系统
participant SM as 状态管理
participant API as 后端API
Note over U,API: 🚀 初始化阶段 (2-3分钟)
U->>MP: 启动小程序
MP->>API: 检查用户登录状态
API-->>MP: 返回用户信息
MP->>SM: 初始化全局状态
alt 用户无葫芦
MP->>CS: 显示摘星组件
U->>CS: 选择北斗七星 (1分钟)
CS->>SM: 计算属性值
CS->>CS: 切换到葫芦生成组件
CS->>API: 保存葫芦数据
end
CS->>CS: 切换到地图探索组件
Note over U,API: 🗺️ 地图探索阶段 (1-5分钟)
U->>CS: 查看地图和点位
CS->>API: 获取活动点位数据
U->>MP: 移动到历史点位
MP->>SM: 更新位置状态
alt 到达触发范围
SM->>CS: 触发AR组件
end
Note over U,API: 📱 AR识别阶段 (1分钟)
U->>CS: 启动相机扫描
CS->>API: 验证AR标记
API-->>CS: 返回篇章数据
CS->>SM: 更新交互状态
CS->>CS: 显示篇章报幕组件
Note over U,API: 🎭 历史交互阶段 (15-18分钟)
U->>CS: 观看篇章报幕 (2分钟)
CS->>API: 获取NPC数据
CS->>CS: 显示NPC展示组件
U->>CS: 与历史人物对话 (2分钟)
CS->>CS: 显示两难问题组件
U->>CS: 选择策略方案 (5分钟)
CS->>API: 提交策略选择
API-->>CS: 返回选择结果
CS->>CS: 显示遗憾安慰组件
U->>CS: 安慰历史人物 (3分钟)
CS->>CS: 显示哲思领悟组件
U->>CS: 接受智慧礼物 (2分钟)
CS->>CS: 显示篇章总结组件
U->>CS: 观看历史总结 (3分钟)
Note over U,API: 📈 成长总结阶段 (2分钟)
CS->>SM: 计算属性提升
CS->>CS: 显示成长总结组件
U->>CS: 查看成长报告 (2分钟)
CS->>API: 保存进度数据
CS->>CS: 返回地图探索组件
Note over U,API: 🔄 循环探索
loop 继续探索其他篇章
U->>CS: 继续探索下一篇章...
end
📋 详细阶段说明
初始化阶段
2-3分钟
用户登录、摘星选择、葫芦生成
地图探索
1-5分钟
查看地图、移动到历史点位
AR识别
1分钟
相机扫描、验证AR标记
历史交互
15-18分钟
NPC对话、两难问题、遗憾安慰、哲思领悟
成长总结
2分钟
属性提升、进度保存
循环探索
持续
探索其他历史篇章
⏱️ 单次完整体验时长
初始化阶段：2-3分钟 | 地图探索：1-5分钟 | AR识别：1分钟 | 历史交互：15-18分钟 | 成长总结：2分钟
总计：约21-29分钟/篇章
完成全部7个篇章预计需要：2.5-3.5小时
6. 技术实现
🖥️ UI渲染方案（推荐：混合方案）
主页面结构
<!-- pages/explore/explore.wxml -->
<view class="explore-container">
<!-- 基础层：始终存在的地图 -->
<map-explorer
wx:if="{{showMapBase}}"
bind:pointClick="onPointClick"
bind:locationUpdate="onLocationUpdate" />
<!-- 初始化层：条件渲染 -->
<star-selector
wx:if="{{currentStage === 'star_selection'}}"
bind:complete="onStarSelectionComplete" />
<gourd-creator
wx:if="{{currentStage === 'gourd_creation'}}"
bind:complete="onGourdCreationComplete" />
<!-- 交互层：浮动弹窗承载 -->
<floating-modal
wx:if="{{showModal}}"
title="{{modalTitle}}"
bind:close="onModalClose">
<!-- 历史交互组件：条件渲染 -->
<chapter-prologue
wx:if="{{currentStage === 'chapter_prologue'}}"
chapter="{{currentChapter}}"
bind:complete="onPrologueComplete" />
// ... 其他交互组件
</floating-modal>
</view>
7. 架构方案对比
| 方案 | 优势 | 劣势 | 适用场景 |
|---|---|---|---|
| 纯组件条件渲染 |
✅ 实现简单 ✅ 状态管理清晰 ✅ 动画过渡容易 |
❌ 内存占用大 ❌ 首次加载慢 |
简单应用 |
| 动态组件加载 |
✅ 按需加载 ✅ 性能更好 ✅ 组件独立性强 |
❌ 实现复杂 ❌ 数据传递困难 ❌ 动画实现困难 |
大型应用 |
| 混合方案 ⭐ |
✅ 平衡性能和复杂度 ✅ 核心体验流畅 ✅ 便于维护扩展 |
❌ 需要合理规划 | 推荐方案 |
🏆 推荐方案：混合架构
采用混合方案，以pages/explore/explore为核心页面，通过组件化和状态管理实现完整的历史文化体验流程。这种架构既保证了用户体验的连贯性，又兼顾了开发效率和性能优化。
🚀 下一步行动计划
- 确认架构方案：基于以上分析确定最终技术方案
- 创建基础结构：建立页面和组件的基础框架
- 实现状态管理：构建全局状态管理系统
- 开发核心组件：优先实现地图探索和基础交互
- 集成测试：验证组件间的协作和数据流转