Pyq 主题 — 详细功能总结与技术文档

主题名称： Pyq
作者： 清酒
版本： 1.0.0 (2026-06-28)
适配程序： Typecho 1.3.0
运行环境： PHP 8.2 + MySQL 5.7
站点地址： https://p.qu.pw/
主题目录： /www/wwwroot/p.qu.pw/usr/themes/pyq/

一、主题概述

Pyq 是一款仿朋友圈风格的 Typecho 主题，以说说（短文）为核心，支持图文、音乐、视频、链接等多种内容形式。移动端优先设计，支持深色模式、PJAX 无刷新导航、LRC 歌词滚动等高级功能。

参考主题：搜罗全网十多个同类型朋友圈主题，进行模仿学习，在此基础上进行了大量功能增强和 UI 优化。

二、文件结构

pyq/
├── index.php              # 首页模板（说说列表 + 分页 + AJAX加载更多）
├── post.php               # 文章详情页（单篇说说 + 评论区）
├── page.php               # 通用页面模板
├── page-about.php         # 关于页面（社交账号弹窗）
├── page-links.php         # 友链页面
├── page-archive.php       # 归档页面（按月分组）
├── header.php             # 公共头部（导航栏 + 封面 + 公告 + 音乐播放器）
├── footer.php             # 公共底部（弹窗公告 + 返回顶部 + JS加载）
├── comments.php           # 评论模板
├── functions.php          # 主题函数（自定义字段 + 工具函数）
├── setting.php            # 后台设置页（Tab式界面）
├── ajax.php               # AJAX接口（加载更多 + 评论提交 + 点赞）
├── music-proxy.php        # 音乐代理（本地Meting库 + 流式传输）
├── img-proxy.php          # 图片代理（防盗链处理）
├── assets/
│   ├── css/
│   │   ├── style.css      # 前台主样式（1193行）
│   │   ├── houtai.css     # 后台设置页样式（354行）
│   │   └── admin-fix.css  # 后台全局修复CSS（130行）
│   ├── js/
│   │   ├── app.js         # 前台主逻辑（1250行）
│   │   └── houtai.js      # 后台设置页逻辑（54行）
│   └── img/               # 主题图片资源
├── lib/
│   └── Meting.php         # Metowolf Meting 音乐API库
└── static/
    └── prism/             # Prism.js 代码高亮（22个文件，16种语言）

总代码量： 5266 行

三、功能特性

3.1 内容类型

3.2 音乐系统

顶部播放器

• 导航栏集成迷你播放器（播放/暂停 + 歌名滚动）

• 支持两种音源：

  • bgm_url：直接 MP3 链接（优先）
  • netease_id：网易云歌曲ID，通过本地 Meting 库代理获取
• 音乐代理 music-proxy.php：流式传输 + Range 分块请求支持

音乐卡片（说说内嵌）

• 80px 高度卡片，封面背景 + 歌曲名 + 歌手 + 播放按钮
• 底部进度条（3px，hover 6px），支持拖动 seek

• LRC 歌词滚动：

  • 支持标准 LRC 格式（[00:12.34]歌词）
  • 支持网易云 JSON 格式（{"t":0,"c":[{"tx":"歌词"}]}）
  • 歌词区在卡片下方展开，背景使用封面模糊图
  • 当前行高亮（白色 15px + 发光阴影）
  • requestAnimationFrame 同步滚动，使用 scrollTo 避免页面抖动
  • 展开/收起按钮，可手动控制

3.3 评论系统

• AJAX 无刷新提交评论
• 必填昵称 + 邮箱（邮箱格式校验）
• 评论 @回复 功能（点击回复按钮自动填充）

• 评论邮件通知：

  • 直接调用 CommentNotifier 插件的 refinishComment 方法
  • 绕过异步模式（yibu=1），确保邮件即时发送
  • 修复 ownerId 为 0 的问题，从 typecho_contents 查询文章作者
• 评论树形渲染（pyq_render_comments_tree）

3.4 交互功能

• 点赞： AJAX 点赞/取消，实时更新按钮状态和点赞列表
• 分享： 8 按钮弹窗（2×4 网格）— 微信/微博/QQ/复制链接/带标题复制/更多
• 返回顶部： 滚动 300px 后显示，平滑滚动
• 图片灯箱： FancyBox 集成，点击图片放大查看
• 懒加载： IntersectionObserver 图片懒加载
• 加载更多： 滚动到底部自动加载下一页（AJAX）

3.5 PJAX 无刷新导航

• 全站 PJAX 实现，音乐播放不中断
• XMLHttpRequest + DOMParser 解析新页面
• history.pushState / popstate 浏览器前进后退支持
• 换页后自动重新初始化：FancyBox、Prism.js、懒加载、搜索、加载更多
• 内容区域目标：#pyq-feed

3.6 深色模式

• 跟随系统 prefers-color-scheme 自动切换
• CSS 变量体系（--bg, --card, --text, --text2, --text3, --border 等）
• 所有组件完整适配深色/浅色

3.7 代码高亮

• Prism.js 集成（16 种语言）
• 暗色主题 + 行号 + 一键复制按钮
• pyq_parse_code() 函数处理代码块

四、后台设置

4.1 设置界面

Tab 式布局（5 个标签页）：

4.2 设置备份

• 一键备份当前所有设置
• 列出历史备份，支持一键恢复/删除
• 备份存储在 typecho_options 表中

4.3 自定义字段

文章编辑页自定义字段支持：

• textarea 高度优化（36px 起，可拖拽调整）
• 文字描述改为 placeholder（$e->input->setAttribute）
• Radio 按钮置顶选择（is_top）
• 所有字段支持 JS 拖拽调整宽度（text input）

五、页面模板

5.1 关于页面 (page-about.php)

• 社交账号展示（QQ/微信/GitHub/微博）
• 点击弹窗显示账号信息（QQ 弹窗、微信弹窗）
• 复制账号到剪贴板
• 弹窗函数在 app.js 中定义（PJAX 兼容）

5.2 友链页面 (page-links.php)

• 配合links插件使用
• 友链列表展示
• 卡片式布局

5.3 归档页面 (page-archive.php)

• 按年月分组的文章列表
• 链接格式：/archives/slug.html

六、插件依赖

七、性能优化

• 图片懒加载（IntersectionObserver）
• PJAX 无刷新（减少整页重载）
• CSS will-change 用于动画元素
• requestAnimationFrame 用于高频更新（歌词同步、进度条）
• 音乐代理流式传输（不缓存完整文件）
• Prism.js 按需加载（仅代码块页面）

文档生成时间：2026-06-28 19:02
主题总代码量：5266 行
备份总数：10 个
_概述栏目：共12大项，仅公开展示7项。