公告通知（announcement）
一个用于向访客展示公告 / 通知的 AeroCore 子主题组件。漂亮、响应式、自动适配深色模式，可单条展示，也可多条轮播。
| 项目 | 内容 |
| 组件 ID | announcement |
| 名称 | 公告通知 |
| 版本 | 1.0.0 |
| 作者 | 已名知名 |
| 作者主页 | https://8src.com/ |
| 父主题 | AeroCore |
| 适用页面 | 首页（home）、文章页（article） |
| 依赖 | 父主题 AeroApi、主题 CSS 变量（深色模式）、packages/ 自动加载机制 |
一、功能简介
本组件用于在站点显眼位置向用户传达公告信息（活动、维护、更新、规则等）。设计目标：好看、不挡事、哪儿都能放。
- 四种语义类型：信息（蓝）/ 成功（绿）/ 警告（黄）/ 危险（红），左侧强调色条 + 圆形图标自动区分。
- 单条 & 多条轮播：填一条就单条展示；填多条进入轮播模式，自动切换 + 左右箭头 + 指示点（悬停暂停）。
- 滚动置顶固定：开启后组件吸顶（
position: sticky），访客滚动页面时始终可见。
- 自动消失倒计时：开启后底部进度条实时倒计时，到点自动隐藏；鼠标悬停暂停，离开继续。
- 手动关闭：访客可点关闭按钮，关闭状态写入
localStorage，同配置不再出现。
- 响应式：flex 布局 +
min-width:0防撑破，窄屏（≤480px）自动收窄，长链接/长文本自动换行。
- 深色模式自适应：全部用主题 CSS 变量（
--bg-card/--text-primary/--border-primary及状态色），浅/深自动切换，无需手写html[data-theme="dark"]。
二、目录结构
```
packages/announcement/
├─ index.php # 组件配置：form_schema、default_data、元数据
├─ render.php # 渲染输出（严格转义）
├─ style.css # 卡片样式、轮播/进度条/指示点、深色模式、响应式
├─ main.js # 关闭、轮播、倒计时逻辑（rAF 驱动、悬停暂停）
└─ README.md # 本说明
```
文件放入 packages/announcement/ 后，CSS / JS 由 AeroCore 自动加载，无需手动 enqueue。
三、配置项说明
1. 单条模式（不填「多条公告」时生效）
| 配置项 | 类型 | 默认 | 说明 |
| 公告标题 | text | 重要公告 |
单条公告标题 |
| 公告内容 | textarea | 示例文案 | 单条正文，支持基础安全 HTML（<a> <b> <br> <strong> 等），已用 wp_kses_post 过滤 |
| 公告类型 | select | info |
info / success / warning / danger 四选一 |
| 自定义图标 | icon_picker | 空 | 留空用类型默认图标；填写则覆盖 |
| 按钮链接 | link | 空 | 留空不显示按钮 |
| 按钮文字 | text | 查看详情 |
按钮上显示的文字 |
| 允许访客手动关闭 | switch | 开 | 关闭后写入 localStorage 记忆 |
| 滚动时置顶固定 | switch | 关 | 开启后吸顶可见 |
| 自动消失 | switch | 关 | 开启后倒计时结束自动隐藏（不记忆，每次加载触发） |
| 自动消失秒数 | number | 5 |
与「自动消失」配合，≥1 |
2. 多条轮播模式（填写「多条公告」后生效）
| 配置项 | 类型 | 说明 |
| 多条公告 | list | 每项含：标题、内容、类型、图标、按钮链接、按钮文字；填了此项即忽略上方所有单条字段，进入轮播 |
| 轮播间隔秒数 | number | 多条时每条停留秒数，≥1，悬停暂停 |
轮播项内字段与单条模式一一对应，可每条单独设定类型 / 图标 / 按钮。
四、使用步骤
- 将整个
packages/announcement/目录复制到你的AeroCore-Child/packages/下。
- 后台「主题设置 → 页面布局 → 第三方组件」中找到 「公告通知」，拖入画布。
- 在右侧面板配置标题 / 内容 / 类型 / 按钮 / 增强开关（置顶、自动消失、轮播）等。
- 保存页面布局。
常见问题
- 后台看不到新组件：重新保存一次「页面布局」以刷新组件缓存。
- 样式未生效：清除浏览器缓存（AeroCore 对已加载资源附带
filemtime版本号，通常刷新即可）。
- 改了配置不更新：删除旧组件实例、重新添加一次（AeroCore 会缓存组件 schema）。
五、类型与样式对照
| 类型 | 强调色（变量） | 默认图标 | 适用场景 |
| 信息 info | --theme-color |
铃铛 | 通知、说明、新功能 |
| 成功 success | --color-success |
对勾 | 上线、达成、通过 |
| 警告 warning | --color-warning |
感叹号 | 维护、限额、注意 |
| 危险 danger | --color-danger |
叉号 | 故障、封禁、紧急 |
深色模式下配色由主题变量自动切换，无需额外处理。
六、交互逻辑（main.js 摘要）
- 手动关闭：点击关闭按钮 → 隐藏组件 → 把
key（取自组件配置）写入localStorage，再次加载同 key 不再显示。
- 轮播：多条时启动
requestAnimationFrame计时，到点切下一条；左右箭头可手动切换；指示点显示当前位置；鼠标悬停暂停。
- 自动消失：开启后进度条随倒计时收缩，归零自动隐藏；悬停暂停，离开恢复。
- 所有计时基于
requestAnimationFrame，切换标签页/后台时自动降频，省电且不漂移。
七、开发约束（遵循 AeroCore 子主题规范）
render.php中不写use AeroCore\xxx；取数一律走AeroApi::option()等父主题接口。
- 输出转义：标题 / 图标用
esc_html()，链接用esc_url()，HTML 属性用esc_attr()，正文用wp_kses_post()放行安全基础 HTML。
id唯一且目录名与id一致（announcement），导入时自动落盘到同名目录。
- 样式全部使用主题 CSS 变量，保证深浅色与站点主题一致。