氛围感 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=雷暴等),并内置能见度/湿度兜底判定,可识别天气模型误报为"阴天"的真实雾天。
二、环境要求
| 项目 | 要求 |
|---|---|
| Halo | 2.20.0 及以上(在 2.27.2 上开发测试) |
| 浏览器 | 支持现代 JS 与 Canvas 的浏览器 |
| 主题 | 任意主题(脚本注入 head,与主题无关) |
三、安装
- 下载插件 JAR 包(
plugin-weather-effect-1.0.0.jar) - 打开 Halo 后台 → 插件 → 右上角安装,上传 JAR 包
- 在插件列表中找到「氛围感」,点击启用
- 点击右侧设置进入配置页
已安装旧版本时,直接上传新 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 个自包含特效脚本 + 部署说明:
- 解压,把需要的特效文件(如
snow.js)上传到你的存储(又拍云、OSS、CDN 均可,如https://your-cdn.com/atmosphere/snow.js) - 在插件设置的对应特效 URL 框中填入地址
- 保存即生效
自定义特效开发契约
想让插件加载你自制的特效(樱花、萤火虫、流星……),脚本只需满足:
- 自包含 IIFE,脚本加载后即开始渲染
- 读取
window.__weatherEffectConfig = { mode, flakeCount, speed, weatherApi }flakeCount:粒子数量,0 表示自行按屏幕宽度自适应speed:速度倍率,请乘到你的运动速度上
- 画布元素 id 固定为
atmosphere-canvas(插件保证同时只加载一个特效) - 画布样式:
position:fixed全屏 +pointer-events:none,不阻挡页面交互 - 建议尊重
window.__forceWeather(存在时跳过 prefers-reduced-motion 检查) - 建议监听
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