238 lines
4.5 KiB
Markdown
238 lines
4.5 KiB
Markdown
|
# Hugo 短代码功能 & Telegram Bot 适配
|
|||
|
|
|
|||
|
|
## ✅ 已实现功能
|
|||
|
|
|
|||
|
|
### 1️⃣ Hugo 短代码
|
|||
|
|
|
|||
|
|
#### 实况照片 (Live Photo)
|
|||
|
|
```markdown
|
|||
|
|
{{< livephoto image="photo.jpg" video="photo.mp4" >}}
|
|||
|
|
```
|
|||
|
|
- 悬停播放视频
|
|||
|
|
- 点击切换播放/暂停
|
|||
|
|
- 静音控制
|
|||
|
|
- 自动检测图片比例
|
|||
|
|
|
|||
|
|
#### 语音气泡
|
|||
|
|
```markdown
|
|||
|
|
{{< voice src="voice.ogg" >}}
|
|||
|
|
```
|
|||
|
|
- 微信风格设计
|
|||
|
|
- 点击播放语音
|
|||
|
|
- 自动显示时长
|
|||
|
|
- 未读标记（当天发布）
|
|||
|
|
|
|||
|
|
#### 音乐卡片
|
|||
|
|
```markdown
|
|||
|
|
{{< music-card src="song.mp3" name="歌曲名" artist="歌手" cover="cover.jpg" >}}
|
|||
|
|
```
|
|||
|
|
- 精美卡片设计
|
|||
|
|
- 播放/暂停控制
|
|||
|
|
- 进度条拖拽
|
|||
|
|
- 时间显示
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📱 Telegram Bot 使用指南
|
|||
|
|
|
|||
|
|
### 发送语音消息
|
|||
|
|
|
|||
|
|
**操作**：
|
|||
|
|
1. 在写作模式下（`/new` 或 `/edit`）
|
|||
|
|
2. 发送语音消息
|
|||
|
|
|
|||
|
|
**Bot 响应**：
|
|||
|
|
```
|
|||
|
|
🎙️ 正在处理语音...
|
|||
|
|
✅ 语音已保存：1719234567-voice.ogg
|
|||
|
|
📝 转文字：今天天气真好...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**生成内容**：
|
|||
|
|
```markdown
|
|||
|
|
{{< voice src="1719234567-voice.ogg" >}}
|
|||
|
|
|
|||
|
|
> 今天天气真好...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 发送音频文件（MP3）
|
|||
|
|
|
|||
|
|
**操作**：
|
|||
|
|
1. 在写作模式下
|
|||
|
|
2. 发送 MP3 文件
|
|||
|
|
|
|||
|
|
**Bot 响应**：
|
|||
|
|
```
|
|||
|
|
🎵 正在处理音频文件...
|
|||
|
|
✅ 音频已保存：1719234567-music.mp3
|
|||
|
|
|
|||
|
|
请输入歌曲信息（格式：歌名 - 歌手）：
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**用户回复**：
|
|||
|
|
```
|
|||
|
|
晴天 - 周杰伦
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Bot 响应**：
|
|||
|
|
```
|
|||
|
|
🎵 歌曲：晴天
|
|||
|
|
🎤 歌手：周杰伦
|
|||
|
|
|
|||
|
|
是否添加封面图？
|
|||
|
|
[📷 添加封面图] [⏭️ 跳过]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**选项 A - 添加封面图**：
|
|||
|
|
1. 点击 "添加封面图"
|
|||
|
|
2. 发送图片
|
|||
|
|
3. Bot：✅ 封面图已保存：cover.jpg
|
|||
|
|
4. 生成带封面的音乐卡片
|
|||
|
|
|
|||
|
|
**选项 B - 跳过**：
|
|||
|
|
1. 点击 "跳过"
|
|||
|
|
2. 直接生成不带封面的音乐卡片
|
|||
|
|
|
|||
|
|
**生成内容**：
|
|||
|
|
```markdown
|
|||
|
|
{{< music-card src="1719234567-music.mp3" name="晴天" artist="周杰伦" cover="cover.jpg" >}}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 发送图片
|
|||
|
|
|
|||
|
|
**操作**：
|
|||
|
|
1. 在写作模式下
|
|||
|
|
2. 发送图片
|
|||
|
|
|
|||
|
|
**Bot 响应**：
|
|||
|
|
```
|
|||
|
|
📷 图片已保存：1719234567-photo.jpg
|
|||
|
|
|
|||
|
|
💡 提示：如果您发送的是 iOS 实况照片（Live Photo），
|
|||
|
|
动态效果无法自动提取。如需保留动态效果，请：
|
|||
|
|
|
|||
|
|
1. 将实况照片转为视频/GIF 后重新发送
|
|||
|
|
2. 或者单独发送视频部分
|
|||
|
|
|
|||
|
|
继续发送其他内容...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**生成内容**：
|
|||
|
|
```markdown
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🎯 功能特性
|
|||
|
|
|
|||
|
|
### PJAX 支持
|
|||
|
|
- 所有短代码支持 PJAX 无刷新页面切换
|
|||
|
|
- 自动重新初始化交互逻辑
|
|||
|
|
- 保持播放状态
|
|||
|
|
|
|||
|
|
### 暗黑模式
|
|||
|
|
- 自动适配暗黑主题
|
|||
|
|
- 深色背景优化
|
|||
|
|
- 高对比度设计
|
|||
|
|
|
|||
|
|
### 响应式设计
|
|||
|
|
- 移动端友好
|
|||
|
|
- 触摸操作支持
|
|||
|
|
- 自适应布局
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🛠️ 技术实现
|
|||
|
|
|
|||
|
|
### 文件结构
|
|||
|
|
|
|||
|
|
**Hugo 主题 (ying)**：
|
|||
|
|
```
|
|||
|
|
themes/ying/
|
|||
|
|
├── layouts/shortcodes/
|
|||
|
|
│ ├── livephoto.html
|
|||
|
|
│ ├── voice.html
|
|||
|
|
│ └── music-card.html
|
|||
|
|
├── assets/css/
|
|||
|
|
│ └── shortcodes.css
|
|||
|
|
└── assets/js/
|
|||
|
|
└── shortcodes.js
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Telegram Bot (write-server)**：
|
|||
|
|
```
|
|||
|
|
write-server/src/lib/bot/
|
|||
|
|
├── poll.ts
|
|||
|
|
│ ├── handleVoiceEnhanced() # 语音增强
|
|||
|
|
│ ├── handleAudioEnhanced() # 音频处理
|
|||
|
|
│ ├── handlePhotoEnhanced() # 图片增强
|
|||
|
|
│ ├── handleAudioInfoEnhanced() # 音频信息
|
|||
|
|
│ └── handleAudioCoverCallback() # 封面图回调
|
|||
|
|
└── handlers.ts
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### API 集成
|
|||
|
|
- Artalk 评论系统
|
|||
|
|
- Telegram Bot API
|
|||
|
|
- Hugo 静态生成
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📝 部署检查清单
|
|||
|
|
|
|||
|
|
- [ ] 提交 ying 主题修改
|
|||
|
|
- [ ] 提交 write-server 修改
|
|||
|
|
- [ ] 推送到远程仓库
|
|||
|
|
- [ ] 重新构建 Hugo 站点
|
|||
|
|
- [ ] 部署 write-server
|
|||
|
|
- [ ] 测试语音消息
|
|||
|
|
- [ ] 测试音频文件
|
|||
|
|
- [ ] 测试图片上传
|
|||
|
|
- [ ] 验证短代码渲染
|
|||
|
|
- [ ] 测试 PJAX 页面切换
|
|||
|
|
- [ ] 测试暗黑模式
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🐛 故障排除
|
|||
|
|
|
|||
|
|
### 语音不播放
|
|||
|
|
- 检查音频文件路径
|
|||
|
|
- 确认文件格式支持（OGG, MP3）
|
|||
|
|
- 查看浏览器控制台错误
|
|||
|
|
|
|||
|
|
### 音乐卡片无响应
|
|||
|
|
- 检查 JS 是否正确加载
|
|||
|
|
- 确认 PJAX 初始化
|
|||
|
|
- 刷新页面重试
|
|||
|
|
|
|||
|
|
### 封面图不显示
|
|||
|
|
- 检查图片路径
|
|||
|
|
- 确认文件已保存
|
|||
|
|
- 查看 Hugo 构建日志
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📚 相关链接
|
|||
|
|
|
|||
|
|
- [Hugo 短代码文档](https://gohugo.io/content-management/shortcodes/)
|
|||
|
|
- [Telegram Bot API](https://core.telegram.org/bots/api)
|
|||
|
|
- [Amigo 主题](https://github.com/zqlit/Hugo-Theme-Amigo)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📊 版本历史
|
|||
|
|
|
|||
|
|
**v1.0.0** (2026-06-24)
|
|||
|
|
- ✅ 移植 Amigo 主题短代码
|
|||
|
|
- ✅ Telegram Bot 语音增强
|
|||
|
|
- ✅ Telegram Bot 音频文件支持
|
|||
|
|
- ✅ 封面图上传功能
|
|||
|
|
- ✅ 实况照片引导提示
|
|||
|
|
- ✅ PJAX 支持
|
|||
|
|
- ✅ 暗黑模式适配
|