新增板块与组件

本页说明如何在三个配置文件之外扩展本站：新增首页板块、新增页面与路由，以及需要遵守的开发约定。适用于新增「历年节目」板块、新页面等配置无法满足的需求。

新增一个首页板块

第 1 步：编写组件

在 src/components/ 新建组件，例如 ProgramsSection.jsx：

export default function ProgramsSection({ title, description, items }) {
  // props 就是 content.config.js 里这个板块配置项的全部字段
  return (
    <section id="programs" className="py-16 px-4">
      <h2 className="font-title text-3xl text-center gradient-text">{title}</h2>
      <p className="text-center text-[var(--text-secondary)] mt-2">{description}</p>
      {/* 用 items 渲染你自己的结构 */}
    </section>
  );
}

组件编写约定：

• 为最外层 <section> 设置与该板块 id 相同的 id 属性，primaryButton.targetId 才能滚动定位到该板块
• 颜色使用 CSS 变量（var(--page-bg)、var(--text-secondary)）或 Tailwind 品牌色（text-keqing-purple），避免写死色值，以自动适配浅色与深色模式
• 标题使用 font-title，正文使用 font-body
• 需要玻璃容器时，使用 <LiquidGlass> 或 <Glass> 组件，样式自动跟随 preset 预设

第 2 步：在 HomePage 注册

打开 src/pages/HomePage.jsx，导入新组件并注册到 sectionComponents：

import ProgramsSection from '../components/ProgramsSection';

const sectionComponents = {
  hero: HeroSection,
  coreContributors: CoreContributors,
  recruit: RecruitPanel,
  contact: ContactPanel,
  programs: ProgramsSection, // ← 新增，键 = 板块 id
};

第 3 步：在 content.config.js 添加配置

{
  id: 'programs',          // 必须与 sectionComponents 的键完全一致
  status: 'enable',
  title: '历年节目',
  description: '历届生日会的精彩节目回顾',
  items: [
    { year: 2024, name: '节目名称', link: 'https://www.bilibili.com/...' },
  ],
},

• 数组中的位置决定渲染顺序（hero 固定在最上方，不参与排序）
• 板块中自定义的字段（如上面的 items）会作为 props 原样传给组件

第 4 步：（可选）粒子层与动效

• 非 hero 板块会被 ContentParticles 粒子层自动包裹，无需额外处理
• 页面进入动画由 HomePage 统一控制，新板块自动包含在内
• 为卡片添加 glass-card-hover 类可实现悬停上浮效果（液态玻璃卡片使用 liquid-glass-hover），也可直接复用现有卡片样式

新增一个页面 / 路由

1. 在 src/pages/ 新建页面组件（可参考 AllContributorsPage.jsx）
2. 在 src/App.jsx 添加懒加载路由：

   const ProgramsPage = lazy(() => import('./pages/ProgramsPage'));
   
   <Route
     path="/programs"
     element={
       <Suspense fallback={<PageSpinner />}>
         <ProgramsPage />
       </Suspense>
     }
   />

3. 导航栏加入口：在 Navbar.jsx 的 rightNavLinks 加一项 { id: 'programs', label: '历年节目', to: '/programs' }
4. 在 scripts/prerender.js 的 routes 数组中加入新路径，使构建时预渲染该页面：

   const routes = ['/', '/contributors', '/programs'];

注意

新增路由后若未加入 prerender.js，该路由的 SEO 会退化为空壳 HTML，且部分托管平台上直接刷新深链可能返回 404。

开发约定

约定	原因
内容 / 文案 / 开关放配置文件，不写死在组件里	保持「配置驱动」，组员维护不用碰代码
颜色用 CSS 变量或 keqing-* 品牌色	深浅色、换肤自动适配
图标用 Lucide React	全站图标风格统一
图片走 OptimizedImage	自动懒加载（loading="lazy"）
提交前跑 npm run lint	保持代码风格一致

常见扩展场景

为轮播图添加文字说明

为 hero.slides 的每一项添加 caption 字段，并在 HeroSection.jsx 的 Swiper slide 中渲染。数据结构变化不影响板块 id，其它逻辑保持不变。

添加公告横幅

按「组件 + 注册 + 配置」三步新增一个 banner 板块，并将其置于 homeSections 数组的第一位（即 hero 之后第一个渲染）。

调整页脚结构

页脚并非配置驱动的布局。直接编辑 src/components/Footer.jsx：文本内容仍维护在 footerConfig 中，结构调整在组件内完成。