本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/待办事宜/FlintHub_公告插件_样式增强_方案.md。

FlintHub 公告插件「样式增强版」规划方案

状态：待拍板（未动一行代码）

对象：plugins/announcements（已启用，plugin.json version 1.3.0）

依据：docs/插件开发规范.md、docs/插件审计报告.md、本机实测

编写：2026-10-11

0. 一句话结论

在现有 plugins/announcements 上做增强（不新建插件）：把「样式」从一维配色升级为

二维正交模型（容器模式 × 条目布局），新增 4 种容器模式 + 5 种条目布局 + 7 种配色 + 每条可选图标，

并顺手整改 4 处既有缺陷。全部走主题变量、零内联、向后兼容（老数据零迁移成本）。

1. 现状盘点（有据）

1.1 顺带发现的 4 处既有缺陷（本次一并整改）

2. 设计原则（5 条硬约束）

1. 零内联：配色走 class（ann-style-*），图标写字面量 <i class="fa mn-fs-16">&#xf0a1;</i>。

⚠️ 不用 $view->icon() —— 它返回值恒带 style="font-size:Npx"，是零内联门禁的漏网点（规范 §9.3 模板本身就有这个毛病）。

1. **颜色一律 --mn-* 变量 + fallback**（§11.7）。已实测 10/10 样式源都有定义的：

--mn-bg-card / --mn-border / --mn-border-light / --mn-text / --mn-text-secondary /

--mn-text-muted / --mn-primary / --mn-primary-subtle / --mn-success / --mn-warning /

--mn-error / --mn-shadow-sm / --mn-bg-body / --mn-bg-input / --mn-tag-bg。

⚠️ --mn-danger 不存在（0/10），别用；要红色用 --mn-error。

1. 向后兼容：style 字段语义不变（仍是配色），老数据 green/red/blue 渲染结果逐像素不变；

新增列全部有 DEFAULT，老行自动取值。

1. 极简：默认不出现无意义控件 —— 无 url 不出链接/箭头；只有 1 条不出切换器；布局本身不需要关闭按钮的就不给。
2. 不动核心：不新增钩子、不改 app/。现有 3 个注入点够用。

3. 样式体系设计（核心）

3.1 两个正交维度

                    条目布局（每条 1 个）              配色（每条 1 个）
容器模式（全局 1 个）  ── 一条公告「长什么样」    ×    ── 强调色是什么
  └ 多条公告「怎么排」

为什么拆两维而不是做「样式模板」：模板是「布局 × 配色」的笛卡尔积，12 个模板 = 12 份 CSS 且不能混搭；

两维只需 5 份布局 CSS + 13 份配色变量，任意组合且 CSS 不膨胀。

3.2 容器模式（全局，announcement_mode，5 种）

carousel 就是图 1（FlatBB）右侧那对箭头的正确归属 —— 它是「多条怎么排」，不是「一条长什么样」。

3.3 条目布局（每条，layout 字段，6 种）

L1 notice — 通知条（图 1 FlatBB 同款）

┌────────────────────────────────────────────────────────────────┐
│  🔊  Notice:  站点将于今晚 23:00 维护    2026-09-06      ‹  ›  │
└────────────────────────────────────────────────────────────────┘

• 容器：--mn-bg-card 底 + --mn-border 细边 + 圆角 999px（胶囊），padding: 9px 18px
• 左：图标（默认 announcement 喇叭，16px，色 = 强调色）
• 前缀标签：加粗 + 强调色，文案取全局设置 announcement_label（默认「公告」）
• 正文：--mn-text，600 字重
• 右：日期（--mn-text-muted，13px，取 created_at 的 Y-m-d）
• 最右：‹ › 箭头（仅当 mode=carousel 且条数 > 1）
• 无 ×（图 1 没有）

L2 badge — 标签式（图 2 XIUNOX 同款）

┌────────────────────────────────────────────────────────────────┐
│  [ 📢 公告 ]  XIUNOX站点出错了怎么办？怎么反馈 Bug？            │
└────────────────────────────────────────────────────────────────┘

• 容器：--mn-bg-card 底 + --mn-border 细边 + 圆角 8px，padding: 8px 14px
• 左：实心圆角色块徽章（底 = 强调色，白字，圆角 6px，padding: 4px 10px，内为 14px 图标 + 标签文案）
• 右：文本，色 = 强调色，hover 下划线（整条可点，有 url 时）
• 无 ×、无日期（图 2 没有）

L3 bar — 经典条（现有默认，视觉不变）

┌────────────────────────────────────────────────────────────────┐
│  站点将于今晚 23:00 维护，预计 30 分钟。                    ×  │
└────────────────────────────────────────────────────────────────┘

• 完全沿用 assets/style.css:2 的现有定义 → 老数据零视觉变更
• 配色决定整条「底色 + 边框 + 文字色」

L4 minimal — 极简左边框

┃ 站点将于今晚 23:00 维护，预计 30 分钟。

• 无图标、无边框、无背景；左侧 4px 强调色竖条（border-left），圆角 0
• 文字 --mn-text；最不打扰的一种，适合「常驻但不抢眼」

L5 alert — 图标提示条（类 Bootstrap alert）

┌────────────────────────────────────────────────────────────────┐
│  ( ⓘ )   站点维护通知                                     ×    │
│          今晚 23:00–23:30 暂停访问                              │
└────────────────────────────────────────────────────────────────┘

• 左：36px 圆形强调色底 + 白图标
• 右侧两行：标题（title 字段，粗，--mn-text）+ 描述（content，--mn-text-secondary）
• 右：× 关闭
• ⚠️ 需要新字段 title

L6 card — 图文卡片

┌────────────────────────────────────────────────────────────────┐
│  [ 📰 ]   站点全面升级 FlintHub                        查看 →  │
│           基于 PHP + SplitDB 的新一代社区系统                   │
└────────────────────────────────────────────────────────────────┘

• 左：48px 方形圆角强调色淡底（--mn-primary-subtle 类）+ 强调色图标
• 右：标题（title）+ 一行摘要（content 截断，Content::excerpt）
• 最右：查看 →（有 url 才出现）
• ⚠️ 需要新字段 title

3.4 配色（每条，style 字段，13 种）

配色统一只定义 4 个 CSS 变量：--ann-accent（强调色）/ --ann-bg / --ann-border / --ann-text。

布局类决定怎么用这 4 个变量 → 布局 × 配色 = 6 × 13 = 78 种组合，零额外 CSS。

设计要点：notice / badge / minimal / alert / card 这 5 种布局的底色统一走 --mn-bg-card，

配色只决定强调色（图标/徽章/左边框/链接色）。这样：

① 暗色主题下这 5 种布局天然可读（不会白底发光）；② 配色切换只换强调色，观感克制。

3.5 图标（每条，icon 字段，新增）

• 下拉选 20 个已在核心 $map 内的公告向图标（已实测 448 字形子集全覆盖）：

announcement(喇叭) / bell / info / warning / newspaper / flag / lightbulb / rocket /

gift / star / tag / tags / heart / comment / book-open / clock / calendar /

check / plus / fire

• 空值 → 按布局给默认（notice/badge/alert → announcement；card → newspaper；minimal/bar → 无图标）
• ⚠️ 只从 $map 里挑，不自造码点（陷阱 §A.14：自造码点 = 静默方块，须重跑 build_font_subset.py）

3.6 其余行为约定

4. 数据模型变更

ALTER TABLE announcements ADD COLUMN layout TEXT NOT NULL DEFAULT 'bar';   -- 条目布局
ALTER TABLE announcements ADD COLUMN icon   TEXT NOT NULL DEFAULT '';      -- 图标名（空=按布局默认）
ALTER TABLE announcements ADD COLUMN title  TEXT NOT NULL DEFAULT '';      -- alert/card 的标题行

迁移方式（三步，缺一即静默失效 —— 规范 §11.33 / 陷阱 142）：

1. Plugin.php 的 ddl() 里的 CREATE TABLE 同步加上这 3 列（只对新装站点生效）；
2. 新增 ensureColumnPatches()：PRAGMA table_info 判存在 → 缺则 ALTER TABLE ADD COLUMN（对存量库生效，幂等）；
3. 改门控标记：现有 hook/init_after.php:14 用 Settings::get('_announcements_migrated') 门控

→ 改成 _announcements_schema_v = '2'（值随版本变，否则老站覆盖上传后补丁根本不跑）。

⚠️ 现有 init_after.php 无「戳文件」门控，每次请求都跑一遍 activate()（内含 CREATE TABLE IF NOT EXISTS）

→ 已超「单插件每请求所有 hook 查询总和 ≤ 5」红线。本次顺带补上戳文件门控（照 points_mall / qa 范式）。

5. 文件改动清单

不改动：app/ 任何文件、assets/css/*、其他插件。

6. 后台 UI 设计

┌─ 站点公告管理 ────────────────────────────────────────────────┐
│                                                               │
│ ① 添加公告                                                    │
│   内容 *  [__________________________]                        │
│   标题    [__________________]  ← 仅 alert / card 布局用      │
│   链接    [https://...]                                       │
│   条目布局 [经典条 ▾]   配色 [跟随主题 ▾]   图标 [🔊 喇叭 ▾]  │
│   排序     [0]                                                │
│           ┌──────────────────────────────────────────────┐    │
│           │ 🔊 公告:  预览文本…             2026-10-11   │    │  ← 实时预览
│           └──────────────────────────────────────────────┘    │
│                              [ 添加公告 ]                     │
│                                                               │
│ ② 展示设置（全局）                                            │
│   展示模式 [箭头轮播 ▾]   标签文案 [公告]   [ 保存 ]          │
│   提示：箭头轮播 / 列表卡 / 跑马灯 会忽略每条公告的条目布局    │
│                                                               │
│ ③ 已有公告（共 3 条）                                         │
│   [经典条·浅绿] 本站全面升级 FlintHub…        [编辑] [删除]   │
│   …                                                           │
└───────────────────────────────────────────────────────────────┘

布局选择器要点：下拉每项显示「名称 + 一句话说明」；下方给实时预览条（用当前表单值渲染，纯 CSS，无网络请求）。

选 list / marquee 容器模式时，条目布局下拉置灰并提示「该模式下不生效」（避免「选了没反应」的困惑）。

7. 风险与红线（写代码时必须逐条对）

8. 分阶段实施计划（建议）

P0 — 骨架 + 二维模型落地（最小可用）

• 数据模型三步迁移（layout / icon / title）
• Plugin.php 常量与取值函数；AdminController 校验
• hook/announcements_display.php 按 layout 分流，先实现 bar（现有）+ badge（图 2）+ notice（图 1）
• CSS：抽 4 变量 + 3 种布局
• 后台：3 个新控件 + 预览条
• 验收：老 3 条数据渲染逐像素不变；图 1 / 图 2 效果可复现

P1 — 容器模式扩充

• 新增 carousel（箭头/圆点/自动播放）、list、marquee
• 后台「展示模式」下拉 5 项 + 联动置灰
• 验收：5 种模式各跑一遍；单条时不出现切换器；hover 暂停生效

P2 — 布局与配色补全 + 既有缺陷整改

• 新增 minimal / alert / card 布局
• 配色扩到 13 项（含 theme 跟随主题）
• 修 D1（重写 说明.md）、D2（弹窗移入 .admin-content）、D3（配色变量化）、D4（defer）
• 验收：暗夜星辰主题下 6 种布局逐一走查可读

P3（可选，需你拍板）— 全站通栏注入

• 新增 layout_body_end 注入点，让公告可显示在全站每页顶部（不限于 3 个列表页）
• ⚠️ 代价：游客页永久缓存会缓存公告 → 每次改公告都要清缓存；且会出现在后台页（需按 template 排除）

工作量粗估：P0 ≈ 半天，P1 ≈ 半天，P2 ≈ 半天，P3 ≈ 2 小时。总计 1.5~2 个工作日（不含你验收与出包）。

9. 验证方案

10. 待你拍板的 6 个点

附：两张参考图的样式归属