🧭 一、背景：在 WordPress Header 中增加诗词微内容模块
在优化 WordPress 站点 Header 时，我希望增加一个轻量级“文化微内容组件”，用于展示：
- 唐诗
- 宋词
- 南唐诗词
目标是：
✔ 不影响布局
✔ 不影响性能
✔ 保持 Header 稳定性
✔ 提供轻微文化氛围
🧪 二、第一版本：尝试 CSS 动画滚动诗词
最初实现方案使用了 CSS animation：
CSS
animation: poetryScroll 14s linear infinite;并通过 PHP 输出诗词：
PHP
return '<div class="poetry-marquee-wrapper"> <span class="poetry-marquee-static">' . esc_html($random) . '</span></div>';⚠️ 出现的问题：
- ❌ Header 布局轻微抖动
- ❌ FSE Row 结构不稳定
- ❌ 长诗句截断异常
- ❌ 不同语言环境错位
- ❌ UI 层级背景冲突
🧠 三、关键决策：放弃动画，改为静态组件
最终确认：
❗Header 区域不适合复杂动效组件
因此整体方案收敛为：
- ❌ 去掉 animation
- ✔ 改为静态展示
- ✔ 强化 PHP 内容控制
🧩 四、最终实现方案（稳定版 PHP）
PHP
function wp_header_poetry() {
$files = [
'唐诗' => WP_CONTENT_DIR . '/uploads/tangshi-sanbai-shou.json',
'宋词' => WP_CONTENT_DIR . '/uploads/songci-sanbai-shou.json',
'南唐' => WP_CONTENT_DIR . '/uploads/nantang.json',
];
$pool = [];
foreach ($files as $type => $file) {
if (!file_exists($file)) continue;
$json = file_get_contents($file);
$data = json_decode($json, true);
if (!is_array($data)) continue;
foreach ($data as $item) {
if (
!isset($item['author'], $item['paragraphs']) ||
!is_array($item['paragraphs']) ||
empty($item['paragraphs'])
) {
continue;
}
$author = trim($item['author']);
$paragraphs = array_map('trim', $item['paragraphs']);
$text = implode('', $paragraphs);
// =========================
// ✂️ 智能截断（优化体验）
// =========================
if (mb_strlen($text, 'UTF-8') > 60) {
$text = mb_substr($text, 0, 60, 'UTF-8');
$pos1 = mb_strrpos($text, '。', 0, 'UTF-8');
$pos2 = mb_strrpos($text, '，', 0, 'UTF-8');
$pos1 = ($pos1 === false) ? 0 : $pos1;
$pos2 = ($pos2 === false) ? 0 : $pos2;
$pos = max($pos1, $pos2);
if ($pos > 30) {
$text = mb_substr($text, 0, $pos + 1, 'UTF-8');
}
}
// =========================
// 🏷 标题处理
// =========================
$title = ($type === '宋词')
? ($item['rhythmic'] ?? '')
: ($item['title'] ?? '');
$title = trim($title);
// =========================
// 🧱 拼接展示内容
// =========================
$display = "【{$type}】";
if (!empty($title)) {
$display .= "《{$title}》";
}
$display .= " {$author}：{$text}";
if (mb_strlen($display, 'UTF-8') <= 90) {
$pool[] = $display;
}
}
}
if (empty($pool)) {
return '';
}
$random = $pool[array_rand($pool)];
return '<div class="poetry-marquee-wrapper">
<span class="poetry-marquee-static">' . esc_html($random) . '</span>
</div>';
}
echo wp_header_poetry();
🎨 五、最终 CSS（稳定版）
CSS
.poetry-marquee-wrapper {
display: inline-flex;
align-items: center;
padding: 0 10px;
min-width: 0;
}
.poetry-marquee-static {
font-size: 14px;
line-height: 1;
opacity: 0.75;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
min-width: 0;
}
.wp-block-group.is-layout-flex {
align-items: center;
}
header.wp-block-template-part {
box-sizing: border-box;
}
🧭 六、主题编辑器最终布局结构（修正后）
当前 Header 在 FSE 中的正确结构：
Plaintext
Header (Template Part)
└── Group (Outer Container)
└── Row (Flex Layout)
├── Poetry Shortcode（左侧）
├── Search（右侧组）
└── Language Switcher（右侧组）关键点：
- ✔ Row 必须统一
- ✔ 左右对齐靠 flex
- ✔ poetry 必须在同一 Row 内
📦 七、诗词数据来源（GitHub）
本系统使用结构化 JSON 诗词数据：
- 唐诗三百首
- 宋词三百首
- 南唐词作
🔗 数据来源
Plaintext
https://github.com/chinese-poetry/chinese-poetry📁 JSON 结构说明
JSON
{
"author": "作者",
"title": "标题（唐诗/南唐）",
"rhythmic": "词牌名（宋词）",
"paragraphs": [
"诗句1",
"诗句2"
]
}🧠 数据处理规则
- paragraphs 直接拼接
- 不额外添加标点（避免“。，”问题）
- 自动截断至 60 字
- Header 只展示一条
🚀 八、工程化收敛总结
本次实现经历三个阶段：
1️⃣ 动效阶段
- CSS marquee
- layout 抖动
- 不稳定 ❌
2️⃣ 调试阶段
- flex + padding + FSE 调整
- 复杂度上升 ❌
3️⃣ 收敛阶段（最终）
- 静态组件 ✔
- PHP 控制内容 ✔
- CSS 最小化 ✔
- 结构稳定 ✔
🧠 九、最终结论
本次优化的核心经验是：
❗Header 区域应优先保证稳定性，而非视觉复杂度
WordPress 网站维护、性能优化与博客运营咨询
本站已持续运营超过 10 年，累计发布 1000+ 篇原创技术文章，长期实践 WordPress 网站建设、CDN / Cloudflare 配置、缓存优化、Google SEO、广告变现和多语言网站运营。
如果你的 WordPress 网站遇到访问慢、缓存异常、插件冲突、广告不显示、SEO 基础结构混乱、CDN 配置不确定等问题，可以联系我做一次远程技术排查。
适合以下用户：
✅ 个人博客站长
✅ WordPress 网站运营者
✅ 独立开发者与内容创作者
✅ SaaS 产品官网运营团队
✅ 希望优化网站速度与稳定性的站点
服务内容：
✅ WordPress 速度优化
✅ Cloudflare / CDN / 缓存配置排查
✅ 插件冲突与页面异常排查
✅ AdSense 广告显示问题排查
✅ SEO 基础结构检查
✅ 博客运营与商业化咨询
如需了解方案或交流相关问题，请直接联系我，并注明：WordPress 维护咨询。
联系方式：
Telegram：@shuijingwan
微信：13980074657
邮箱：shuijingwanwq@gmail.com