主页大图功能使用指南

本指南详细介绍如何在 Demius 主题中使用主页大图功能。

---

📋 目录

• 功能特性
• 两种模式对比
• Mode1 中间栏大图
• Mode2 全屏大图
• 打字机效果
• 常见问题

---

✨ 功能特性

• ✅ 双模式选择：Mode1（中间栏大图）、Mode2（全屏大图）
• ✅ 平滑动画：滚动动画、卡片汇聚动画
• ✅ 打字机效果：Mode2副标题支持打字机效果
• ✅ 自定义背景：可使用整站背景或独立背景
• ✅ 遮罩控制：Mode2支持调整遮罩透明度
• ✅ 响应式设计：自动适配各种屏幕
• ✅ PJAX兼容：页面切换流畅过渡

---

🚀 快速开始

1. 启用主页大图

在 hugo.toml 中配置：

[params.homeBigImage]
  enable = true
  mode = "mode2"  # 或 "mode1"
  title = "我的博客"
  subtitle = "欢迎访问"

2. 重新构建

hugo server

3. 访问首页

访问 http://localhost:1313/ 查看效果

---

🎨 两种模式对比

Mode1 - 中间栏大图

特点：

• ✅ 大图仅在中间栏显示
• ✅ 左右侧栏始终可见
• ✅ 点击/滚动后显示文章列表
• ✅ 支持导航箭头和卡片动画

适用场景：

• 希望保留侧栏信息
• 强调内容展示
• 简洁的欢迎页面

Mode2 - 全屏大图

特点：

• ✅ 大图覆盖整个屏幕
• ✅ 点击后向上滚动显示三栏布局
• ✅ 支持打字机效果
• ✅ 更震撼的视觉效果

适用场景：

• 强调品牌形象
• 更具视觉冲击力
• 适合个人博客/作品展示

对比表格：

特性	Mode1	Mode2
显示范围	中间栏	全屏
侧栏可见性	始终可见	点击后显示
视觉冲击力	⭐⭐⭐	⭐⭐⭐⭐⭐
打字机效果	❌	✅
卡片动画	✅	❌
导航箭头	✅	❌

---

🎯 Mode1 中间栏大图

完整配置

[params.homeBigImage]
  enable = true
  mode = "mode1"
  title = "我的博客"
  subtitle = "分享技术与生活"
  
  [params.homeBigImage.mode1]
    backgroundImage = "/img/home-banner.jpg"
    arrowAnimation = true
    scrollSpeed = 500
    cardAnimation = true
    cardAnimationSpeed = "normal"

参数详解

backgroundImage (字符串)

• 作用： 中间栏大图背景
• 路径： /img/home-banner.jpg（放在 static/img/）
• 建议尺寸： 1920×600px
• 格式： JPG/PNG/WebP

arrowAnimation (布尔值)

• 作用： 是否显示向下导航箭头
• 默认值： false
• 效果： 闪烁动画提示用户滚动

scrollSpeed (数字)

• 作用： 滚动到文章列表的动画速度（毫秒）
• 默认值： 500
• 建议： 300-800ms

cardAnimation (布尔值)

• 作用： 是否启用文章卡片汇聚动画
• 默认值： true
• 效果： 卡片从四周飞入

cardAnimationSpeed (字符串)

• 作用： 卡片动画速度
• 可选值： "slow", "normal", "fast"
• 默认值： "normal"

使用示例

示例一：简洁模式

[params.homeBigImage]
  enable = true
  mode = "mode1"
  title = "Hello World"
  subtitle = "Keep It Simple"
  
  [params.homeBigImage.mode1]
    backgroundImage = "/img/simple-bg.jpg"
    arrowAnimation = false
    cardAnimation = false

示例二：完整动画

[params.homeBigImage]
  enable = true
  mode = "mode1"
  title = "Welcome"
  subtitle = "Explore My Blog"
  
  [params.homeBigImage.mode1]
    backgroundImage = "/img/welcome-bg.jpg"
    arrowAnimation = true
    scrollSpeed = 600
    cardAnimation = true
    cardAnimationSpeed = "slow"

---

🌟 Mode2 全屏大图

完整配置

[params.homeBigImage]
  enable = true
  mode = "mode2"
  title = "我的博客"
  subtitle = "时间就是生命，Life is money，Money is life"
  
  [params.homeBigImage.mode2]
    fullScreen = true
    overlayOpacity = 0.5
    customBackgroundImage = "/img/fullscreen-bg.jpg"
    
    # 打字机效果
    typewriterEnable = true
    typewriterSpeed = 100
    typewriterDelay = 1000
    typewriterCursor = true
    typewriterLoop = false

参数详解

fullScreen (布尔值)

• 作用： 是否全屏显示
• 默认值： true
• 建议： 保持 true

overlayOpacity (数字)

• 作用： 遮罩层透明度（0-1）
• 默认值： 0.5
• 建议：
  • 明亮图片：0.3-0.5
  • 深色图片：0.2-0.4

customBackgroundImage (字符串)

• 作用： 独立背景图配置
• 说明：
  • 设置路径：使用该图片
  • 留空：使用整站背景图
• 建议尺寸： 1920×1080px

使用示例

示例一：使用整站背景

[params.homeBigImage]
  enable = true
  mode = "mode2"
  title = "字·兮·书"
  subtitle = "记录生活，分享技术"
  
  [params.homeBigImage.mode2]
    fullScreen = true
    overlayOpacity = 0.4
    customBackgroundImage = ""  # 空值，使用整站背景
    typewriterEnable = false

示例二：独立背景 + 打字机

[params.homeBigImage]
  enable = true
  mode = "mode2"
  title = "Welcome to My Blog"
  subtitle = "探索技术的无限可能"
  
  [params.homeBigImage.mode2]
    fullScreen = true
    overlayOpacity = 0.5
    customBackgroundImage = "/img/tech-bg.jpg"
    
    typewriterEnable = true
    typewriterSpeed = 80
    typewriterDelay = 500
    typewriterCursor = true
    typewriterLoop = false

---

⌨️ 打字机效果

配置参数

[params.homeBigImage.mode2]
  typewriterEnable = true      # 启用打字机
  typewriterSpeed = 100        # 打字速度（毫秒/字符）
  typewriterDelay = 1000       # 开始延迟（毫秒）
  typewriterCursor = true      # 是否显示光标
  typewriterLoop = false       # 是否循环播放

参数详解

typewriterEnable (布尔值)

• 作用： 是否启用打字机效果
• 仅支持： Mode2模式的副标题
• 默认值： false

typewriterSpeed (数字)

• 作用： 每个字符的打字速度（毫秒）
• 默认值： 100
• 建议：
  • 快速：50-80ms
  • 正常：100-120ms
  • 慢速：150-200ms

typewriterDelay (数字)

• 作用： 页面加载后延迟多久开始打字（毫秒）
• 默认值： 1000
• 建议： 500-2000ms

typewriterCursor (布尔值)

• 作用： 是否显示闪烁光标
• 默认值： true
• 效果： | 符号闪烁

typewriterLoop (布尔值)

• 作用： 是否循环播放
• 默认值： false
• 说明：
  • true：打完后删除，重新打字
  • false：打完后停留

效果示例

单次播放

typewriterLoop = false

效果：

时间就是生命，Life is money，Money is life|
(打字完成后停留，光标继续闪烁)

循环播放

typewriterLoop = true

效果：

时 → 时间 → 时间就是生命 → (删除) → 时 → ...
(无限循环)

---

🎨 背景图配置

独立背景 vs 整站背景

使用独立背景

[params.homeBigImage.mode2]
  customBackgroundImage = "/img/home-special.jpg"

特点：

• ✅ 首页使用专属背景
• ✅ 其他页面使用整站背景
• ✅ 更灵活的视觉设计

使用整站背景

[params.homeBigImage.mode2]
  customBackgroundImage = ""  # 留空

特点：

• ✅ 统一的视觉风格
• ✅ 减少图片加载
• ✅ 配置更简单

背景图建议

Mode1：

• 尺寸：1920×600px
• 格式：JPG（压缩到<300KB）
• 内容：简洁、横向构图

Mode2：

• 尺寸：1920×1080px
• 格式：JPG/WebP（压缩到<500KB）
• 内容：大气、中心构图

---

📱 响应式适配

自动适配

两种模式都会自动适配移动端：

Mode1：

• 大图高度自动调整
• 文字大小缩放
• 箭头位置优化

Mode2：

• 全屏效果保持
• 文字居中对齐
• 打字机速度不变

---

🔧 高级定制

修改Mode1大图高度

.home-big-image-mode1 {
  height: 500px;  /* 默认600px */
}

修改Mode2遮罩颜色

.home-big-image-overlay {
  background: linear-gradient(
    135deg, 
    rgba(0, 0, 0, 0.5), 
    rgba(0, 0, 255, 0.3)
  );
}

修改标题样式

.home-big-image-title {
  font-size: 4rem;
  color: #fff;
  text-shadow: 2px 2px 8px rgba(0, 0, 0, 0.5);
}

修改打字机光标

.typewriter-cursor {
  color: #00ff00;  /* 改为绿色 */
  animation: blink 1s infinite;  /* 调整闪烁速度 */
}

---

🔍 常见问题

Q1: 大图不显示？

检查清单：

1. ✅ enable = true
2. ✅ 图片路径正确
3. ✅ 图片已上传到 static/img/
4. ✅ 清除浏览器缓存

Q2: Mode2点击无反应？

原因： JavaScript 未正确加载

解决：

1. 检查浏览器控制台错误
2. 确认 PJAX 正确初始化
3. 强制刷新页面

Q3: 打字机效果不生效？

检查：

1. typewriterEnable = true
2. 仅 Mode2 支持打字机
3. 检查 JavaScript 错误

Q4: 卡片动画太快/太慢？

调整速度：

cardAnimationSpeed = "slow"   # 慢速
cardAnimationSpeed = "normal" # 正常
cardAnimationSpeed = "fast"   # 快速

Q5: 如何禁用大图？

[params.homeBigImage]
  enable = false

Q6: Mode2侧栏闪烁？

已修复： CSS自动隐藏初始状态

如仍有问题：

1. 清除缓存
2. 检查 CSS 加载顺序

Q7: 轮播图与大图冲突？

已处理： 大图激活时轮播图自动隐藏

无需额外配置

Q8: 如何在分页页面禁用大图？

自动处理： 分页页面自动跳过大图动画

---

🎯 最佳实践

1. 模式选择

选择Mode1：

• ✅ 重视内容展示
• ✅ 侧栏信息重要
• ✅ 简洁风格

选择Mode2：

• ✅ 强调品牌形象
• ✅ 追求视觉冲击
• ✅ 个人作品展示

2. 背景图选择

原则：

• ✅ 高质量图片
• ✅ 主题相关
• ✅ 不过于花哨
• ❌ 避免文字过多
• ❌ 避免过暗/过亮

3. 文字内容

标题：

• ✅ 简短有力
• ✅ 3-8个字
• ✅ 突出主题

副标题：

• ✅ 补充说明
• ✅ 10-30字
• ✅ 引起兴趣

4. 打字机效果

适合：

• ✅ 座右铭
• ✅ 欢迎语
• ✅ 品牌口号

不适合：

• ❌ 过长文字
• ❌ 重要信息
• ❌ 导航指引

5. 动画速度

Mode1：

• 滚动：400-600ms
• 卡片：normal/slow

Mode2：

• 打字：80-120ms
• 延迟：500-1500ms

---

📊 性能优化

1. 图片优化

• ✅ 使用 WebP 格式
• ✅ 压缩到合适大小
• ✅ 使用 CDN 加速

2. 动画优化

• ✅ 合理设置速度
• ✅ 避免过多动画
• ✅ 移动端简化动画

3. 加载优化

• ✅ 图片懒加载
• ✅ CSS 内联关键样式
• ✅ JavaScript 延迟加载

---

🔄 更新日志

v1.0.0 (2025-10-24)

• ✨ 支持 Mode1 和 Mode2
• ✅ 打字机效果
• ✅ 卡片汇聚动画
• ✅ 独立背景配置
• ✅ PJAX 兼容
• ✅ 分页自动检测

---

📝 许可证

本功能遵循 Demius 主题的许可证协议。

---

祝使用愉快！ 🎉