简介
本文件面向 DouPHP 小程序的通用 UI 组件，聚焦于项目中已实现并可复用的基础能力：导航栏组件与富文本渲染组件。文档覆盖组件属性、事件、插槽、样式定制、无障碍与国际化要点，并提供使用示例路径与常见问题解决方案，帮助开发者快速集成与扩展。
项目结构
小程序端通用 UI 组件位于 miniprogram/default/components 目录下，当前包含：
- navbar：可配置标题、背景色、滚动透明度、返回/首页菜单等能力的导航栏组件
- mp-html：基于节点的富文本渲染容器，支持图片懒加载、错误图、选择模式等
graph TB
A["小程序应用<br/>app.wxss"] --> B["导航栏组件<br/>components/navbar"]
A --> C["富文本组件<br/>components/mp-html"]
B --> D["工具与环境<br/>utils/env.ts, utils/ui.ts"]
C --> E["节点渲染器<br/>node/*"]核心组件
- 导航栏（navbar）
- 作用：提供页面顶部导航区域，支持自定义标题、背景色、滚动透明度、返回/首页按钮、左右插槽扩展
- 关键特性：多插槽（left/center/right）、滚动时背景与标题透明度联动、调试入口圆点（条件渲染）
- 富文本（mp-html）
- 作用：将 HTML 内容安全地渲染为小程序节点树，支持图片懒加载、错误占位图、图片菜单、文本选择等
- 关键特性：通过 nodes 数据驱动渲染，slot 兜底显示，opts 控制行为
架构总览
导航栏组件通过 properties 接收外部配置，内部维护 data 计算状态（如高度、透明度），并通过 methods 处理用户交互；富文本组件以 nodes 作为数据源，结合 opts 参数控制渲染行为。两者均遵循小程序组件化规范，便于在任意页面复用。
sequenceDiagram
participant P as "页面"
participant N as "导航栏组件"
participant U as "工具函数"
participant W as "微信API"
P->>N : 传入 title/backgroundColor/titleColor/scrollOpacity/url/showMenu
N->>N : 计算 statusBarHeight/navigationBarHeight/menuButtonHeight
P->>N : 点击返回按钮
N->>U : douPageTo(url) 或 wx.navigateBack()
P->>N : 点击首页按钮
N->>W : wx.switchTab('/pages/index/index')详细组件分析
导航栏组件（navbar）
- 属性（properties）
- title：标题文本，支持任意类型，内部会转为字符串；空值时显示为空
- backgroundColor：导航栏背景色，默认白色
- titleColor：标题颜色，默认深灰
- scrollOpacity：背景层与默认标题的透明度（0~1），用于滚动渐变效果
- url：返回按钮跳转目标 URL，留空则调用返回
- showMenu：是否显示左侧菜单（返回/首页），默认显示
- 插槽（slots）
- left：左侧区域，未传时使用内置菜单；也可完全自定义
- center：中心区域，未传时回退到 title；可自定义复杂布局
- right：右侧区域，可用于操作按钮等
- 事件与方法
- goBack：根据 url 决定跳转或返回
- goHome：跳转到首页 Tab
- openDebug：打开调试信息页（条件渲染）
- 生命周期
- attached：初始化时根据环境与服务器调试开关决定是否显示调试入口圆点
- 样式与主题
- 可通过 backgroundColor/titleColor 进行主题定制
- 全局样式可在 app.wxss 中统一调整导航栏相关类名
- 无障碍与国际化
- 建议在自定义插槽内为交互元素添加 aria-* 或 a11y 相关属性
- 文案建议通过 i18n 工具获取，避免硬编码
classDiagram
class Navbar {
+title
+backgroundColor
+titleColor
+scrollOpacity
+url
+showMenu
+goBack()
+goHome()
+openDebug()
}
class Utils {
+isDebugEnv()
+isServerDebug()
+douPageTo(url)
}
Navbar --> Utils : "调用"使用示例（路径参考）
- 页面中使用导航栏并传入标题与背景色：页面模板引用示例
- 自定义 left/center/right 插槽内容：页面模板插槽用法
富文本组件（mp-html）
- 属性与数据
- nodes：节点数组，由解析器生成，驱动渲染
- selectable：是否允许文本选择
- containerStyle：容器样式
- opts：行为选项，包括 lazyLoad、loadingImg、errorImg、showImgMenu、selectable
- 插槽
- 当 nodes 为空时，slot 作为兜底内容显示
- 事件与回调
- catchadd="_add"：捕获节点添加事件，便于后续处理
- 样式与主题
- 根节点类名 _root 与可选 _select 用于样式控制
- 可通过外层 CSS 变量或组件级样式覆盖默认外观
- 无障碍与国际化
- 建议在业务层为图片添加 alt 描述，或通过解析阶段注入无障碍属性
- 文案与提示建议使用 i18n 工具管理
flowchart TD
Start(["进入富文本组件"]) --> CheckNodes{"nodes 是否为空?"}
CheckNodes --> |是| RenderSlot["渲染 slot 兜底内容"]
CheckNodes --> |否| RenderNodes["按 nodes 渲染节点树"]
RenderNodes --> ApplyOpts["应用 opts 配置<br/>lazyLoad/loadingImg/errorImg/showImgMenu/selectable"]
RenderSlot --> End(["完成"])
ApplyOpts --> End使用示例（路径参考）
- 页面中引入并传入 nodes 与 opts：页面模板富文本用法
- 自定义图片加载失败占位图：页面样式与数据绑定
依赖关系分析
- 导航栏依赖
- 环境判断：utils/env.ts 中的 isDebugEnv/isServerDebug
- 页面跳转：utils/ui.ts 中的 douPageTo
- 全局尺寸：app.globalData 中的 statusBarHeight、navigationBarHeight 等
- 富文本依赖
- 节点渲染：node/* 子模块负责具体节点渲染逻辑
- 行为控制：opts 参数影响图片加载、菜单、选择等行为
- 全局样式
- app.wxss 提供全局样式基线，可被组件样式覆盖或扩展
graph LR
Env["utils/env.ts"] --> Nav["navbar.ts"]
UI["utils/ui.ts"] --> Nav
App["app.wxss"] --> Nav
Node["node/*"] --> Html["mp-html/index.wxml"]性能考虑
- 导航栏
- 滚动透明度变化应尽量减少 setData 频率，必要时合并更新
- 自定义插槽内容应避免重绘密集的大列表
- 富文本
- 合理使用 lazyLoad 减少首屏图片加载压力
- 对大段 HTML 进行分页或虚拟列表优化
- 图片 errorImg 设置合理占位图，避免闪烁
- 通用
- 避免在频繁触发的回调中进行大量计算
- 使用小程序缓存与本地存储减少重复请求
故障排查指南
- 导航栏标题不显示
- 检查 title 是否为空或未正确传入；确认 center 插槽未被覆盖
- 参考：navbar.ts 标题处理:12-22
- 返回按钮无效
- 检查 url 是否正确；若为空则调用返回；确认 douPageTo 可用
- 参考：navbar.ts 返回逻辑:59-67
- 富文本不渲染
- 确认 nodes 数据已正确生成；检查 opts 配置是否阻止渲染
- 参考：mp-html 根节点:1-1
- 图片加载失败
- 设置合理的 errorImg；检查网络与资源路径
- 参考：mp-html opts 配置:1-1
- 调试入口不显示
- 检查客户端环境与服务端调试开关；确认双门控条件
- 参考：navbar.ts 调试入口:50-57
结论
本项目的小程序通用 UI 组件以导航栏与富文本为核心，提供了可配置、可扩展、易集成的基础能力。通过清晰的属性、插槽与事件机制，开发者可以灵活定制界面与交互。结合全局样式与工具函数，可实现一致的主题与体验。建议在业务中优先复用这些组件，以提升开发效率与维护性。
附录
- 主题与样式
- 通过 backgroundColor/titleColor 快速定制导航栏主题
- 在 app.wxss 中定义全局样式变量，供组件复用
- 参考：app.wxss:1-200
- 国际化
- 建议在页面与组件中通过 i18n 工具获取文案，避免硬编码
- 参考：i18n 工具入口
- 站点配置
- 服务端调试开关与站点信息可通过 site.ts 同步至前端
- 参考：site.ts:1-200