239 lines
4.5 KiB
Markdown
239 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 支持
|
||
- ✅ 暗黑模式适配
|