组件分类与职责 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

组件分类与职责

简介

本技术文档围绕 DouPHP 小程序的“组件分类与职责”展开，目标是明确基础组件、业务组件、通用组件的分类标准与设计原则，界定各类组件的职责边界，并给出合理的粒度划分建议。结合仓库中实际的小程序工程结构，重点说明 UI 基础组件（如导航栏）、业务逻辑组件（如商品卡片、订单列表）以及通用工具组件（如导航栏、弹窗）的实现模式与组织方式，帮助团队在统一规范下高效协作与维护。

项目结构

DouPHP 小程序采用多主题/多实例的组织方式：default 与 company 两套独立的小程序工程，各自包含 pages、components、services、stores、utils、style 等目录，便于按品牌或客户进行差异化定制。全局配置通过 app.json 声明页面路由、窗口样式、tabBar 以及 usingComponents 中的全局组件注册。

graph TB
A["小程序入口<br/>app.json"] --> B["页面层<br/>pages/*"]
A --> C["组件层<br/>components/*"]
A --> D["服务层<br/>services/*"]
A --> E["状态管理<br/>stores/*"]
A --> F["工具库<br/>utils/*"]
C --> G["通用组件<br/>navbar"]
B --> H["业务页面<br/>product / order / user ..."]
D --> I["HTTP / 上传 / 权限 等服务"]
E --> J["用户/购物车/公共状态"]

核心组件

通用组件：navbar（导航栏），提供标题、返回、首页、自定义插槽、滚动透明度、调试入口等功能，作为跨页面复用的基础 UI 能力。
业务组件：以页面级聚合形态存在，例如 product（商品相关页面）、order（订单相关页面），承载具体业务数据展示与交互流程。
基础组件：由微信原生组件与少量自封装组合而成，如 view、image、button 等，用于构建更细粒度的 UI 元素。

职责边界建议

通用组件：不感知业务上下文，仅暴露属性与事件；关注可复用性与一致性。
业务组件：封装特定业务场景的视图与交互，必要时向上抛出事件，向下调用 services/stores。
基础组件：只负责最小粒度的 UI 表现与简单交互，避免业务耦合。

架构总览

小程序整体遵循“页面-组件-服务-状态-工具”的分层模型：

页面层：负责路由与页面级状态编排，组合通用/业务组件完成完整业务流程。
组件层：按通用、业务、基础三级拆分，保证高内聚低耦合。
服务层：封装 HTTP、上传、权限校验等跨页面能力。
状态管理：集中管理用户、购物车、公共信息等状态。
工具库：环境判断、格式化、路由、UI 辅助等。

sequenceDiagram
participant P as "页面"
participant N as "通用组件 navbar"
participant S as "服务层 services"
participant ST as "状态 stores"
participant U as "工具 utils"
P->>N : 渲染导航栏(标题/颜色/插槽)
N->>U : 获取环境/路由工具
P->>S : 发起业务请求(商品/订单)
S-->>P : 返回数据
P->>ST : 更新本地状态
P->>N : 触发返回/首页等事件
N->>U : 执行跳转/切换Tab

详细组件分析

通用组件：导航栏（navbar）

功能要点
- 支持标题、背景色、标题色、滚动透明度控制。
- 提供 left/center/right 插槽，未传 center 时回退为默认标题。
- 内置返回与首页按钮，支持自定义返回 URL。
- 调试入口圆点：在非正式版且服务端调试开启时显示，点击进入调试页。
设计原则
- 无业务耦合：仅处理导航与 UI 行为，业务逻辑交由页面与服务层。
- 可配置化：通过 properties 暴露常用样式与行为开关。
- 可扩展性：插槽机制允许页面注入左侧/右侧内容。
使用示例路径
- 在 app.json 中全局注册 usingComponents，页面直接引用。
- 页面 WXML 中通过 <navbar title="..." backgroundColor="#fff" showMenu="{{true}}">...</navbar> 使用。

classDiagram
class Navbar {
+properties : title, backgroundColor, titleColor, scrollOpacity, url, showMenu
+data : statusBarHeight, navigationBarHeight, navigationBarHeightHalf, menuButtonHeight, navigationBarAndStatusBarHeight, debugDot
+methods : goBack(), goHome(), openDebug()
}
class Utils {
+isDebugEnv()
+isServerDebug()
+douPageTo(url)
}
Navbar --> Utils : "调用环境与路由工具"

业务组件：商品相关页面（product）

职责边界
- 展示商品详情/列表、编辑表单、工作流视图等。
- 协调 services 获取数据，更新 stores 状态，驱动 UI 渲染。
- 与通用组件（navbar）组合，保持统一的导航体验。
典型流程
- 页面加载 -> 调用服务获取商品数据 -> 更新本地状态 -> 渲染视图 -> 用户交互（加入购物车/编辑/分享）。
代码示例路径
- 商品列表/详情页逻辑参考：miniprogram/default/pages/product/product.ts

业务组件：订单相关页面（order）

职责边界
- 订单列表、下单结算、支付结果、线下支付、订单详情、用户订单管理等。
- 与 services 交互完成下单、查询、支付回调；与 stores 同步订单状态。
典型流程
- 选择商品 -> 进入 checkout -> 提交订单 -> 支付 -> 成功页展示。
代码示例路径
- 订单主流程逻辑参考：miniprogram/default/pages/order/order.ts

基础组件：UI 基础元素

范围
- 基于微信原生 view/image/button/input 等构建的最小 UI 单元。
- 通常被通用组件或业务组件组合使用，不包含复杂业务逻辑。
设计原则
- 单一职责：只负责展示与简单交互。
- 可复用：通过 props 控制外观与行为，避免硬编码。
- 易测试：纯函数式或轻量方法，便于单元测试。

（本节为概念性说明，不直接分析具体文件）

依赖关系分析

组件对工具的依赖
- navbar 依赖 utils/env.js 与 utils/ui.js，用于环境判断与页面跳转。
页面与服务的依赖
- product/order 页面依赖 services/http、services/upload、services/permission 等，完成数据获取与权限控制。
全局配置
- app.json 中 usingComponents 将 navbar 注册为全局可用组件，减少重复引入成本。

graph LR
subgraph "页面"
P1["product.ts"]
P2["order.ts"]
end
subgraph "组件"
C1["navbar.ts"]
end
subgraph "工具"
U1["utils/env.ts"]
U2["utils/ui.ts"]
end
subgraph "服务"
S1["services/http.ts"]
S2["services/upload.ts"]
S3["services/permission.ts"]
end
P1 --> S1
P2 --> S1
P1 --> S2
P2 --> S2
P1 --> S3
P2 --> S3
C1 --> U1
C1 --> U2

性能考量

组件粒度
- 将高频复用的 UI 片段抽取为通用组件，减少重复渲染与逻辑冗余。
- 业务组件尽量保持轻，复杂逻辑下沉到 services/stores。
渲染优化
- 合理使用 wx:if/wx:for，避免不必要的重绘。
- 长列表使用虚拟滚动或分页加载，降低首屏压力。
网络与缓存
- 接口请求合并与缓存策略，减少重复请求。
- 图片资源按需加载与压缩，提升加载速度。
状态管理
- 将跨页面共享的状态放入 stores，避免页面间传递过多参数。

（本节为通用指导，不直接分析具体文件）

故障排查指南

导航异常
- 检查 navbar 的 properties 是否正确传入（title、url、showMenu）。
- 确认 douPageTo 与 navigateBack 的使用场景是否匹配当前栈深度。
调试入口不显示
- 确认客户端非正式版与服务端调试开关同时满足条件。
页面无法跳转
- 核对 app.json 中 pages 列表是否包含目标页面路径。
- 检查 tabBar 配置与 switchTab 的使用限制。

结论

通过清晰的组件分层与职责边界，DouPHP 小程序实现了高内聚、低耦合的可维护架构。通用组件聚焦可复用 UI 能力，业务组件专注领域逻辑编排，基础组件保障最小粒度的 UI 表达。配合 services/stores/utils 的分层设计，既能快速迭代业务，又能保证一致的用户体验与良好的性能表现。建议在后续开发中持续遵循本规范，逐步沉淀更多通用组件与最佳实践。

附录

命名规范
- 组件：小写下划线或驼峰均可，但需保持一致；通用组件建议以功能命名（如 navbar）。
- 页面：按业务域划分目录，文件名与路由一致（如 product、order）。
- 服务：动词+名词（如 http、upload、permission）。
- 工具：描述性命名（如 env、ui、format）。
目录组织
- miniprogram/{theme}/components：通用组件
- miniprogram/{theme}/pages：业务页面
- miniprogram/{theme}/services：跨页面服务
- miniprogram/{theme}/stores：状态管理
- miniprogram/{theme}/utils：工具函数
- miniprogram/{theme}/style：样式文件
代码示例路径
- 导航栏实现：miniprogram/default/components/navbar/navbar.wxml、miniprogram/default/components/navbar/navbar.ts
- 商品页面：miniprogram/default/pages/product/product.ts
- 订单页面：miniprogram/default/pages/order/order.ts
- 全局组件注册：miniprogram/default/app.json、miniprogram/company/app.json

添加日期：2026-10-05