简介

本文件面向前端开发者，系统化说明 DouPHP 小程序的样式系统与主题机制。内容涵盖：

• 样式架构：全局样式、WeUI 变量体系、图标字体、组件样式与页面样式的组织方式
• 主题定制：颜色方案、字体设置、图标资源管理
• 样式复用策略：公共样式、组件样式、页面样式的分层与引用
• 响应式与移动端适配：导航栏高度、状态栏、胶囊按钮区域等
• 多主题切换：基于 CSS 变量的动态主题与用户偏好持久化思路
• 调试工具与常见问题：开发期调试开关、错误捕获、页面未找到提示等

项目结构

小程序默认模板位于 miniprogram/default，样式相关的关键位置如下：

• 应用级入口与配置：app.json（页面路由、窗口、TabBar）、app.ts（启动流程、全局信息）
• 全局样式：app.wxss（引入 WeUI、图标字体，定义基础布局与通用类）
• 第三方样式：style/weui.wxss（WeUI 主题变量、浅色/深色模式）
• 图标字体：style/iconfont.wxss（统一图标资源）
• 组件样式：components/navbar/navbar.wxss（自定义导航栏）
• 站点运行配置：config/site.ts（根地址、API 地址、全局 loading 开关等）

graph TB
A["app.json<br/>页面/窗口/TabBar"] --> B["app.wxss<br/>全局样式"]
B --> C["style/weui.wxss<br/>WeUI 变量与主题"]
B --> D["style/iconfont.wxss<br/>图标字体"]
B --> E["components/navbar/navbar.wxss<br/>导航栏组件样式"]
F["app.ts<br/>启动/全局信息"] --> G["config/site.ts<br/>站点运行配置"]
A --> H["pages/*<br/>页面样式(按模块划分)"]

核心组件

• 全局样式层（app.wxss）
  • 引入 WeUI 与图标字体，提供基础重置、常用布局容器、列表、表单、按钮、价格展示等通用类
  • 通过固定头部、侧边栏、主内容区等组合实现常见页面骨架
• 主题变量层（weui.wxss）
  • 使用 CSS 变量定义背景、前景、品牌色、标签色等，支持 light/dark/care 多种主题
  • 通过 data-weui-theme 与 data-weui-mode 切换主题与模式
• 导航栏组件（navbar.wxss）
  • 自定义导航栏，兼容系统状态栏与右上角胶囊按钮区域，避免内容被遮挡
• 站点配置（site.ts）
  • 集中暴露 root_url、mp_url、douLoading、debug_enable、rewrite_enable 等运行时常量
• 应用启动（app.ts）
  • 初始化全局尺寸（状态栏高度、导航栏高度），开启自动更新，非正式版启用 vConsole，统一错误处理

架构总览

小程序样式采用“全局 + 组件 + 页面”的分层组织，结合 WeUI 的 CSS 变量体系实现主题化。

graph TB
subgraph "应用层"
APP["app.ts<br/>启动/全局信息"]
CFG["config/site.ts<br/>站点配置"]
end
subgraph "样式层"
GWXSS["app.wxss<br/>全局样式"]
WUI["style/weui.wxss<br/>WeUI 变量/主题"]
ICON["style/iconfont.wxss<br/>图标字体"]
NAV["components/navbar/navbar.wxss<br/>导航栏"]
end
subgraph "页面层"
PAGES["pages/*<br/>各页面样式"]
end
APP --> CFG
APP --> GWXSS
GWXSS --> WUI
GWXSS --> ICON
GWXSS --> NAV
GWXSS --> PAGES

详细组件分析

全局样式（app.wxss）

• 作用
  • 引入 WeUI 与图标字体，统一基础样式
  • 定义常用布局容器（body/wrap/padding-y 等）、网格列表、搜索胶囊条、详情区块、订单列表、表单控件、按钮、导航栏、页头等
• 设计要点
  • 使用 Flex 布局与百分比宽度实现响应式卡片与列表
  • 价格、标签、按钮等高频元素提供语义化类名，便于跨页面复用
  • 通过固定头部与侧边实现复杂页面的骨架布局

flowchart TD
Start(["页面加载"]) --> Import["引入 weui.wxss / iconfont.wxss"]
Import --> Base["基础重置与全局类"]
Base --> Layout["布局容器/网格/列表/详情"]
Layout --> UI["表单/按钮/导航/页头"]
UI --> Page["页面按需复用"]

主题变量（weui.wxss）

• 主题模型
  • 通过 data-weui-theme 控制 light/dark 主题
  • 通过 data-weui-mode 控制 care 等辅助模式
• 变量体系
  • 背景色系列：--weui-BG-0 ~ --weui-BG-5
  • 前景色系列：--weui-FG-0 ~ --weui-FG-5
  • 品牌与强调色：--weui-BRAND、--weui-RED、--weui-BLUE 等
  • 标签文本与背景：--weui-TAG-TEXT- / --weui-TAG-BACKGROUND-
• 使用建议
  • 业务样式优先使用这些变量，避免硬编码颜色
  • 在页面或组件中通过父节点设置 data-weui-theme 即可切换主题

classDiagram
class WeUITheme {
"+light 主题变量"
"+dark 主题变量"
"+care 模式变量"
"+data-weui-theme 切换"
"+data-weui-mode 切换"
}
class AppStyle {
"+使用 --weui-* 变量"
"+覆盖局部配色"
}
WeUITheme <.. AppStyle : "被引用"

导航栏组件（navbar.wxss）

• 功能
  • 自定义导航栏，兼容系统状态栏与右上角胶囊按钮区域
  • 左侧返回/菜单、居中标题、右侧操作项
• 适配要点
  • 通过 padding-right 预留胶囊区域，避免内容被遮挡
  • 使用绝对定位与 z-index 保证层级正确

sequenceDiagram
participant P as "页面"
participant N as "navbar 组件"
participant S as "系统导航栏"
P->>N : 渲染导航栏
N->>S : 读取状态栏/胶囊高度
N->>N : 计算左右间距与标题位置
N-->>P : 显示可交互的导航栏

站点配置（site.ts）

• 职责
  • 集中暴露站点运行时的关键常量：root_url、mp_url、douLoading、debug_enable、rewrite_enable
• 使用方式
  • 业务模块直接 import 使用，避免分散配置导致不一致

应用启动与全局信息（app.ts）

• 职责
  • 初始化全局尺寸（状态栏高度、导航栏高度、胶囊高度）
  • 开启自动更新、非正式版启用 vConsole
  • 统一错误处理（JS 异常、Promise 拒绝、页面未找到）
  • 解析推广参数并写入本地缓存
• 对样式的影响
  • 为导航栏与页面顶部留出正确的安全区域，避免内容被系统 UI 遮挡

sequenceDiagram
participant WX as "微信环境"
participant APP as "App(app.ts)"
participant STORE as "Stores"
participant HTTP as "HTTP 拦截器"
WX->>APP : onLaunch
APP->>HTTP : 注册 onError(UNAUTHORIZED)
APP->>STORE : bootstrapStores()
APP->>WX : 获取 windowInfo/deviceInfo/menuButtonBoundingClientRect
APP->>APP : 计算 statusBarHeight/navigationBarHeight
APP->>WX : canIUse getUpdateManager?
APP->>WX : isDebugEnv? setEnableDebug(true)

依赖关系分析

• app.wxss 依赖 weui.wxss 与 iconfont.wxss，作为全局样式入口
• navbar.wxss 作为组件样式被页面引入，依赖全局尺寸信息（由 app.ts 计算）
• app.json 声明 TabBar 与 usingComponents，影响整体视觉与导航行为
• site.ts 被 app.ts 与其他服务/页面引用，提供统一的站点地址与调试开关

graph LR
WXSS["app.wxss"] --> WEUI["weui.wxss"]
WXSS --> ICON["iconfont.wxss"]
WXSS --> NAV["navbar.wxss"]
JSON["app.json"] --> WXSS
TS["app.ts"] --> CFG["site.ts"]
NAV --> TS

性能与兼容性

• 性能优化
  • 将 WeUI 与图标字体放在全局样式中一次性引入，减少重复加载
  • 使用 CSS 变量替代大量条件样式，降低样式体积与重排
  • 图片资源尽量使用雪碧图或矢量图标，减少请求数
• 兼容性处理
  • 通过 app.ts 获取系统信息，计算导航栏高度，适配不同机型与平台差异
  • 使用 WeUI 提供的主题变量，确保在不同主题下的一致性与可读性
• 移动端适配
  • 利用 rpx 与百分比布局，配合 flex 与 grid-list 实现自适应卡片与列表
  • 导航栏预留胶囊区域，避免内容被系统 UI 遮挡

故障排查指南

• 调试开关
  • 非正式版自动开启 vConsole，便于查看日志与网络请求
  • 可通过 config/site.ts 中的 debug_enable 控制调试能力
• 错误捕获
  • 全局 JS 异常与未处理的 Promise 拒绝会输出到控制台；调试模式下弹窗提示
  • 页面未找到时记录路径，便于快速定位拼写错误
• 常见问题
  • 导航栏被遮挡：检查是否正确使用 app.ts 计算的导航栏高度，并在组件中预留胶囊区域
  • 主题不生效：确认是否在根节点设置了 data-weui-theme，且样式优先级正确

结论

DouPHP 小程序的样式系统以 WeUI 的 CSS 变量为核心，结合全局样式与组件样式，实现了清晰的主题化与高复用性。通过 app.ts 的全局尺寸计算与调试能力，保障了多机型的兼容性与开发效率。遵循本文的组织与最佳实践，可高效扩展新页面与主题。

附录：多主题切换方案

• 动态主题
  • 在根节点设置 data-weui-theme="light|dark|care"，即可切换主题
  • 业务样式应优先使用 --weui-* 变量，避免硬编码颜色
• 用户偏好保存
  • 可在 app.ts 启动时读取本地存储的用户主题偏好，并设置到根节点
  • 用户切换主题后，将选择结果持久化到 storage，下次启动自动恢复
• 图标与资源
  • 图标统一通过 iconfont.wxss 引入，避免多份资源冗余
  • 图片资源按主题区分命名，按需加载

sequenceDiagram
participant U as "用户"
participant A as "App(app.ts)"
participant R as "根节点"
U->>A : 选择主题(亮/暗/关怀)
A->>A : 写入 storage(主题键)
A->>R : 设置 data-weui-theme
R-->>U : 界面即时切换