简介
本文件面向DouPHP小程序的基础UI组件，重点围绕导航栏组件的实现与使用，提供属性配置、事件回调、插槽用法、样式定制与主题适配的完整说明。同时给出按钮、输入框、弹窗、加载器等常用基础组件的使用建议与最佳实践，帮助开发者快速构建一致、可维护的小程序界面。
项目结构
小程序采用自定义导航栏模式，全局在应用配置中启用 custom 导航样式，并在应用中注册全局导航栏组件。页面通过引入该组件实现统一的顶部导航体验。
graph TB
A["应用配置 app.json"] --> B["全局 usingComponents 注册 navbar"]
B --> C["页面模板中使用 <navbar/>"]
C --> D["导航栏组件 navbar.wxml/wxss/ts"]
D --> E["工具函数 ui.ts跳转/提示"]图示来源
- app.json:136-145
- navbar.wxml:1-39
- navbar.ts:1-79
- ui.ts:1-73
核心组件
- 导航栏组件（navbar）
- 作用：提供固定顶部的导航区域，支持左侧菜单、居中标题、右侧插槽；支持滚动透明度渐变、返回/首页行为、调试入口等。
- 关键能力：
- 自定义背景色与标题颜色
- 滚动时背景与标题透明度联动
- 左侧返回与首页按钮（可隐藏）
- 左/中/右三个插槽，便于扩展
- 基于全局状态栏/导航栏高度自适应布局
- 统一跳转与提示工具集成
架构总览
导航栏组件通过小程序自定义组件机制挂载到页面，结合全局工具函数完成导航与交互。整体流程如下：
sequenceDiagram
participant Page as "页面"
participant Nav as "navbar 组件"
participant UI as "ui.ts 工具"
participant WX as "微信API"
Page->>Nav : 渲染 <navbar title/backgroundColor/showMenu/url/>
Nav->>Nav : 计算状态栏/导航栏高度并布局
Page->>Nav : 点击“返回”或“首页”
Nav->>UI : douPageTo(url)/wx.switchTab()
UI-->>WX : navigateBack / switchTab / redirectTo
Nav-->>Page : 更新标题/透明度等视图状态图示来源
- navbar.ts:59-77
- ui.ts:30-64
详细组件分析
导航栏组件（navbar）
- 组件结构与插槽
- 左侧区域：内置返回与首页按钮（可通过 showMenu 控制显示），也支持 left 插槽插入自定义内容。
- 中间区域：默认展示 title，也可通过 center 插槽完全自定义。
- 右侧区域：right 插槽，用于放置更多操作项。
- 背景层：独立背景 view，透明度由 scrollOpacity 驱动，标题默认跟随透明度变化。
- 属性与数据
- 属性
- title：页面标题（字符串），支持空值处理
- backgroundColor：背景色（默认白色）
- titleColor：标题颜色（默认深色）
- scrollOpacity：背景与标题透明度（0~1）
- url：返回时的目标路径（可选）
- showMenu：是否显示左侧菜单（默认显示）
- 内部数据
- 状态栏高度、导航栏高度、胶囊按钮高度、组合高度等，均取自全局 globalData
- debugDot：调试入口圆点开关（受环境与服务器调试标志双门控）
- 属性
- 方法与事件
- goBack：优先跳转到指定 url，否则回退上一级
- goHome：切换到首页 TabBar
- openDebug：进入调试信息页（满足条件时显示）
- 样式要点
- 固定定位、z-index 层级管理
- 左右预留空间避免遮挡系统胶囊按钮
- 标题居中且支持单行省略
- 调试圆点位于全屏右侧垂直居中，外层容器不拦截点击
classDiagram
class Navbar {
+properties : title, backgroundColor, titleColor, scrollOpacity, url, showMenu
+data : statusBarHeight, navigationBarHeight, ... , debugDot
+methods : goBack(), goHome(), openDebug()
}
class Utils {
+douPageTo(url)
+douMsg(message, url, time)
+showShareMenu()
}
Navbar --> Utils : "调用跳转/提示"图示来源
- navbar.ts:12-77
- ui.ts:30-73
导航栏使用示例（以页面为例）
- 在页面模板中引入并使用组件，传入必要属性：
- 设置标题、背景色、标题颜色
- 根据业务决定是否显示左侧菜单
- 为返回按钮指定目标 url（可选）
- 通过 left/right 插槽扩展功能按钮
- 通过 center 插槽替换默认标题
- 在页面逻辑中控制滚动透明度：
- 监听页面滚动，动态更新 scrollOpacity，实现背景渐显效果
- 跳转与提示：
- 使用工具函数进行统一跳转与 toast 提示，保证行为一致
依赖关系分析
- 组件对全局配置的依赖
- 应用配置启用自定义导航栏，并在全局 usingComponents 中注册 navbar
- 组件对工具函数的依赖
- 跳转与提示统一通过 ui.ts 的工具函数，确保 tabBar 与非 tabBar 页面的差异化处理
- 组件对全局数据的依赖
- 状态栏/导航栏尺寸来自 app.globalData，保证不同机型适配
graph LR
AppCfg["app.json<br/>usingComponents/window"] --> NavComp["navbar 组件"]
NavComp --> Uti["ui.ts<br/>douPageTo/douMsg"]
NavComp --> Gd["app.globalData<br/>尺寸/状态"]图示来源
- app.json:136-145
- navbar.ts:40-48
- ui.ts:30-64
性能与兼容性
- 性能优化建议
- 滚动透明度更新：使用节流/防抖减少 setData 频率，避免频繁重排
- 图片资源：导航图标使用合适尺寸与 mode="heightFix"，减少解码开销
- 插槽内容：尽量保持轻量，避免在导航栏内渲染复杂列表或大图
- 条件渲染：showMenu 与 debugDot 等布尔属性控制渲染范围，减少无用节点
- 兼容性处理
- 状态栏/导航栏高度：通过全局 globalData 获取，适配刘海屏与不同系统版本
- 胶囊按钮避让：左右 padding 预留空间，避免内容被系统按钮遮挡
- 跳转策略：统一使用 douPageTo，自动识别 tabBar 与非 tabBar 路径，避免栈异常
- 主题与样式定制
- 通过 backgroundColor/titleColor 快速切换主题
- 通过 left/right/center 插槽注入品牌元素或操作按钮
- 如需更深层定制，可在 wxss 中覆盖 .navigation/.bar/.menu 等类名
故障排查
- 标题不显示或被截断
- 检查 title 是否为空或超长；确认 center 插槽未覆盖默认标题
- 参考：navbar.wxml:20-23
- 返回按钮无效
- 若设置了 url，将跳转到指定页面；未设置则回退上一页
- 参考：navbar.ts:59-67
- 滚动透明度不生效
- 确认页面是否正确更新 scrollOpacity；避免过度频繁 setData
- 参考：navbar.wxml:3-4
- 调试圆点不出现
- 需同时满足客户端非正式版与服务端调试开启；否则不会渲染
- 参考：navbar.ts:50-57
- 跳转后页面栈异常
- 使用 douPageTo 统一跳转，避免手动调用 wx.navigateTo 导致栈不一致
- 参考：ui.ts:30-47
结论
导航栏组件提供了稳定、可扩展的顶部导航方案，结合全局工具函数实现了统一的跳转与提示行为。通过属性与插槽的组合，既能满足常见场景的快速接入，也能支撑复杂业务的深度定制。配合合理的性能优化与兼容性处理，可在多机型上保持一致的用户体验。
附录：其他基础UI组件使用指南
以下为小程序开发中常用的基础UI组件使用建议与最佳实践。由于仓库未包含独立的组件封装，以下方法可直接复用或按需封装为组件。
- 按钮（Button）
- 属性：type、size、plain、loading、disabled、formType、openType
- 事件：bindtap、bindgetuserinfo、bindopensetting 等
- 样式：通过 class 覆盖默认样式，或使用 rpx 单位适配
- 建议：禁用态与加载态明确反馈；长文本使用换行或省略
- 输入框（Input）
- 属性：value、placeholder、type、password、maxlength、focus、disabled
- 事件：bindinput、bindconfirm、bindblur、bindfocus
- 建议：键盘类型与输入限制匹配业务；提交前做前端校验
- 弹窗（Modal/Dialog）
- 使用 wx.showModal 或自定义 modal 组件
- 属性：title、content、showCancel、cancelText、confirmText
- 事件：success/fail/complete 回调
- 建议：避免嵌套多层弹窗；异步操作时显示 loading
- 加载器（Loading）
- 使用 wx.showLoading 或自定义 spinner
- 建议：长时间请求使用进度或骨架屏；及时关闭避免残留
- Toast 提示
- 使用 ui.ts 中的 douMsg，统一提示与跳转行为
- 建议：短消息为主，避免打断用户操作流
- 分享
- 使用 ui.ts 中的 showShareMenu，开启转发与朋友圈分享
- 建议：在 onShareAppMessage/onShareTimeline 中设置分享内容