喵洛阁

Astro 博客课程表页面实现教程

Mon, 13 Apr 2026 10:28:51 +0800

Astro 博客课程表页面实现教程

前言

本文详细讲解如何使用 Astro + TypeScript 构建一个功能完整的课程表页面，包括数据结构设计、数据解析、组件架构等核心知识点。

整体架构

课程表页面采用分层设计：

数据层 - JSON 文件存储课程数据
解析层 - TypeScript 工具函数解析 JSON 并计算当前周次
类型层 - 定义完整的数据类型系统
组件层 - Astro 组件负责渲染页面结构
交互层 - 客户端脚本实现实时状态更新

数据结构设计

JSON 数据格式

课程数据存储在一个 JSON 文件中，包含以下字段：

{
  "config": {
    "courseLen": 2,
    "id": 1,
    "name": "默认配置"
  },
  "nodeTimes": [{ "node": 1, "startTime": "08:00", "endTime": "09:40", "timeTable": 1 }],
  "meta": {
    "id": 1,
    "tableName": "大三下",
    "maxWeek": 20,
    "nodes": 10,
    "startDate": "2026-3-2",
    "timeTable": 1,
    "showSat": false,
    "showSun": false
  },
  "courseDefinitions": [{ "id": 1, "courseName": "计算机网络", "color": "#FF6B6B" }],
  "arrangements": [
    {
      "id": 1,
      "day": 1,
      "startNode": 1,
      "step": 2,
      "startWeek": 1,
      "endWeek": 16,
      "teacher": "张老师",
      "room": "A101"
    }
  ]
}

TypeScript 类型定义

// 配置段
interface TimetableConfigSegment {
  courseLen: number
  id: number
  name: string
}

// 节次时间
interface TimetableNodeTime {
  node: number
  startTime: string
  endTime: string
  timeTable: number
}

// 元数据
interface TimetableMetaSegment {
  id: number
  tableName: string
  maxWeek: number
  nodes: number
  startDate: string
  timeTable: number
  showSat?: boolean
  showSun?: boolean
}

// 课程定义
interface TimetableCourseDefinition {
  id: number
  courseName: string
  color?: string
}

// 课程安排
interface TimetableCourseArrangement {
  id: number
  day: number
  startNode: number
  step: number
  startWeek: number
  endWeek: number
  teacher?: string
  room?: string
}

// 解析后的完整数据
interface ParsedTimetableData {
  config: TimetableConfigSegment
  nodeTimes: TimetableNodeTime[]
  meta: TimetableMetaSegment
  courseDefinitions: TimetableCourseDefinition[]
  arrangements: TimetableCourseArrangement[]
}

数据解析层

JSON 解析器

const EXPECTED_SEGMENT_COUNT = 5

function parseJsonLine(line: string, lineNumber: number): T {
  const normalizedLine = line.endsWith(',') ? line.slice(0, -1) : line
  try {
    return JSON.parse(normalizedLine) as T
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error)
    throw new Error(`课表数据解析失败：第 ${lineNumber} 行不是合法 JSON（${message}）`)
  }
}

export function parseTimetableText(rawText: string): ParsedTimetableData {
  const lines = rawText
    .split(/\r?\n/)
    .map((line) => line.trim())
    .filter((line) => line.length > 0)

  if (lines.length !== EXPECTED_SEGMENT_COUNT) {
    throw new Error(`课表数据结构错误：必须恰好包含 ${EXPECTED_SEGMENT_COUNT} 段 JSON`)
  }

  const segments = lines.map((line, index) => parseJsonLine(line, index + 1))
  const [config, nodeTimes, meta, courseDefinitions, arrangements] = segments

  return {
    config: config as TimetableConfigSegment,
    nodeTimes: nodeTimes as TimetableNodeTime[],
    meta: meta as TimetableMetaSegment,
    courseDefinitions: courseDefinitions as TimetableCourseDefinition[],
    arrangements: arrangements as TimetableCourseArrangement[],
  }
}

当前周计算

function parseDateFromYmd(ymd: string): Date | null {
  const parts = ymd.split('-').map((part) => Number(part))
  if (parts.length !== 3 || parts.some((part) => !Number.isFinite(part))) {
    return null
  }
  const [year, month, day] = parts
  return new Date(year, month - 1, day)
}

export function resolveCurrentWeek(
  startDateText: string,
  maxWeek: number,
  now: Date = new Date(),
): number {
  const startDate = parseDateFromYmd(startDateText)
  if (!startDate) {
    return 1
  }

  const msPerDay = 24 * 60 * 60 * 1000
  const diffDays = Math.floor((now.getTime() - startDate.getTime()) / msPerDay)
  const week = Math.floor(diffDays / 7) + 1

  if (week < 1) return 1
  if (week > maxWeek) return 1
  return week
}

页面路由设计

首页路由

---
import fs from 'node:fs'
import path from 'node:path'
import type { TimetableViewModel } from '@/types/timetable'
import TimetablePageContent from '@components/timetable/TimetablePageContent.astro'
import MainGridLayout from '@layouts/MainGridLayout.astro'
import { buildTimetableViewModel, resolveCurrentWeek } from '@utils/timetable-normalizer'
import { parseTimetableFile } from '@utils/timetable-parser-server'

const filePath = 'src/data/timetable/大三下.json'
const absoluteFilePath = path.join(process.cwd(), filePath)

let viewModel: TimetableViewModel | null = null
let loadError = ''
let isCurrentWeek = false
let baselineText = ''

try {
  baselineText = fs.readFileSync(absoluteFilePath, 'utf-8')
  const parsedData = parseTimetableFile(filePath)
  const currentWeek = resolveCurrentWeek(parsedData.meta.startDate, parsedData.meta.maxWeek)
  viewModel = buildTimetableViewModel(parsedData, currentWeek)
  isCurrentWeek = viewModel.currentWeek === currentWeek
} catch (error) {
  loadError = error instanceof Error ? error.message : '课表数据加载失败'
}
---


  {
    viewModel ? (
      
    ) : (
      
        课表加载失败：{loadError}
      
    )
  }

动态路由

---
const weekParam = Number(Astro.params.week)

// 使用 URL 参数中的周次，如果无效则使用当前周
const selectedWeek =
  Number.isFinite(weekParam) && weekParam >= 1 ? Math.floor(weekParam) : currentWeek

// 生成所有周次的静态路径
export function getStaticPaths() {
  const parsedData = parseTimetableFile('src/data/timetable/大三下.json')
  const maxWeek = Math.max(1, parsedData.meta.maxWeek || 1)
  return Array.from({ length: maxWeek }, (_, index) => ({
    params: { week: String(index + 1) },
  }))
}
---

组件层实现

页面容器组件

---
import type { TimetableViewModel } from '@/types/timetable'
import LiveTimetableStatus from '@components/timetable/LiveTimetableStatus.astro'
import TimetableDayList from '@components/timetable/TimetableDayList.astro'
import TimetableGrid from '@components/timetable/TimetableGrid.astro'

interface Props {
  viewModel: TimetableViewModel
  isCurrentWeek?: boolean
  baselineText: string
}

const { viewModel, isCurrentWeek = false, baselineText } = Astro.props

const liveStatusPayload = {
  coursesByDay: viewModel.coursesByDay,
}
---


  
  
    {viewModel.tableName}
    共 {viewModel.maxWeek} 周
  

  
  
     上一周 
    
      第 {viewModel.currentWeek} 周
    
     下一周 
    {
      isCurrentWeek && (
        
          当前周
        
      )
    }

桌面端网格组件

---
import type { TimetableCourseView } from '@/types/timetable'
import TimetableCourseCard from '@components/timetable/TimetableCourseCard.astro'

interface Props {
  viewModel: TimetableViewModel
}

const { viewModel } = Astro.props

const dayIndexes = viewModel.dayColumns.map((day) => day.day)
const dayCount = viewModel.dayColumns.length

// 构建课程查找表
const courseMapByDayAndNode = new Map()

for (const day of dayIndexes) {
  for (const course of viewModel.coursesByDay[day] ?? []) {
    const pairStartNode = course.startNode % 2 === 1 ? course.startNode : course.startNode - 1
    const key = `${day}-${Math.max(1, pairStartNode)}`
    const list = courseMapByDayAndNode.get(key) ?? []
    list.push(course)
    courseMapByDayAndNode.set(key, list)
  }
}
---


  
  
    节次
    {
      viewModel.dayColumns.map((day) => (
        
          {day.label}
        
      ))
    }
  

  
  {
    viewModel.nodeRows
      .filter((row) => row.node % 2 === 1)
      .map((row) => (
        
          
            
              第 {row.node}-{Math.min(row.node + 1, viewModel.nodeRows.length)} 节
            
            {row.startTime}
          

          {viewModel.dayColumns.map((day) => {
            const key = `${day.day}-${row.node}`
            const courses = courseMapByDayAndNode.get(key) ?? []
            return (
              
                {courses.length > 0 ? (
                  
                    {courses.map((course) => (
                      
                    ))}
                  
                ) : (
                  
                    —
                  
                )}
              
            )
          })}
        
      ))
  }

实时状态组件

---
import type { TimetableCourseView } from '@/types/timetable'

interface Props {
  payload: {
    coursesByDay: Record
  }
}

const { payload } = Astro.props
const payloadText = encodeURIComponent(JSON.stringify(payload))
---


  状态计算中...
  
    下一堂课：
    --

样式与交互

响应式设计

课表页面使用了响应式设计，桌面端显示网格，移动端显示列表：

在组件内部使用 Tailwind 的响应式类控制显示：


...


...

颜色生成

每个课程卡片都有一个唯一的颜色，通过哈希函数生成：

function hashText(input: string): number {
  let hash = 0
  for (let i = 0; i < input.length; i += 1) {
    hash = (hash * 31 + input.charCodeAt(i)) | 0
  }
  return Math.abs(hash)
}

function buildCourseColor(courseName: string, courseId: number): string {
  const seed = hashText(`${courseName}-${courseId}`)
  const hue = seed % 360
  return `hsl(${hue} 78% 68%)`
}

使用 HSL 颜色模式，固定饱和度和亮度，只改变色相，这样生成的颜色既多样又和谐。

可视化编辑器（进阶）

TimetableVisualEditor.svelte 是一个功能完整的可视化编辑器，让用户可以直接在浏览器里增删改课程。

核心功能

双栏布局 - 左侧课程列表，右侧属性编辑面板
编辑模式 - 提供"编辑课表"和"退出编辑"按钮
数据验证 - 实时验证课程数据的合法性
导出功能 - 将编辑后的数据导出为 JSON 文件

状态管理

let editMode = false // 是否处于编辑模式
let draftParsed: ParsedTimetableData // 编辑中的数据副本
let selectedArrangementRef: number | null // 当前选中的课程索引
let validationError = '' // 验证错误信息
let isDirty = false // 数据是否有修改
let creatingCourse = false // 是否正在创建新课程

表单验证

function validateDraft(data: ParsedTimetableData): string {
  for (let index = 0; index < data.arrangements.length; index += 1) {
    const arrangement = data.arrangements[index]

    if (arrangement.day < 1 || arrangement.day > 7) {
      return `第 ${index + 1} 条课程安排的星期超出范围（1-7）`
    }

    if (arrangement.startNode < 1 || arrangement.startNode > maxNode) {
      return `第 ${index + 1} 条课程安排的起始节次超出范围`
    }

    if (arrangement.startWeek > arrangement.endWeek) {
      return `第 ${index + 1} 条课程安排的起止周非法`
    }

    const courseDef = data.courseDefinitions.find((c) => c.id === arrangement.id)
    if (!courseDef || !courseDef.courseName?.trim()) {
      return `第 ${index + 1} 条课程安排关联课程名为空`
    }
  }
  return ''
}

数据导出

function exportJson() {
  const error = validateDraft(draftParsed)
  if (error) {
    validationError = error
    return
  }

  const text = serializeTimetableDataToFileText(draftParsed)
  const blob = new Blob([text], { type: 'application/json;charset=utf-8' })
  const url = URL.createObjectURL(blob)

  const link = document.createElement('a')
  link.href = url
  link.download = `${baselineParsed.meta.tableName || 'timetable'}.json`
  document.body.appendChild(link)
  link.click()
  document.body.removeChild(link)
  URL.revokeObjectURL(url)
}

总结

通过这篇文章，我们详细解析了一个完整的课程表页面的实现过程：

数据层 - 设计了清晰的 JSON 数据结构，分离配置、定义和安排

类型层 - 使用 TypeScript 定义完整类型，确保类型安全

解析层 - 实现 JSON 解析、数据转换和当前周计算

路由层 - 使用 Astro 动态路由生成所有周次页面

组件层 - 拆分多个组件，实现网格布局、列表布局、课程卡片

交互层 - 客户端脚本实现实时状态更新

编辑层 - 可视化编辑器支持增删改课程

可扩展的功能

如果你想进一步完善这个课表页面，可以考虑：

多课表支持 - 支持切换不同学期的课表
课程提醒 - 上课前发送浏览器通知
导出功能 - 导出为 ICS 日历文件
数据同步 - 从教务系统自动同步课程

希望这篇教程对你有帮助！

waline使用neon数据库和在vercel部署

Sat, 11 Apr 2026 17:09:31 +0800

文章介绍了使用Waline和neon数据库在Vercel上部署博客的过程。首先，需要创建数据库并配置存储服务，然后定义数据库名称并执行创建表操作。接下来，通过点击顶部按钮重新部署，使数据库服务生效。最后，添加环境变量并进入项目页面进行"Redeploy"操作，使变量生效。

waline使用neon数据库和在vercel部署

由于Leancloud已于26年年初开始逐步停止服务，并在明年年初将停运，于是，使用neon数据库来替代，基于Waline的官方文档来进行部署，但是遇到了问题，再参考文章来完善部署方案。

在部署博客的过程中，我选取Waline作为评论系统，于是根据文档来部署：

点击上方按钮来部署

但是目前部署会出现下图的问题

创建数据库

点击顶部的 Storage 进入存储服务配置页，选择 Create Database 创建数据库。Marketplace Database Providers 数据库服务选择 Neon，点击 Continue 进行下一步。
此时会让你创建一个 Neon 账号，此时选择 Accept and Create 接受并创建。后续选择数据库的套餐配置，包括地区和额度。这里可以什么都不操作直接选择 Continue 下一步。
此时会让你定义数据库名称，这里也可以不用修改直接 Continue 进行下一步。
这时候 Storage 下就有你创建的数据库服务了，点击进去选择 Open in Neon 跳转到 Neon。在 Neon 界面左侧选择 SQL Editor，将 waline.pgsql 中的 SQL 语句粘贴进编辑器中，点击 Run 执行创建表操作。

稍等片刻之后会告知你创建成功。此时回到 Vercel，点击顶部的 Deployments 点击顶部最新的一次部署右侧的 Redeploy 按钮进行重新部署。该步骤是为了让刚才配置的数据库服务生效。
此时会跳转到 Overview 界面开始部署，等待片刻后 STATUS 会变成 Ready。此时请点击 Visit ，即可跳转到部署好的网站地址，此地址即为你的服务端地址。

以上就是官方文档相关部分，接下来是补充：

Neon数据库配置信息

在上图部分复制数据库信息：

变量	值
`PG_HOST`	取`PGHOST_UNPOOLED`的值
`PG_DB`	取`PGDATABASE`的值
`PG_USER`	取`POSTGRES_USER`的值
`PG_PASSWORD`	取`PGPASSWORD`的值
`PG_SSL`	填`true`

Vercel环境变量设置

提示：添加环境变量后，需要进入Vercel项目的Deployments页面，找到最新部署点击 “Redeploy”，变量才会生效。

新文章通知记录

Sat, 11 Apr 2026 17:07:00 +0800

文章介绍了博客新文章通知功能的实现原理，包括 RSS 数据获取、IndexedDB 存储、文章变更检测、差异对比算法等核心逻辑。通过对比新旧文章数据，自动检测新增和更新的文章，并以动画弹窗形式通知用户。

新文章通知记录

有时候，发现新内容的那一刻，正是阅读最好的时机。

功能概述

新文章通知功能是一个自动检测博客文章更新的客户端组件，能够在用户访问网站时，自动对比当前 RSS 数据与上次访问时的数据，发现新增或更新的文章，并以优雅的弹窗形式通知用户。

核心特性

自动检测：基于 RSS 数据自动检测文章变更
差异对比：使用 diff 算法精确识别内容变化
本地存储：使用 IndexedDB 持久化存储文章数据
智能防误报：过滤全量更新等特殊情况

实现逻辑

1. 数据获取与存储

RSS 获取：通过 fetch('/rss.xml') 获取当前博客文章列表

数据解析：解析 XML，提取标题、链接、GUID、发布时间、描述和正文内容

IndexedDB 存储：将文章数据存储在浏览器的 IndexedDB 中，支持离线访问

2. 变更检测机制

系统通过对比新旧数据检测以下变更：

变更类型	检测条件	处理方式
新文章	GUID 在旧数据中不存在	标记为 `isUpdated: false`
标题变更	`post.title !== stored.title`	使用 `diffLines` 对比差异
描述变更	`post.description !== stored.description`	使用 `diffLines` 对比差异
内容变更	`post.content !== stored.content`	使用 `diffLines` 对比差异

3. 智能防误报策略

为避免以下情况产生误报：

首次访问：所有文章都是"新"的，不应提示
全量更新：RSS 源重建导致所有文章 GUID 变化
全部更新：所有文章同时被标记为更新

系统采用以下策略：

// 检测是否全为新文章或全为更新
const isAllNew = detectedChanges.length === currentPosts.length && 
                 detectedChanges.every((p) => !p.isUpdated)
const isAllUpdated = detectedChanges.length === currentPosts.length && 
                     detectedChanges.every((p) => p.isUpdated)

if (isAllNew || isAllUpdated) {
  // 重置存储，不显示通知
  await clearStore(db, 'posts')
  await savePosts(db, 'posts', currentPosts)
  showNotification([], Date.now(), false, initTime)
  return
}

核心代码结构

组件结构

NewPostNotification.astro

组件采用三层架构：

UI 层：圆形铃铛图标 → 展开面板 → 文章列表
动画层：CSS 过渡动画实现平滑展开/收起
逻辑层：TypeScript 处理数据对比和状态管理

数据库操作

notification-db.ts

数据库操作封装：

函数	功能
`openDB()`	打开 IndexedDB 连接
`getStoredPosts()`	获取存储的文章列表
`savePosts()`	保存文章到数据库
`clearStore()`	清空数据存储
`fetchRSS()`	获取并解析 RSS 数据
`generateId()`	生成带作用域的唯一 ID

// 数据库配置
const DB_NAME = 'blog-rss-store-v2'
const STORE_OLD = 'posts'
const STORE_NEW = 'posts_new'

差异对比算法

使用 diff 库进行行级对比：

import * as Diff from 'diff'

function computeDiff(oldText: string, newText: string) {
  // 标准化处理：统一换行符、去除行尾空格
  const normalizeRaw = (text: string) => {
    return text
      .replace(/\r\n/g, '\n')
      .replace(/\r/g, '\n')
      .split('\n')
      .map(line => line.replace(/[ \t]+$/g, ''))
      .join('\n')
      .trim()
  }
  
  const diffs = Diff.diffLines(normalizeRaw(oldText), normalizeRaw(newText))
  return diffs.some(part => part.added || part.removed) ? diffs : null
}

食用方法

使用说明：当检测到新文章或文章更新时，页面右下角会出现铃铛图标，点击即可查看变更列表。

功能入口

新文章通知组件 - 位于页面右下角的铃铛图标

交互说明

首次访问：自动记录当前文章状态，不显示通知
发现更新：铃铛图标出现红点并脉动动画，1.5秒后自动展开
查看变更：点击文章标题可跳转到对应文章
标记已读：点击"清空通知"按钮重置状态
手动关闭：点击"隐藏"按钮收起面板

注意事项

1. 数据存储限制

IndexedDB 容量：浏览器通常限制在 50MB 左右
存储结构：文章正文可能较大，注意监控存储空间
清理策略：目前无自动清理，长期可能积累大量数据

2. RSS 源依赖

实时性：依赖 RSS 生成时机，可能有延迟
完整性：确保 RSS 包含完整文章内容（content:encoded）
跨域问题：RSS 需与网站同域或通过代理访问

3. 性能优化

防抖处理：对比操作在客户端执行，大量文章时可能卡顿
异步加载：RSS 获取为异步，不影响页面加载
内存管理：文章数据缓存在内存中，注意内存占用

4. 兼容性

浏览器支持：需要支持 IndexedDB 的现代浏览器
隐私模式：部分浏览器隐私模式下 IndexedDB 不可用
SSR 适配：组件使用 client:only 指令，避免服务端渲染问题

技术栈

技术	用途
Astro	组件框架
TypeScript	类型安全
IndexedDB	本地数据持久化
diff	文本差异对比
DOMParser	RSS XML 解析
Tailwind CSS	样式设计

总结

新文章通知功能通过 RSS 数据对比和 IndexedDB 存储，实现了客户端的文章变更检测。核心优势在于：

无需后端：纯前端实现，不依赖服务器推送
精准检测：使用 diff 算法精确识别内容变化
智能防误报：过滤首次访问和全量更新等特殊情况
优雅交互：平滑动画和清晰的信息展示

未来优化方向

支持 Web Push 推送通知
添加文章更新详情页（diff 可视化）
实现自动清理过期数据
支持多 RSS 源聚合