简介
本文件面向 DouPHP 小程序的“组件样式与主题系统”，聚焦以下目标：
- 梳理样式架构：CSS 模块化组织、样式继承机制、主题变量体系。
- 指导如何自定义组件样式：覆盖默认样式、添加自定义类名、使用 CSS 变量。
- 提供主题切换方案：明暗主题、品牌色定制等。
- 说明响应式设计：适配不同屏幕尺寸与设备类型。
- 给出样式性能优化技巧：复用、减少重绘重排、按需加载等。
- 提供调试工具与最佳实践，以及跨平台兼容性与浏览器差异处理建议。
项目结构
小程序端包含两套可独立维护的主题/模板：default（默认）与 company（企业）。每套模板均具备：
- app.wxss：全局样式入口，统一引入基础样式与图标字体，并定义页面级初始化、通用布局与组件样式。
- style/weui.wxss：WeUI 样式库，内置明暗主题变量与媒体查询断点。
- config/site.ts：站点级运行配置（如 API 地址、调试开关等），便于运行时注入。
graph TB
A["小程序应用<br/>app.wxss"] --> B["基础样式库<br/>style/weui.wxss"]
A --> C["图标字体<br/>style/iconfont.wxss"]
A --> D["业务通用样式<br/>app.wxss 中 .grid-list/.detail/.btn 等"]
E["站点配置<br/>config/site.ts"] -.-> A核心组件
- 全局样式入口（app.wxss）
- 负责引入 WeUI 与图标字体，设置 page 背景、字号、颜色等基础样式。
- 提供通用布局与组件样式，如 grid-list、text-list、detail、order-item-list、btn、navbar、page-head 等。
- 主题变量（weui.wxss）
- 通过 data-weui-theme 选择器切换明/暗主题，集中管理背景、前景、强调色等变量。
- 支持 care 模式与多色板（红/橙/绿/蓝/品牌色等）。
- 站点配置（site.ts）
- 暴露根域名、API 地址、调试开关等，供前端逻辑在运行时读取。
架构总览
小程序样式采用“全局入口 + 主题库 + 业务样式”的分层组织：
- 入口层：app.wxss 统一引入基础样式与图标字体，定义页面级初始化和通用组件样式。
- 主题层：weui.wxss 以 CSS 变量为核心，通过 data-weui-theme 实现明暗主题切换，并提供丰富的语义化变量。
- 业务层：各页面/组件通过组合基础类名与业务类名构建界面，必要时覆盖或扩展默认样式。
sequenceDiagram
participant App as "应用入口<br/>app.wxss"
participant Theme as "主题库<br/>weui.wxss"
participant Biz as "业务样式<br/>app.wxss"
participant Page as "页面/组件"
App->>Theme : 引入 WeUI 样式与主题变量
App->>Biz : 引入业务通用样式
Page->>App : 使用 .grid-list/.detail/.btn 等类
Page->>Theme : 通过 data-weui-theme 切换明/暗主题
Note over Theme,Page : 主题变量变更驱动 UI 整体换肤详细组件分析
全局样式与通用组件（app.wxss）
- 初始化与基础布局
- 设置 page 背景、字号、颜色；统一 box-sizing；定义 wrap、padding-y、pb 等间距类。
- 列表与详情
- grid-list：网格列表，含图片、标题、描述、标签、价格行等子块。
- text-list：图文列表，支持无图模式与右侧图片定位。
- detail：详情页容器，含标题、信息、图片、视频、内容区等。
- 表单与按钮
- btn/btn-gray/btn-mini/btn-payment：统一按钮风格与尺寸。
- text-input/text-area/text-area-auto：输入框与文本域样式。
- 导航与页面头
- navbar：固定顶部导航，支持滚动与静态布局。
- page-head：页面头部区域，支持副标题与操作按钮。
- 订单与购物车
- order-item-list：订单/购物车条目，支持删除、属性标签、数量加减等。
flowchart TD
Start(["页面渲染"]) --> UseGrid["使用 .grid-list 展示商品/内容"]
UseGrid --> UseDetail["进入 .detail 查看详情"]
UseDetail --> UseForm["使用 .text-input/.text-area 进行交互"]
UseForm --> UseBtn["点击 .btn 触发操作"]
UseBtn --> End(["完成交互"])主题系统与变量（weui.wxss）
- 主题变量
- 通过 [data-weui-theme=light] 与 [data-weui-theme=dark] 分别定义背景、前景、强调色等变量族（--weui-BG-、--weui-FG-、--weui-BRAND 等）。
- 支持 care 模式，调整对比度与色彩饱和度以提升可读性。
- 按钮与交互态
- 按钮激活遮罩、默认激活背景在不同主题下自动适配。
- 媒体查询与断点
- 内置针对常见设备宽度的 @media 规则，用于微调布局与排版。
classDiagram
class 主题变量 {
"--weui-BG-0"
"--weui-BG-1"
"--weui-FG-0"
"--weui-FG-1"
"--weui-BRAND"
"--weui-BLUE"
"--weui-RED"
}
class 主题开关 {
"data-weui-theme=light"
"data-weui-theme=dark"
}
class 组件样式 {
".btn"
".weui-input__placeholder"
".grid-list"
}
主题开关 --> 主题变量 : "选择变量集"
组件样式 --> 主题变量 : "引用变量"站点配置（site.ts）
- 作用：集中管理站点级运行数据，如根域名、小程序 API 地址、调试开关、重写开关等。
- 使用方式：在业务代码中直接导入并使用，避免硬编码 URL 与开关。
依赖关系分析
- app.wxss 依赖 weui.wxss 与 iconfont.wxss，形成“基础样式 + 图标资源”的依赖链。
- 业务样式（app.wxss 中的组件类）依赖主题变量，从而与 weui.wxss 的主题系统耦合。
- 站点配置 site.ts 为运行时配置，不直接参与样式渲染，但影响网络请求与调试行为。
graph LR
Site["站点配置<br/>site.ts"] -.-> App["应用入口<br/>app.wxss"]
App --> WeUI["主题库<br/>weui.wxss"]
App --> Icon["图标字体<br/>iconfont.wxss"]
App --> Biz["业务样式<br/>app.wxss 组件类"]性能考虑
- 样式复用
- 优先使用已定义的通用类（如 .grid-list、.btn、.navbar），减少重复样式。
- 将高频使用的样式抽取为公共类，提升一致性并降低体积。
- 减少重绘重排
- 避免频繁修改 layout-affecting 属性（如 width、height、margin、padding），优先使用 transform 与 opacity 做动画。
- 合理使用 will-change 与硬件加速，但谨慎使用以避免内存占用。
- 按需加载
- 将非首屏所需的样式拆分到页面级样式文件中，减少全局包体。
- 对大型第三方样式（如 WeUI）仅引入必要模块或使用裁剪后的版本。
- 主题切换开销
- 通过切换 data-weui-theme 属性一次性更新主题变量，避免逐元素修改样式。
- 将主题切换逻辑放在应用启动或用户设置处，减少运行时频繁切换。
故障排查指南
- 主题未生效
- 检查是否设置了正确的 data-weui-theme 属性（light/dark）。
- 确认 weui.wxss 已被正确引入且未被后续样式覆盖。
- 样式冲突
- 使用开发者工具的“计算样式”查看最终生效的样式来源，定位覆盖顺序问题。
- 提高选择器特异性时需谨慎，避免破坏主题变量体系。
- 响应式异常
- 检查 @media 断点是否与目标设备匹配，必要时增加更细粒度的断点。
- 注意不同小程序内核对某些 CSS 属性的支持差异，必要时降级处理。
- 调试技巧
- 开启 debug_enable 后，可在控制台输出更多日志，辅助定位问题。
- 使用站点配置中的 mp_url 与 root_url 校验接口与资源路径是否正确。
结论
DouPHP 小程序的样式与主题系统以 app.wxss 为入口、weui.wxss 为主题核心、业务样式为扩展，形成了清晰的分层与良好的可扩展性。通过 CSS 变量与 data-weui-theme 实现主题切换，结合统一的组件类名与响应式断点，能够快速构建一致、可维护的小程序界面。建议在开发中遵循样式复用、按需加载与最小化重绘的原则，并结合调试工具持续优化体验。
附录
如何自定义组件样式
- 覆盖默认样式
- 在页面或组件样式文件中，使用更高特异性的选择器覆盖 app.wxss 中的通用类。
- 示例：为 .btn 添加业务前缀类，再在其中覆盖颜色与尺寸。
- 添加自定义类名
- 为复杂组件创建专属类名（如 .my-card），并在其中组合基础类名与业务样式。
- 使用 CSS 变量
- 通过 --weui-BRAND、--weui-BG-、--weui-FG- 等变量统一品牌色与明暗主题。
- 在需要时扩展自定义变量，并在多处引用以保证一致性。
主题切换实现方案
- 明暗主题
- 在根节点设置 data-weui-theme="light" 或 "dark"，即可切换整套主题变量。
- 品牌色定制
- 通过覆盖 --weui-BRAND 及相关强调色变量，实现品牌色替换。
- Care 模式
- 启用 care 模式以提升对比度与可读性，适合无障碍场景。
响应式设计方法
- 使用内置断点
- weui.wxss 中包含针对常见设备宽度的 @media 规则，可直接利用。
- 自定义断点
- 根据业务需求新增 @media 规则，适配不同屏幕尺寸与方向变化。
- 设备差异
- 针对不同小程序内核与设备特性，提供降级样式与回退方案。
跨平台兼容性与浏览器差异
- 兼容性
- 优先使用标准 CSS 属性，避免实验性特性；对不支持的属性提供降级样式。
- 差异处理
- 针对 iOS/Android 与不同小程序内核的差异，使用条件样式或检测逻辑进行适配。
- 测试建议
- 在多设备与多内核下进行真机测试，确保样式表现一致。