UI组件库 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

UI组件库

简介

本文件为 DouPHP 后台管理系统的 UI 组件库文档，聚焦于后台界面中常用的按钮、模态框、下拉菜单、标签页、导航栏等组件。文档从系统架构、组件职责、数据流与事件处理入手，说明各组件的 API 接口、配置选项、事件机制与样式定制方法，并提供开发示例与最佳实践，帮助开发者快速复用现有组件、组合复杂界面并实现自定义扩展。

项目结构

后台 UI 由“布局壳层 + 可复用片段 + 通用样式 + 通用脚本”构成：

布局壳层：通过 index.htm 引入 header、sidebar、toolbar、footer 等公共片段，形成固定顶栏、侧边栏、工具栏与内容区。
可复用片段：page_header、pager、file_input、editor 等用于页面级复用。
样式：common.css 提供全局重置、布局、按钮、表单、表格、分页、模态框等；form.css 补充表单相关样式。
脚本：common.js 提供删除、提交、状态切换、下拉菜单、侧边子菜单定位、文件上传预览与裁剪、自动高度文本域等交互能力。

graph TB
A["index.htm<br/>入口模板"] --> B["header.tpl<br/>顶栏"]
A --> C["sidebar.tpl<br/>侧边栏"]
A --> D["toolbar.tpl<br/>工具栏"]
A --> E["footer.tpl<br/>页脚含隐藏表单"]
A --> F["common.css<br/>全局样式"]
A --> G["common.js<br/>通用交互"]
D --> H["page_header.tpl<br/>页面头部"]
D --> I["pager.tpl<br/>分页"]
F --> J["form.css<br/>表单样式"]

图示来源

admin/view/index.htm:1-224
admin/view/inc/header.tpl
admin/view/inc/sidebar.tpl
admin/view/inc/toolbar.tpl
admin/view/inc/footer.tpl
admin/view/inc/page_header.tpl
admin/view/inc/pager.tpl
admin/view/css/common.css
admin/view/css/form.css
admin/view/js/common.js

核心组件

布局壳层
- 顶栏：站点名、用户操作入口、下拉菜单。
- 侧边栏：一级菜单与二级子菜单，支持悬停弹出与当前模块展开。
- 工具栏：页面级操作入口，支持下拉菜单。
- 内容区：页面主体，支持独立页面模式与带二级导航模式。
表单与数据展示
- 表单控件：输入框、选择框、文本域、文件上传、编辑器。
- 表格与分页：统一边框与行高，配合 pager 片段。
交互组件
- 按钮：主按钮、次按钮、危险按钮等语义化样式。
- 下拉菜单：基于 hover 激活，CSS 控制显隐。
- 模态框：通过 AJAX 动态加载 HTML 片段到 body。
- 状态切换：无刷新布尔字段切换，AJAX 更新 UI。
- 文件上传：本地预览、裁剪、替换、删除。
- 自动高度文本域：根据内容自适应高度。

架构总览

后台 UI 采用“模板片段 + 样式 + 脚本”的解耦方式：

模板负责结构与数据绑定，片段化复用。
样式集中在 common.css，按章节组织（重置、工具类、布局、按钮、表单、表格、分页、模态框等）。
脚本集中在 common.js，使用事件委托与协议化属性（如 data-url、data-confirm、data-state）驱动交互。

sequenceDiagram
participant U as "用户"
participant T as "模板(index.htm)"
participant S as "样式(common.css)"
participant J as "脚本(common.js)"
participant R as "服务端路由"
U->>T : 打开后台首页
T-->>S : 加载全局样式
T-->>J : 加载通用脚本
U->>J : 点击删除/提交/切换
J->>R : 发送请求(POST/GET/DELETE)
R-->>J : 返回HTML或JSON
J-->>U : 更新DOM/提示/跳转

图示来源

admin/view/index.htm:1-224
admin/view/css/common.css
admin/view/js/common.js

详细组件分析

导航栏与侧边栏

顶栏
- 结构：Logo、站点名、右侧导航与下拉菜单。
- 交互：hover 激活下拉菜单，active 状态高亮。
- 响应式：移动端缩小间距，隐藏站点名。
侧边栏
- 结构：一级菜单项与二级子菜单 ul.sub-menu。
- 交互：当前模块内联展开；非当前模块悬停弹出 fixed 定位的子菜单，JS 计算视口坐标避免溢出。
- 滚动位置：点击菜单项保存滚动位置，下次恢复。
- 响应式：窄屏下仅显示图标，展开时显示当前模块子菜单。

flowchart TD
Start(["鼠标进入侧边栏子菜单"]) --> Calc["计算弹出位置<br/>top/left"]
Calc --> Check{"是否超出视口底部?"}
Check -- 是 --> Adjust["调整top至可视区域"]
Check -- 否 --> Keep["保持原top"]
Adjust --> Show["显示子菜单"]
Keep --> Show
Show --> End(["完成"])

图示来源

admin/view/js/common.js:62-76
admin/view/css/common.css:394-575

工具栏与页面头部

工具栏
- 结构：固定顶部工具条，包含操作按钮与下拉菜单。
- 交互：下拉菜单 hover 激活，active 状态显示菜单。
页面头部
- 结构：标题与操作区，支持副操作区。
- 用途：统一页面标题与动作入口，便于复用。

按钮

语义化样式：主按钮、次按钮、危险按钮等，通过 class 区分。
行为：结合 common.js 的事件委托，支持删除、提交、状态切换等操作。
响应式：在小屏幕下调整内边距与字体大小。

表单控件与编辑器

表单控件
- 输入框、选择框、文本域：统一基础样式与对齐。
- 自动高度文本域：autoTextarea 插件根据 min/max 行数自适应高度。
文件上传
- 本地预览：FileReader 读取并显示缩略图。
- 裁剪：调用 douCrop 编辑图片，支持比例设置。
- 替换/删除：通过 fileReplace/fileDel 与后端交互。
编辑器
- 通过 editor.tpl 片段集成富文本编辑器。

表格与分页

表格
- 统一边框、行高与背景色，支持子行与选中态。
分页
- 通过 pager.tpl 片段渲染分页控件，支持页码与跳转。

模态框

触发：通过 douFrame(name, frame, url) 发起 AJAX 请求，将返回的 HTML 追加到 body。
使用场景：弹窗表单、详情查看、确认对话框等。

sequenceDiagram
participant U as "用户"
participant J as "common.js"
participant R as "服务端"
participant D as "DOM"
U->>J : 调用 douFrame(name, frame, url)
J->>R : POST {name, frame}
R-->>J : 返回HTML片段
J->>D : append(html)
D-->>U : 显示模态框

图示来源

admin/view/js/common.js:602-612

下拉菜单

交互：hover 添加 active 类以显示菜单，离开移除 active。
样式：绝对定位、边框与悬停高亮。

状态切换（行内布尔切换）

协议：元素携带 data-url、data-post、data-state、data-text-on/off、data-on-class/off-class、data-confirm-on/off。
流程：点击后 AJAX POST 提交，成功则根据返回值翻转文字、类与行弱化样式，并显示提示。
适用：启用/禁用、显示/隐藏、已读/未读等。

sequenceDiagram
participant U as "用户"
participant E as "元素(.js-toggle)"
participant J as "common.js"
participant S as "服务端"
U->>E : 点击
E->>J : 触发 douToggle()
J->>S : POST(data-url, data-post)
S-->>J : JSON{code : 'OK', message, data : {value : 1|0}}
J->>E : 应用状态(文字/类/行样式)
J-->>U : 提示成功/失败

图示来源

admin/view/js/common.js:25-47
admin/view/js/common.js:711-742
admin/view/js/common.js:747-800

删除与提交

删除：douDelete(url, confirmMsg) 通过隐藏表单提交 DELETE（_method=DELETE），支持确认文案。
提交：douPost(url, confirmMsg) 通过隐藏表单提交 POST，支持确认文案。
事件委托：.js-delete 与 .js-post 类名统一绑定，避免内联 onclick 冲突。

页面布局与响应式

布局壳层：#dou-header、#dou-sidebar、#dou-content、#dou-footer。
响应式：窄屏下侧边栏宽度变化，子菜单隐藏，内容区 margin 调整。
工具栏与二级导航：在 has-subnav 模式下，左侧固定子导航，右侧内容自适应。

依赖关系分析

模板依赖
- index.htm 依赖 header、sidebar、toolbar、footer 片段。
- toolbar 可能包含 page_header 与 pager。
样式依赖
- common.css 提供全局样式与组件样式。
- form.css 补充表单与表格样式。
脚本依赖
- common.js 依赖 jQuery、Alpine（slug 生成）、Pinyin（拼音转 slug）、cropper（裁剪）。
- 文件上传依赖 douCrop 与 fileReplace/fileDel 等函数。

graph LR
I["index.htm"] --> H["header.tpl"]
I --> S["sidebar.tpl"]
I --> T["toolbar.tpl"]
I --> F["footer.tpl"]
T --> PH["page_header.tpl"]
T --> PG["pager.tpl"]
I --> CSS["common.css"]
I --> JS["common.js"]
CSS --> FORM["form.css"]
JS --> LIB["jQuery/Alpine/Pinyin/cropper"]

图示来源

admin/view/index.htm:1-224
admin/view/inc/header.tpl
admin/view/inc/sidebar.tpl
admin/view/inc/toolbar.tpl
admin/view/inc/footer.tpl
admin/view/inc/page_header.tpl
admin/view/inc/pager.tpl
admin/view/css/common.css
admin/view/css/form.css
admin/view/js/common.js

性能考虑

事件委托：使用 document 级别的事件委托减少监听器数量，提升性能。
懒加载与缓存：侧边栏滚动位置与页面滚动位置通过 localStorage 缓存，减少重复计算。
图片优化：文件上传预览仅在必要时计算宽高，避免频繁重排。
样式合并：common.css 集中管理，减少 HTTP 请求。
异步交互：AJAX 局部更新 DOM，避免整页刷新。

故障排查指南

删除/提交无效
- 检查是否存在 #dou-delete-form 或 #dou-post-form 隐藏表单。
- 确认 CSRF token 是否正确注入（meta csrf-token 与表单 token）。
状态切换失败
- 检查 data-url 与 data-post 是否正确。
- 服务端需返回 JSON{code:'OK', message, data:{value:1|0}}。
下拉菜单不显示
- 检查元素是否带有 .dropdown 与 .dropdown-menu。
- 确认 hover 事件是否被其他脚本拦截。
文件上传预览异常
- 检查 FileReader 兼容性。
- 确认 douCrop 与 fileReplace/fileDel 函数可用。
文本域高度异常
- 检查 autoTextarea 是否初始化。
- 确认 min/max 行数与 line-height 计算正确。

结论

DouPHP 后台 UI 组件库通过清晰的模板片段、统一的样式与脚本，提供了稳定易用的界面基础。开发者可基于现有组件快速构建复杂界面，并通过协议化属性与 AJAX 交互实现高效的数据更新。遵循一致性、可访问性与响应式设计原则，结合主题定制与样式覆盖的最佳实践，可进一步提升用户体验与维护效率。

附录

常用类名与属性
- 按钮：.btn-primary/.btn-secondary/.btn-danger（语义化样式）。
- 下拉菜单：.dropdown/.dropdown-menu/.active。
- 状态切换：.js-toggle、data-url、data-post、data-state、data-text-on/off、data-on-class/off-class、data-confirm-on/off。
- 删除/提交：.js-delete、.js-post、data-url、data-confirm。
- 文件上传：.file-input、.file-input-preview、.file-input-action-crop、.file-input-remove。
主题定制建议
- 优先覆盖 common.css 中的变量与关键类，避免直接修改源码。
- 使用媒体查询适配不同屏幕尺寸。
- 保持颜色对比度与焦点可见性，提升可访问性。
开发示例路径
- 按钮与表单：参考 admin/view/inc/file_input.tpl 与 form.css。
- 模态框：参考 common.js 中的 douFrame 用法。
- 状态切换：参考 common.js 中的 js-toggle 协议与服务端响应格式。
- 分页：参考 admin/view/inc/pager.tpl。

添加日期：2026-10-05