首页轮播图（home-carousel）

在首页顶部显示轮播图，支持触摸滑动、滑动动画、定时上下架、移动端独立高度、图片显示方式配置。

属性	值
插件 ID	`home-carousel`
版本	`1.2.0`
作者	狡猾的骗骗花 nodey@qq.com
入口	`dist/server.mjs`
注入槽位	`feed.main.before`

功能预览

功能清单

前台展示

滑动过渡动画 — 幻灯片切换时通过 opacity + transform: translateX() 实现方向性滑动，支持 prefers-reduced-motion 无障碍降级
触摸滑动 — 移动端左右滑动切换幻灯片，touch-action: pan-y 保证不干扰页面纵向滚动
键盘导航 — 容器聚焦后（tabindex="0"）可用左右方向键切换
悬停暂停 — 鼠标悬停时暂停自动播放，移出后恢复
进度圆点 — 底部导航圆点覆盖在图片上，悬停时显示箭头和圆点，触屏设备常驻显示
懒加载 — 首张图片 eager 加载，其余 lazy 延迟加载

后台配置

配置项	类型	默认值	说明
开启轮播图	开关	`true`	总开关
图片高度	选择	`280`	桌面端高度，预设 200/280/360/480px，显示推荐宽度×高度
移动端高度	选择	`200`	移动端独立高度（≤768px 生效），预设同上
图片显示方式	选择	`cover`	`cover` 裁剪居中 / `contain` 完整显示 / `fill` 拉伸填充
自动播放	开关	`true`	是否自动轮播
停留时间	数字	`4000`	每张图片展示时长（毫秒），最少 1000

每张轮播图字段

字段	说明
显示图片	图片 URL，建议 16:9 比例
标题	叠加在图片底部的文字，可留空
跳转地址	点击跳转链接，支持站内 `/posts/1` 和外链 `https://...`，可留空
定时上架	到该时间后显示，留空则立即显示
定时下架	到该时间后隐藏，留空则不自动下架

架构设计

采用 MVC 分层架构，职责清晰分离：

text
addon.json                          ← 插件清单
dist/
  config.mjs                        ← Model 层：配置归一化与安全过滤
  server.mjs                        ← 入口：slot 渲染 + 后台页面/API
assets/
  home-carousel-client.js           ← 前台交互（触摸/键盘/动画/自动播放）
  home-carousel-admin.js            ← 后台入口（controller → view）
  home-carousel-admin.controller.js ← 状态管理（加载/保存/增删改排序）
  home-carousel-admin.view.js       ← 视图渲染（配置表单 + 轮播项列表）
  home-carousel-admin.css           ← 后台样式（.hc- 命名空间）

数据流

text
管理员配置 → POST /admin-api → normalizeCarouselConfig → writeConfig
                                                          ↓
访客访问首页 → readConfig → normalizeCarouselConfig → isSlideActive 过滤
                                                          ↓
                                          buildCarouselHtml → SSR HTML + CSS 变量
                                                          ↓
                                          clientModule 绑定交互事件

安全措施

XSS 防护 — 所有用户输入（图片 URL、标题、链接）经 escapeHtml 转义后输出
链接协议白名单 — 只允许 http:// https:// / # mailto: tel: 前缀，阻止 javascript: data: vbscript: 等危险协议
外链安全 — 外部链接自动添加 target="_blank" rel="noreferrer noopener"
配置归一化 — 所有配置值经类型检查和范围校验，高度限白名单、数字限下限

技术要点

CSS 变量注入配置

配置值通过内联 CSS 自定义属性传递，纯 CSS 生效，无需 JavaScript 介入：

html
<div class="h-carousel-track"
     style="--hc-height:280px;--hc-mobile-height:200px;--hc-object-fit:cover">

css
.h-carousel-track { height: var(--hc-height, 280px); }
@media (max-width: 768px) {
  .h-carousel-track { height: var(--hc-mobile-height, var(--hc-height)); }
}
.h-carousel-img { object-fit: var(--hc-object-fit, cover); }

滑动动画原理

通过 is-active 类控制 opacity 和 pointer-events，配合 transform 实现方向性滑动：

禁用 transition，设置入场幻灯片初始位置 translateX(±100%)
强制 reflow（void el.offsetWidth）提交初始状态
恢复 transition，添加 is-active 类，设置 transform: translateX(0)
出场幻灯片反向滑出

@media (prefers-reduced-motion: reduce) 自动禁用所有过渡动画。

定时上下架

过滤只发生在前台渲染（renderCarouselResult），不影响后台 API——管理员仍能看到和编辑已过期的轮播项。所有幻灯片过期时整个轮播图不渲染。

权限声明

text
config:read    — 读取轮播图配置
config:write   — 保存轮播图配置
slot:register  — 注册首页槽位
page:admin     — 注册后台管理页
api:admin      — 注册后台 API

兴趣节点

【插件】首页轮播图 home-carousel