氛围感 Atmosphere Effect

为 Halo 博客叠加全局天气氛围特效的插件 作者:梦想是做一名杀手 · https://blog.upslide.cn

「氛围感」会自动检测每位访客当地的实时天气,在整站叠加对应的动态特效:下雪天飘雪、雨天落雨、雾天起雾……让博客"活"起来。同时支持把任意特效替换为自定义外部脚本(樱花、萤火虫、流星……随你发挥)。

当前正式版本:1.0.0


一、功能特性

  • 七类内置天气特效,按访客当地实时天气自动切换
  • 双数据源:心知天气(API Key,服务端代理)或 Open-Meteo(免费无 Key)
  • 外部特效脚本:每类特效可填写外部 URL 替换内置版本,加载失败自动回退
  • 性能友好:Canvas 渲染 + pointer-events:none 不阻挡交互 + 页面隐藏自动暂停
  • 隐私安全:API Key 仅保存在服务端;定位结果缓存 30 分钟;不追踪、不存储个人信息
  • 无障碍:尊重系统"减少动态效果"设置(prefers-reduced-motion)

内置特效一览

特效触发天气(心知代码)视觉效果
❄ 雪花 snow阵雪/小中大暴雪 (12-16, 26-28)白色雪花飘落 + 光晕摆动
🌧 雨 rain阵雨/中大暴雨/冻雨 (3, 7-11, 19, 21-25)雨丝斜落 + 落地涟漪
💧 细雨 drizzle小雨 (6)轻柔毛毛雨,慢速朦胧
⛈ 雷雨 thunder雷阵雨 (4, 5)密集雨丝 + 随机闪电
🌫 雾 fog雾凇/雾 (17, 18)多层雾团横移 + 贴地浓雾带
🟤 沙尘 dust沙尘暴/浮尘/扬沙/霾 (20, 29-32, 53, 54)沙粒横漂 + 沙尘罩
✨ 日光尘 clear晴/多云 (0, 1)暖色光尘缓缓上浮

Open-Meteo 数据源使用 WMO 天气码(45/48=雾、61-82=雨、71-86=雪、95-99=雷暴等),并内置能见度/湿度兜底判定,可识别天气模型误报为"阴天"的真实雾天。


二、环境要求

项目要求
Halo2.20.0 及以上(在 2.27.2 上开发测试)
浏览器支持现代 JS 与 Canvas 的浏览器
主题任意主题(脚本注入 head,与主题无关)

三、安装

  1. 下载插件 JAR 包(plugin-weather-effect-1.0.0.jar)
  2. 打开 Halo 后台 → 插件 → 右上角安装,上传 JAR 包
  3. 在插件列表中找到「氛围感」,点击启用
  4. 点击右侧设置进入配置页

已安装旧版本时,直接上传新 JAR 会提示升级,配置会自动保留。


四、配置说明

1. 天气数据源

选项说明
Open-Meteo(免费无 Key)默认。插件独立工作,不需要任何账号和密钥
心知天气(API Key,服务端代理)与主题自带的天气组件数据源同步。前往 https://www.seniverse.com 注册获取,免费版即可,自动根据访客 IP 定位。获取 API Key 后填入下方「心知天气 API Key」
  • API Key 仅保存在 Halo 服务端,不会出现在页面代码中
  • 心知请求失败时自动回退 Open-Meteo,特效链路始终可用

2. 运行模式

选项说明
自动(真实天气驱动)按访客当地实时天气自动选择特效(日常使用推荐)
强制:雪花 / 雨 / 细雨 / 雷雨 / 雾 / 沙尘 / 日光尘强制渲染指定特效,用于测试验收
关闭特效不注入任何内容

3. 粒子数量 / 速度倍率

  • 粒子数量:0 为按屏幕宽度自适应(推荐),最大 400,对所有特效生效
  • 速度倍率:1 为默认速度,范围 0.2 ~ 3,越大越快

4. 七个特效脚本 URL(外部特效)

每类特效一行,标注了特效名称和对应天气码:

  • 留空 = 使用插件内置特效(推荐,零成本)
  • 填写 URL = 该特效改为引用你自己的外部脚本

适用场景:想自定义特效外观、或把特效文件放到自己的 CDN 统一管理。配套的 7 个自包含特效脚本见下方「特效文件包」。


五、特效文件包(外部部署)

发布包附带 atmosphere-effects-v1.0.0.zip,内含 7 个自包含特效脚本 + 部署说明:

  1. 解压,把需要的特效文件(如 snow.js)上传到你的存储(又拍云、OSS、CDN 均可,如 https://your-cdn.com/atmosphere/snow.js)
  2. 在插件设置的对应特效 URL 框中填入地址
  3. 保存即生效

自定义特效开发契约

想让插件加载你自制的特效(樱花、萤火虫、流星……),脚本只需满足:

  1. 自包含 IIFE,脚本加载后即开始渲染
  2. 读取 window.__weatherEffectConfig = { mode, flakeCount, speed, weatherApi }
    • flakeCount:粒子数量,0 表示自行按屏幕宽度自适应
    • speed:速度倍率,请乘到你的运动速度上
  3. 画布元素 id 固定为 atmosphere-canvas(插件保证同时只加载一个特效)
  4. 画布样式:position:fixed 全屏 + pointer-events:none,不阻挡页面交互
  5. 建议尊重 window.__forceWeather(存在时跳过 prefers-reduced-motion 检查)
  6. 建议监听 visibilitychange,页面隐藏时暂停动画省电

六、调试与排查

手段说明
URL 参数 ?weather=类型临时强制特效,支持 snow / rain / drizzle / thunder / fog / dust / clear / off
URL 参数 ?atmosphere_debug=1打开 console 调试日志,并绕过 30 分钟缓存强制重新检测
服务端端点访问 https://你的博客/plugins/plugin-weather-effect/weather 查看心知代理返回的原始数据

常见问题:

  • 设置了自动但没特效:当前天气可能是多云/阴天(无特效归属)。加 ?atmosphere_debug=1 看 console 中判定出的类型
  • 明明是雾天却没起雾:Open-Meteo 模型常把雾报成阴天,插件已内置能见度/湿度兜底;心知数据源则按中文现象文本优先匹配,不受码表错乱影响
  • 特效加载失败:外部 URL 404 时会自动回退内置特效,console 会打印回退日志

七、隐私与性能说明

  • 定位与天气查询结果缓存在访客浏览器 localStorage(30 分钟,键名 atmosphere_cache_v1)
  • 心知模式:服务器按访客 IP(X-Forwarded-For)向心知定位查询,结果在服务端缓存 10 分钟,不存储任何个人身份信息
  • 特效画布 pointer-events:none,不阻挡点击与阅读;页面切到后台自动暂停渲染
  • 全部特效脚本体积均在 10KB 以内

八、版本记录

1.0.0(正式归档版):服务端 10 分钟天气缓存节省 API 配额;外部脚本加载失败自动回退内置;运行模式白名单加固;心知雾/霾/沙尘按中文现象文本优先匹配。

此前开发迭代记录(内部版本):

版本说明
1.5.x心知天气数据源(服务端代理,Key 不暴露);端点路由与雾码匹配修复
1.4.x七类内置特效;运行模式可强制任意特效;外部特效 URL 逐类配置
1.3.0更名「氛围感」;新增特效来源内置/外部双模式
1.2.0修复 Bean 注册索引与静态资源映射(首次可正常工作版本)
1.0-1.1(试验版)初版雪花特效

许可

MIT License