前端公共部分开发完成，支持图片展示功能

2026-02-15 10:19:32 +08:00 · 2026-01-27 12:56:17 +08:00
parent 911e58c29b
commit be0bcb4d51
25 changed files with 3252 additions and 19 deletions
--- a/webapp/USAGE.md
+++ b/webapp/USAGE.md
@@ -0,0 +1,201 @@
+# 必应每日一图 - 使用说明
+
+## ✨ 功能特性
+
+### 首页（画廊视图）
+
+1. **顶部大图区域**
+   - 全屏展示今日必应图片
+   - 显示图片标题、版权信息和日期
+   - 渐变遮罩效果，突出文字内容
+   - 悬停时内容向上浮动动画
+
+2. **操作按钮**
+   - **查看大图**：跳转到全屏图片查看页面
+   - **了解更多**：打开必应相关链接（基于 quiz 字段）
+
+3. **历史图片画廊**
+   - 网格布局展示历史图片（响应式：手机1列、平板2列、桌面3列）
+   - 鼠标悬停显示元数据信息
+   - 卡片放大和图片缩放动画效果
+   - 点击任意图片打开详情页
+
+4. **无限滚动**
+   - 支持"加载更多"按钮
+   - 自动检测是否还有更多图片
+   - 加载状态提示
+
+### 图片查看页面
+
+1. **全屏展示**
+   - 以最高清晰度（UHD）展示图片
+   - 黑色背景，图片居中显示
+   - 顶部和底部渐变工具栏
+
+2. **信息悬浮层**（类似 Windows 聚焦壁纸）
+   - 半透明背景，毛玻璃效果
+   - 显示图片标题、版权信息
+   - "了解更多信息"链接到必应相关页面
+   - 可以通过按钮或键盘切换显示/隐藏
+
+3. **日期导航**
+   - **前一天** / **后一天** 按钮
+   - 支持键盘方向键导航（← / →）
+   - 今天的图片禁用"后一天"按钮
+   - 导航时有节流保护
+
+4. **键盘快捷键**
+   - `←` : 前一天
+   - `→` : 后一天
+   - `Esc` : 返回首页
+   - `I` : 切换信息显示
+
+## 🎨 设计亮点
+
+### 视觉效果
+- 深色主题，突出图片内容
+- 渐变背景和遮罩层
+- 毛玻璃效果（backdrop-blur）
+- 平滑的过渡动画
+- 响应式设计，适配各种屏幕
+
+### 交互体验
+- 悬停效果（卡片放大、图片缩放）
+- 加载状态提示
+- 按钮禁用状态
+- 键盘快捷键支持
+- 流畅的页面切换
+
+## 🚀 技术实现
+
+### 组件结构
+```
+src/
+├── views/
+│   ├── Home.vue          # 首页画廊视图
+│   └── ImageView.vue     # 图片查看页面
+├── composables/
+│   └── useImages.ts      # 数据获取逻辑
+├── router/
+│   └── index.ts          # 路由配置
+└── lib/
+    ├── api-service.ts    # API 服务
+    ├── api-config.ts     # API 配置
+    ├── api-types.ts      # 类型定义
+    └── http-client.ts    # HTTP 客户端
+```
+
+### 路由配置
+- `/` - 首页画廊视图
+- `/image/:date` - 图片查看页面（动态路由）
+
+### API 集成
+使用封装好的 API 服务：
+- `getTodayImageMeta()` - 获取今日图片元数据
+- `getImages({ limit })` - 获取图片列表
+- `getImageMetaByDate(date)` - 获取指定日期图片
+- `getTodayImageUrl()` - 获取今日图片 URL
+- `getImageUrlByDate(date, variant)` - 获取指定日期图片 URL
+
+### 数据管理
+使用 Vue Composables 模式：
+- `useTodayImage()` - 管理今日图片数据
+- `useImageList()` - 管理图片列表（支持分页）
+- `useImageByDate()` - 管理特定日期图片数据
+
+## 📱 响应式设计
+
+### 断点
+- 手机：< 640px（1列）
+- 平板：640px - 1024px（2列）
+- 桌面：> 1024px（3列）
+
+### 适配特性
+- 响应式网格布局
+- 动态字体大小
+- 移动端优化的按钮文字
+- 触摸友好的交互
+
+## 🎯 使用流程
+
+1. **访问首页**
+   ```
+   http://localhost:5173/
+   ```
+
+2. **浏览今日图片**
+   - 顶部大图展示当天必应图片
+   - 查看标题和版权信息
+
+3. **点击"了解更多"**
+   - 自动拼接完整的必应 URL
+   - 在新标签页打开
+
+4. **浏览历史图片**
+   - 向下滚动查看历史图片网格
+   - 鼠标悬停查看详细信息
+   - 点击"加载更多"获取更多图片
+
+5. **全屏查看图片**
+   - 点击任意图片进入全屏模式
+   - 使用按钮或键盘导航
+   - 按 `Esc` 返回首页
+
+## 🔧 开发
+
+### 启动开发服务器
+```bash
+npm run dev
+```
+
+### 构建生产版本
+```bash
+npm run build
+```
+
+### 预览构建结果
+```bash
+npm run preview
+```
+
+## 📝 注意事项
+
+1. **API 配置**
+   - 确保后端 API 服务正在运行
+   - 开发环境会自动代理 `/api` 请求到 `http://localhost:8080`
+
+2. **图片分辨率**
+   - 首页顶部大图：UHD
+   - 画廊缩略图：1920x1080
+   - 全屏查看：UHD
+
+3. **必应链接**
+   - quiz 字段需要拼接 `https://www.bing.com` 前缀
+   - 例如：`/search?q=...` → `https://www.bing.com/search?q=...`
+
+4. **日期格式**
+   - 使用 ISO 格式：`YYYY-MM-DD`
+   - 例如：`2024-01-27`
+
+## 🎨 自定义样式
+
+可以通过修改 Tailwind CSS 类来调整样式：
+- 渐变颜色：`bg-gradient-to-*`
+- 透明度：`bg-black/80`
+- 模糊效果：`backdrop-blur-*`
+- 动画：`transition-*`、`animate-*`
+
+## 🐛 已知问题
+
+- 需要确保 API 返回正确的图片元数据
+- 图片加载依赖网络速度
+- 大图可能需要一些时间加载
+
+## 🚀 未来优化
+
+- [ ] 添加图片预加载
+- [ ] 支持手势滑动切换（移动端）
+- [ ] 添加图片下载功能
+- [ ] 支持收藏功能
+- [ ] 添加搜索和筛选
+- [ ] 支持暗色/亮色主题切换