kxpyq/查看文件 - 码桶 大佬论坛

码桶

发现社区成员的开源项目
开心 /

kxpyq

公开
main
kxpyq/README.md
README.md9.5 KB
# 🎉 开心朋友圈 (KXpyq) — Typecho 主题介绍

> **版本**：v1.0.0  
> **作者**：[清酒](https://qu.pw)
> **博客**：[KX.MS](https://kx.ms/archives/pyq.html)  
> **类型**：朋友圈风格单用户博客主题  
> **适配**：Typecho 1.2+ / PHP 7.4+

---

## 📱 简介 [KX.MS](https://kx.ms/archives/pyq.html)

**开心朋友圈**（KXpyq）是一款高仿真微信朋友圈风格的 Typecho 主题。设计初衷是为个人博主提供一个亲切、轻量、移动优先的"碎碎念"发布平台——像发朋友圈一样写博客。

它不是传统博客，而是你的**数字朋友圈**：说说、图片、音乐、视频、位置签到、互动评论……这些在微信里习以为常的表达方式，现在你可以在自己的网站上拥有了。

---

## 🏗 整体架构

```
kxpyq/
├── index.php               # 首页——朋友圈信息流
├── post.php                # 文章页——单条说说详情
├── header.php              # 公共头部：SEO/导航/封面/公告
├── footer.php              # 公共底部：音乐浮控/返回顶部/JS加载
├── functions.php           # 核心逻辑：卡片渲染/音乐代理/代码高亮等
├── setting.php             # 后台设置界面（5个Tab页）
├── ajax.php                # AJAX接口：加载更多/点赞/评论/搜索
├── page-about.php          # 关于页面（数据统计+社交链接）
├── page-archive.php        # 归档时光轴（年月分组+统计）
├── page-links.php          # 友情链接页（依赖Links插件）
├── comments.php            # 评论区模板
├── img-proxy.php           # 图片缩放代理（缓存+EXIF修正）
├── music-proxy.php         # 网易云音乐代理
├── lib/Meting.php          # 本地Meting音乐库
├── assets/
│   ├── css/
│   │   ├── style.css          # 源CSS（开发版）
│   │   ├── style.min.css      # 压缩CSS（生产版，~33KB）
│   │   ├── houtai.css         # 后台设置页样式
│   │   └── admin-fix.css      # 后台预览修正
│   ├── js/
│   │   ├── app.v2.js          # 源JS（开发版，~61KB）
│   │   ├── app.min.js         # 压缩JS（生产版，~60KB）
│   │   └── houtai.js          # 后台设置页脚本
│   ├── lib/
│   │   ├── prism/             # Prism.js代码高亮（19种语言，按需加载）
│   │   └── fancybox/          # Fancybox图片灯箱（懒加载）
│   └── cache/                 # 图片代理缓存目录
```

**核心设计理念**：统一渲染、移动优先、性能极致、渐进增强。

所有卡片通过 `pyq_format_post_data()` + `pyq_render_card()` 两个函数统一输出，PHP 服务端渲染与 AJAX 客户端渲染共享同一套代码，杜绝不一致。

---

## ✨ 全部功能一览

### 🎨 朋友圈风格

- 封面大图 + 头像 + 昵称 + 个性签名
- 卡片式信息流，圆角阴影，体验接近微信
- 移动端优先，完美适配手机/平板/桌面
- 置顶说说支持

### 📝 说说内容类型

| 类型 | 说明 |
|------|------|
| 纯文字 | 超过250字自动折叠「展开全文」 |
| 图片 | 1/2/3/4/9宫格自适应布局，单图原比例不裁切 |
| 视频 | 支持直链视频，内嵌播放器 |
| 音乐卡片 | 网易云/本地音频，专辑封面 + 播放控制 + 进度条 + LRC歌词滚动 |
| 链接卡片 | 缩略图 + 标题 + 描述，外链展示 |
| 位置签到 | 链接到高德地图搜索 |
| 话题标签 | `#tag#` 格式，点击搜同类 |

### 🎵 音乐系统

- **全局BGM**：后台配置背景音乐，PJAX 换页不中断
- **音乐卡片**：每条说说可内嵌音乐播放器，支持：
  - 网易云自动获取歌曲名/歌手/封面（Metting API）
  - 播放/暂停 + 进度条拖拽 + 音量
  - LRC 歌词展开滚动（支持标准 LRC 和网易云 JSON 两种格式）
- **浮动音乐控制**：右下角音符按钮 + 播放/暂停 + 定位子按钮
- **网易云代理**：music-proxy.php 本地代理，解决外链失效

### 💻 代码高亮

- Prism.js 集成，支持 **19 种语言**：  
  Bash, C, C++, CSS, Go, HTML, Java, JavaScript, JSON, Kotlin, Markup, PHP, Python, Ruby, Rust, SQL, Swift, TypeScript, 纯文本
- 多行代码块 `\`\`\`language` + 行内代码 `` `code` ``
- 复制按钮 + 行号显示
- **按需加载**：首页不加载，文章页按内容中实际语言动态引入

### 🖼 图片系统

- **图片代理**：`img-proxy.php` 自动缩放 + 缓存，节省带宽
- **EXIF 方向修正**：竖拍照片自动旋转
- **Fancybox 灯箱**：图片点击放大浏览，支持手势滑动（`fancybox.umd.js` ~165KB）
- **懒加载**：Intersection Observer + blur-in 动画
- **失败重试**：图片加载失败自动重试 3 次

### 💬 互动功能

- **点赞**：基于 Cookie + IP 去重，支持访客名显示，点赞列表一目了然
- **表情反应**：长按赞按钮弹出 👍❤️😂😮😢 五种 emoji 反应
- **评论系统**：
  - 嵌套回复，支持 @ 提及
  - 超过 5 条自动折叠，点击「展开全部 N 条」
  - IP 归属地显示（ip-api.com）
  - 博主标记（橙色「博主」badge）
  - 评论邮件通知（依赖 CommentNotifier 插件）
  - 首次评论标记「首评」
- **分享**：二维码分享 + 浏览器原生分享 API + 海报分享（Canvas 生成卡片图）
- **搜索**：全屏弹窗搜索，实时结果
- **PJAX 无刷新换页**：切页时音乐不中断

### 🎛 外观定制

- **深色/浅色模式**：
  - 手动一键切换
  - 定时自动切换（19:00 ~ 07:00）
  - 跟随系统偏好
  - 状态持久化到 localStorage
- **字体大小调节**：左下角 Aa 按钮，14px / 16px / 18px 三档
- **主题色**：后台自定义 HEX 色值
- **最大宽度**：后台调节（默认 680px，适合朋友圈风格）
- **卡片圆角**：后台调节（默认 12px）
- **自定义 CSS/JS**：后台直接注入

### 📡 SEO & 社交分享

- Open Graph 标签（og:title/description/image/url/type/site_name）
- Twitter Card 标签
- 自动 meta description
- RSS / Atom Feed 链接
- 文章底部版权声明（支持 `{title} {url} {author} {date}` 变量）

### 📱 PWA 支持

- `manifest.json`：可安装到手机桌面，带图标和主题色
- Service Worker：离线缓存，弱网可用
- 深色/浅色 theme-color 自适应

### 🚀 性能优化

| 项目 | 优化前 | 优化后 | 方式 |
|------|--------|--------|------|
| CSS | 44KB 同步 | 33KB minified | 压缩 + 版本号 |
| JS | 61KB 同步 | 60KB + defer | 压缩 + 异步加载 |
| Prism | 108KB 全量 | 0~20KB 按需 | 按页面检测语言加载 |
| Fancybox | 165KB 全量 | 0KB（首次点击加载） | 懒加载 |
| **首屏总计** | **~378KB** | **~93KB** | **节省 75%** |

- DNS 预解析 + Preconnect
- 非关键 CSS 异步预加载
- 图片懒加载 + 代理缩放
- 非首屏资源全部延迟

### ⚙️ 后台设置

5 个 Tab 页，分类清晰：

| Tab | 内容 |
|-----|------|
| 基础设置 | 头像、封面、用户名、签名、ICP备案、说说分类、CDN |
| 音乐设置 | 背景音乐 URL、网易云歌曲ID |
| 社交菜单 | GitHub/微博/微信/QQ + 自定义菜单 |
| 功能设置 | Gravatar源（5选）、公告、文章版权 |
| 高级设置 | 主题色/最大宽度/卡片圆角 + 自定义CSS/JS + 注入代码 |

内置**设置备份/还原**功能，换主题不怕配置丢失。

### 📄 页面类型

| 页面 | 说明 |
|------|------|
| 首页 | 朋友圈信息流，无限滚动加载 |
| 文章页 | 单条说说详情 + 相关推荐 |
| 关于页面 | 数据统计（文章/评论/分类/天数）+ 社交链接（GitHub/微博/微信/QQ/Telegram）+ 评论区 |
| 归档页面 | 时光轴：年份分组 + 月份分割 + 统计卡片 |
| 友情链接 | Links 插件集成，按分组展示 |
| 自定义页面 | 通用模板 |

### 🔒 安全

- 输入/输出全面 XSS 防护（`htmlspecialchars` + `json_encode`）
- CSRF Token 验证
- 图片代理 URL 白名单校验（仅允许 http/https）

---

## 🔌 必须搭配的插件

| 插件 | 用途 | 必要性 |
|------|------|--------|
| **Links** | 友情链接管理 | 必须——友情链接页面依赖 |
| **CommentNotifier** | 评论邮件通知 | 必须——评论后自动发邮件通知博主 & 访客 |
| **ArticlePoster** | 文章海报分享 | 必须——海报分享功能依赖 |

> 以上三个插件请务必在 Typecho 后台启用，否则对应功能无法使用。[插件下载](https://kx.ms/archives/pyq.html)

---

## 🌐 兼容性

- **浏览器**：Chrome 80+ / Edge 80+ / Firefox 80+ / Safari 14+
- **PHP**：7.4+（图片代理需要 GD 库）
- **Typecho**：1.2+

---

## 📦 安装

1. 将 `kxpyq` 文件夹上传到 Typecho 的 `/usr/themes/` 目录
2. 后台 → 外观 → 启用「开心朋友圈」
3. 进入「设置外观」进行个性化配置
4. 安装并启用必备插件：Links / CommentNotifier / ArticlePoster
5. 在「撰写」中新建文章，选择「说说」分类（默认 slug: `shuoshuo`），填写自定义字段即可

---

## 📸 截图

`/usr/themes/kxpyq/screenshot.png`

---

## 📝 许可

本主题为开源免费主题，可自由使用、修改。

---

> 🍺 从朋友圈来，到朋友圈去。愿你的碎碎念，有处安放。
> —— 清酒 @ [qu.pw](https://qu.pw)