简介

本开发文档面向 DouPHP 小程序的视频管理页面，覆盖视频列表页与视频详情页的完整实现。内容涵盖：

• 列表页缩略图展示、分类筛选、分页加载
• 详情页播放器控制、进度管理、播放统计记录
• 视频数据结构设计（标题、描述、封面图、视频URL、时长、标签、分类等）
• 播放器功能说明（播放/暂停、进度条拖动、音量调节、全屏切换）
• 页面开发示例（集成播放器、缩略图生成、播放统计）
• 性能优化方案（预加载、缓冲策略、内存管理）
• 常见问题解决方案（格式兼容、网络异常、错误重试）

项目结构

本项目采用前后端分离的组织方式：

• 小程序前端位于 miniprogram/default/pages 下，包含视频列表与详情页面
• 后端 API 控制器位于 _'/module/video/api/controller/video/VideoController.php
• 业务逻辑集中在 VideoService，数据模型在 Video 与 VideoCategory

graph TB
subgraph "小程序前端"
VC["视频列表页面<br/>video_category.ts/.wxml"]
VD["视频详情页面<br/>video.ts/.wxml"]
end
subgraph "后端API"
AC["API 控制器<br/>VideoController.php"]
SVC["业务服务<br/>VideoService.php"]
M1["模型 Video<br/>Video.php"]
M2["模型 VideoCategory<br/>VideoCategory.php"]
end
VC --> AC
VD --> AC
AC --> SVC
SVC --> M1
SVC --> M2

核心组件

• 小程序视频列表页：负责分类导航、视频网格展示、分页加载
• 小程序视频详情页：负责获取视频详情、渲染视频播放器与内容
• 后端 API 控制器：提供视频列表与详情接口，处理分类与归档参数
• 业务服务层：构建列表与详情数据、格式化字段、统计点击量
• 数据模型：封装查询条件、关联分类、排序与分页

架构总览

小程序通过 HTTP 调用后端 API，控制器将请求转发至服务层，服务层使用模型进行数据查询与组装，最终返回结构化数据供前端渲染。

sequenceDiagram
participant WX as "小程序页面"
participant API as "API 控制器"
participant SVC as "视频服务"
participant MOD as "视频模型"
WX->>API : 请求视频列表/详情
API->>SVC : 调用 buildVideoListData / buildVideoShowData
SVC->>MOD : 查询已发布视频/分类树
MOD-->>SVC : 返回数据集合
SVC-->>API : 返回结构化结果
API-->>WX : JSON 响应

详细组件分析

视频列表页（分类筛选与分页）

• 分类导航：顶部横向滚动分类栏，点击切换 category_id 并重新加载列表
• 列表展示：网格布局显示缩略图与标题，图片使用 widthFix 模式保持比例
• 分页加载：触底加载更多，合并新数据并更新分页状态
• 分享标题：从接口返回的 title 设置分享标题

flowchart TD
Start(["进入列表页"]) --> LoadCat["读取分类ID"]
LoadCat --> FetchList["请求视频列表接口"]
FetchList --> RenderGrid{"是否成功?"}
RenderGrid --> |是| ShowList["渲染网格列表"]
RenderGrid --> |否| ShowErr["提示请求失败"]
ShowList --> Bottom{"触底事件"}
Bottom --> |是| NextPage["页码+1并追加数据"]
Bottom --> |否| End(["结束"])
NextPage --> FetchList

视频详情页（播放器与控制）

• 数据获取：根据 id 调用详情接口，设置页面标题与分享信息
• 播放器：使用原生 video 组件，支持 controls 提供的播放/暂停、进度条、音量、全屏
• 内容渲染：使用 mp-html 组件渲染视频正文内容
• 统计记录：后端在详情接口中自动增加点击量

sequenceDiagram
participant Page as "详情页面"
participant API as "API 控制器"
participant SVC as "视频服务"
participant Model as "视频模型"
Page->>API : GET /video/show?id=xxx
API->>SVC : buildVideoShowData(id)
SVC->>Model : findPublishedById(id)
Model-->>SVC : 视频数据
SVC-->>API : 视频详情(含分类信息)
API->>SVC : recordVideoView(id)
SVC->>Model : updateClick(id)
API-->>Page : 返回视频详情
Page->>Page : 渲染 video 组件与内容

视频数据结构设计

• 列表项字段：id、category_id、title、file（视频URL）、defined（自定义键值对）、image（封面图）、created_at（发布时间）、add_time_short（短日期）、click（点击量）、description（摘要）、url（详情页链接）、cate_info（分类信息）
• 详情页字段：video（完整视频对象，含 format、content、keywords、description 等多语言字段）、defined、cate_info（分类名称、关键词、描述、父级ID、URL）
• 分类字段：id、name、parent_id、sort、多语言 name

erDiagram
VIDEO {
int id PK
int category_id FK
string title
text content
string description
string image
string file
int click
datetime created_at
json defined
}
VIDEO_CATEGORY {
int id PK
int parent_id
string name
int sort
}
VIDEO_CATEGORY ||--o{ VIDEO : "包含"

视频播放器功能实现

• 播放/暂停：由 video 组件 controls 提供
• 进度条拖动：用户可拖拽进度条跳转播放位置
• 音量调节：controls 提供音量滑块
• 全屏切换：controls 提供全屏按钮
• 内容渲染：mp-html 组件用于富文本内容展示

播放统计记录

• 详情接口在返回前调用 recordVideoView，内部执行 updateClick，使点击量自增
• 前端无需额外埋点，服务端统一计数

依赖关系分析

• 小程序页面依赖 HTTP 服务与路由工具
• API 控制器依赖 VideoService 与配置、路由解析
• VideoService 依赖 MarkdownRenderer、Video 模型
• Video 模型依赖多个 trait 完成附加字段、过滤、排序、分页

graph LR
P1["video_category.ts"] --> H["http服务"]
P2["video.ts"] --> H
H --> C["API 控制器"]
C --> S["VideoService"]
S --> M1["Video 模型"]
S --> M2["VideoCategory 模型"]

性能考虑

• 列表分页：后端按配置分页返回，前端按需追加，避免一次性加载过多数据
• 图片优化：封面图使用 widthFix 模式，减少重绘与内存占用
• 内容渲染：详情内容使用 mp-html 组件，适合富文本渲染
• 预加载与缓冲：小程序 video 组件默认具备缓冲能力；可在列表页提前缓存下一项视频 URL，提升首开速度
• 内存管理：页面卸载时销毁 store bindings，避免内存泄漏
• 网络优化：合理设置请求超时与重试策略，减少重复请求

故障排查指南

• 不同格式视频兼容：后端在服务层根据 file 后缀推断 format；若需扩展，可在服务层增加格式判断与转码提示
• 网络异常处理：前端 catch 分支统一提示“请求失败”，建议结合网络状态检测与重试机制
• 播放错误重试：video 组件 error 事件中可触发重试或降级到备用地址
• 分类与归档参数：控制器会校验分类 ID 与归档参数，非法时抛出异常；请确保路由参数正确
• 统计未生效：确认详情接口被调用且 recordVideoView 执行成功

结论

DouPHP 小程序视频管理页面通过清晰的前后端分层实现了视频列表与详情的完整功能。列表页支持分类筛选与分页加载，详情页提供标准播放器控制与内容渲染，并在服务端统一记录播放统计。建议在后续迭代中增强弹幕、预加载策略与错误重试机制，以提升用户体验与系统稳定性。

附录

• 开发示例要点
  • 集成播放器：在详情页面使用 video 组件并绑定 src 为后端返回的视频 URL
  • 缩略图生成：列表页使用 image 组件展示封面图，注意尺寸与比例
  • 播放统计：无需前端埋点，后端详情接口自动增加点击量
• 推荐优化实践
  • 列表预取：在进入详情页前预取下一视频详情
  • 缓冲策略：利用 video 组件内置缓冲，必要时提供备用地址
  • 内存管理：及时释放页面资源，避免长时间驻留导致内存增长