Hexo-live-photo

一款轻量、易用的 Hexo 插件，用于在博客文章中优雅地展示由 iPhone、Android 等设备拍摄的 Live Photo（动态照片）及类似动态图片。

起因与介绍

当今的智能手机（如 iPhone 的 Live Photo、部分 Android 的类似功能）都能拍摄动态照片，它们记录下拍照前后共约 3 秒的动态视频和声音。然而，当我们将博客文章部署到静态网站时，这些动态照片通常会退化为静态的 JPEG 图片，失去了其生动的核心体验。

Hexo-live-photo 插件就是为了解决这个问题而生的。它通过解析 Live Photo 资源（一张 .jpg 图片和一段 .mp4 视频），并利用 HTML5 视频播放技术，在不影响页面加载性能的前提下，为您的 Hexo 博客完美还原动态照片的播放效果，让您的回忆更加生动。

Live

动图展示

安装

在 Hexo 博客根目录下执行以下命令：

1	npm install hexo-live-photo --save

配置

在 Hexo 的主配置文件 _config.yml 中添加以下选项：

# Live Photo插件配置
livephoto:
  enable: true
  autoplay: true          # 是否自动播放（当进入视口时）
  hover_to_play: true     # 是否启用悬停播放
  click_to_play: true    # 是否启用点击播放
  lazy_load: true         # 是否启用懒加载
  threshold: 0.8          # 触发自动播放的可见比例
  badge: true             # 是否显示Live标识
  badge_text: 'Live'      # 标识文字
  badge_position: 'bottom-left' # 标识位置: bottom-left, bottom-right, top-left, top-right
  loading_animation: true # 是否显示加载动画
  preload: 'auto'         # 视频预加载策略: auto, metadata, none
  keep_observing: false   # 是否持续观察元素
  hover_delay: 300        # 悬停延迟（毫秒）
  weixin_disable_autoplay: true # 是否禁用微信内置浏览器的自动播放

使用指南

准备资源文件

确保您拥有动态照片的两个核心文件：

视频文件 (.mp4)：动态照片的视频部分
封面图片文件 (.jpg)：动态照片的静态封面部分

将这两个文件放入您的 Hexo 博客源文件目录中，例如 source/images/posts/。

示例文件结构：

1 2	source/images/posts/my-vacation.jpg source/images/posts/my-vacation.mov

推荐您使用对象存储或CDN来托管这些资源，以提升加载速度和用户体验。

示例网址结构：

1 2	https://your-cdn.com/images/posts/my-vacation.jpg https://your-cdn.com/images/posts/my-vacation.mp4

在文章中使用

在您的 Markdown 文章（.md文件）中任何需要插入动态照片的地方，使用 {% live_photo %} 标签。

基本语法：

1	{% livephoto 图片路径视频路径 %}

一行显示两张动图：

代码中内置了相关的CSS代码，采用Flex布局，利用HTML代码即可实现。

<div class="image-grid">
  <div class="image-column">
    {% livephoto 图片路径 视频路径 %}
  </div>
  <div class="image-column">
    {% livephoto 图片路径 视频路径 %}
  </div>
</div>

高级用法

您可以在标签内添加额外的参数如自定义标题、设置宽度和高度。

拓展用法：

1	{% livephoto 图片路径视频路径 "图片描述" "可选标题" "可选宽度" "可选高度" %}

实例：

1	{% livephoto /images/sunset.jpg /videos/sunset.mp4 "海滩日落" "马尔代夫日落美景" "600px" %}

实现原理

插件会生成以下 HTML 结构：

<div class="live-photo-container" id="livePhoto">
    <img src="/images/sunset.jpg" alt="海滩日落" class="static-image">
    <video class="video" muted playsinline>
        <source src="/videos/sunset.mp4" type="video/mp4">
    </video>
    <div class="live-badge">Live</div>
</div>

交互：向下滚动页面，当图片完全进入视图时，Live Photo会自动播放一次，当鼠标悬停或触摸时，视频会再次播放。
外观：可在图片四角显示“Live”标识，提升动态照片的识别度。

注意事项

视频格式：推荐使用H.264编码的MP4格式，以确保在大多数浏览器上的兼容性。
性能：虽然插件已做优化，但请注意视频文件不宜过大，建议使用速度较快的CDN托管视频资源。
浏览器支持：确保您的浏览器支持HTML5视频播放功能，经过测试以后，小米浏览器 会将视频转换为视频播放器，虽然不影响观看，但你会失去下载静态图片的机会和动态播放的体验。
微信浏览器：由于微信内置浏览器对自动播放有严格限制，建议开启 weixin_disable_autoplay 选项，避免自动播放造成的白屏问题。

更新日志

V1.1.3：优化了badge的内容，优化了页面插入代码的逻辑，更新了配置文件的条目。
V1.1.2：修复了加载指示器的显示问题，新增了移动端一行显示两张图片的CSS样式。
V1.1.1：增加了对微信的兼容性支持，修复了部分浏览器的自动播放问题。

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT

支持

如果这个插件帮助到了你，请给予一个 star ⭐。在使用过程中遇到任何问题，请提交 Issue。