feat(toc): implement post table of contents and refactor line number component

2026-01-30 15:48:29 +08:00
@@ -1,10 +1,12 @@
 /// <reference types="vite/client" />
 import type { Alpine } from "alpinejs";
+import type { TocManager } from "./src/alpine/toc";

 export {};

 declare global {
  interface Window {
    Alpine: Alpine;
+    tocManager?: TocManager;
  }
 }
@@ -147,7 +147,7 @@ const appendElementLines = (fragment: DocumentFragment, metrics: ElementMetrics,

 // ============ 主组件 ============

-export const lineNumbers = (): LineNumbersState => ({
+export const postLineNum = (): LineNumbersState => ({
  totalLines: 0,
  resizeObserver: null,

@@ -206,8 +206,21 @@ export const lineNumbers = (): LineNumbersState => ({
    let currentLine = 1;
    let lastBottom = 0;

+    // 派发清空目录事件
+    document.dispatchEvent(new CustomEvent('post-toc:clear'));
+
    for (const element of elements) {
      const metrics = getElementMetrics(element, containerRect, defaultLineHeight);
+      const tagName = element.tagName.toLowerCase();
+
+      // 如果是标题元素，派发添加目录事件
+      if (metrics.isHeading) {
+        const level = parseInt(tagName.charAt(1), 10);
+        const title = element.textContent?.trim() || '';
+        document.dispatchEvent(new CustomEvent('post-toc:add', {
+          detail: { level, title, element, tagName }
+        }));
+      }

      if (lastBottom > 0 && metrics.top > lastBottom) {
        currentLine = appendGapLines({
@@ -223,6 +236,9 @@ export const lineNumbers = (): LineNumbersState => ({
      lastBottom = metrics.top + metrics.height;
    }

+    // 派发初始化滚动高亮事件
+    document.dispatchEvent(new CustomEvent('post-toc:init-highlight'));
+
    gutter.innerHTML = '';
    gutter.appendChild(fragment);
    gutter.style.height = `${container.scrollHeight}px`;
@@ -0,0 +1,110 @@
+// ============ 类型定义 ============
+
+export interface PostTocItem {
+  id: string;
+  level: number;
+  title: string;
+  element: HTMLElement;
+  tagName: string;
+}
+
+// ============ 工具函数 ============
+
+const generateId = (counter: number): string =>
+  `post-toc-${counter}-${Date.now()}`;
+
+const ensureElementId = (element: HTMLElement, fallbackId: string): string => {
+  if (!element.id) element.id = fallbackId;
+  return element.id;
+};
+
+const findTopVisibleEntry = (entries: IntersectionObserverEntry[]): IntersectionObserverEntry | null => {
+  const visible = entries.filter(e => e.isIntersecting);
+  if (visible.length === 0) return null;
+
+  return visible.reduce((prev, curr) =>
+    curr.boundingClientRect.top < prev.boundingClientRect.top ? curr : prev
+  );
+};
+
+const createScrollObserver = (onActiveChange: (id: string) => void): IntersectionObserver =>
+  new IntersectionObserver(
+    (entries) => {
+      const topEntry = findTopVisibleEntry(entries);
+      if (topEntry) onActiveChange(topEntry.target.id);
+    },
+    { rootMargin: '-80px 0px -70% 0px', threshold: [0, 0.5, 1] }
+  );
+
+// ============ 事件常量 ============
+
+export const TOC_EVENTS = {
+  CLEAR: 'post-toc:clear',
+  ADD: 'post-toc:add',
+  HIGHLIGHT: 'post-toc:init-highlight'
+} as const;
+
+// ============ Alpine 组件 ============
+
+export const postToc = () => ({
+  items: [] as PostTocItem[],
+  activeId: '',
+  observer: null as IntersectionObserver | null,
+
+  // 私有属性
+  _isInitialized: false,
+  _counter: 0,
+  _minLevel: 6,
+
+  init() {
+    if (this._isInitialized) return;
+
+    document.addEventListener(TOC_EVENTS.CLEAR, () => this.clear());
+
+    document.addEventListener(TOC_EVENTS.ADD, (e) => {
+      const { level, title, element, tagName } = (e as CustomEvent).detail;
+
+      this.addItem(level, title, element, tagName);
+    });
+
+    document.addEventListener(TOC_EVENTS.HIGHLIGHT, () => this.initScrollHighlight());
+
+    this._isInitialized = true;
+  },
+
+  addItem(level: number, title: string, element: HTMLElement, tagName: string) {
+    this._counter++;
+
+    const id = ensureElementId(element, generateId(this._counter));
+
+    if (level < this._minLevel) this._minLevel = level;
+
+    this.items = [...this.items, { id, level, title, element, tagName }];
+  },
+
+  clear() {
+    this.items = [];
+    this.activeId = '';
+    this._counter = 0;
+    this._minLevel = 6;
+    this.observer?.disconnect();
+  },
+
+  initScrollHighlight() {
+    this.observer?.disconnect();
+    this.observer = createScrollObserver((id) => { this.activeId = id; });
+    this.items.forEach(item => this.observer?.observe(item.element));
+  },
+
+  scrollTo(id: string) {
+    const element = document.getElementById(id);
+    if (!element) return;
+
+    element.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    this.activeId = id;
+  },
+
+  getIndent(level: number): string {
+    return `${(level - this._minLevel) * 16}px`;
+  }
+});
@@ -4,9 +4,10 @@ import "./styles/font-pixel.scss";

 import Alpine from 'alpinejs'
 import {upvote} from './alpine/upvote'
-import {themeMode} from './alpine/themeMode'
+import {themeMode} from './alpine/theme-mode'
 import {menu} from './alpine/menu'
-import {lineNumbers} from './alpine/lineNumbers'
+import {postLineNum} from './alpine/post-line-num'
+import {postToc} from './alpine/post-toc'
 import {typewriterEffect} from './utils'

 window.Alpine = Alpine
@@ -14,7 +15,8 @@ window.Alpine = Alpine
 Alpine.data('upvote', upvote)
 Alpine.data('themeMode', themeMode)
 Alpine.data('menu', menu)
-Alpine.data('lineNumbers', lineNumbers)
+Alpine.data('postLineNum', postLineNum)
+Alpine.data('postToc', postToc)

 Alpine.start()

@@ -0,0 +1,54 @@
+@import "variables";
+
+.post-line-gutter {
+  position: absolute;
+  left: -80px;
+  top: 0;
+  width: 60px;
+  user-select: none;
+  opacity: 0.5;
+  border-right: 1px solid color-mix(in srgb, var(--foreground) 15%, transparent);
+
+  @media (max-width: $tablet-max-width) {
+    display: none;
+  }
+
+  .line-number {
+    position: absolute;
+    right: 8px;
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    padding-right: 10px;
+    font-size: 0.85rem;
+    color: var(--foreground);
+    transition: opacity 0.15s ease;
+    opacity: 0.8;
+
+    &:hover {
+      opacity: 1;
+    }
+  }
+
+  .line-number--gap {
+    opacity: 0.5;
+  }
+
+  .line-number--breakpoint {
+    cursor: pointer;
+
+    .line-breakpoint {
+      position: absolute;
+      right: -3px;
+      color: var(--brightRed);
+      font-size: 0.875rem;
+      font-family: Hack, Monaco, Consolas, monospace;
+      transition: transform 0.15s ease, filter 0.15s ease;
+    }
+
+    &:hover .line-breakpoint {
+      transform: scale(1.2);
+      filter: brightness(1.2);
+    }
+  }
+}
@@ -0,0 +1,188 @@
+@import "variables";
+
+.post-toc {
+  position: absolute;
+  left: -280px;
+  top: 85px;
+  width: 200px;
+  max-height: calc(100vh - 200px);
+  overflow-y: auto;
+  overflow-x: hidden;
+  z-index: 100;
+  font-size: 0.8rem;
+  line-height: 1.6;
+  color: var(--foreground);
+  opacity: 0.7;
+  transition: opacity 0.2s ease;
+
+  // 隐藏滚动条但保持可滚动
+  scrollbar-width: thin;
+  scrollbar-color: var(--foreground) transparent;
+
+  &:hover {
+    opacity: 1;
+  }
+
+  &::-webkit-scrollbar {
+    width: 4px;
+  }
+
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    background-color: color-mix(in srgb, var(--foreground) 30%, transparent);
+    border-radius: 2px;
+  }
+
+  // 移动端和平板隐藏
+  @media (max-width: 1200px) {
+    display: none;
+  }
+}
+
+.toc-tree {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  padding-left: 10px;
+  position: relative;
+
+  // 左侧边框线（不连接顶部）
+  &::before {
+    content: '';
+    position: absolute;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    width: 1px;
+    background-color: color-mix(in srgb, var(--foreground) 20%, transparent);
+  }
+}
+
+.toc-item {
+  position: relative;
+  display: flex;
+  align-items: flex-start;
+  padding: 2px 0;
+  cursor: pointer;
+  transition: background-color 0.15s ease;
+  border-radius: 3px;
+
+  &:hover {
+    background-color: color-mix(in srgb, var(--foreground) 8%, transparent);
+  }
+
+  // 折叠箭头
+  &__toggle {
+    flex-shrink: 0;
+    width: 16px;
+    height: 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--foreground);
+    opacity: 0.5;
+    font-size: 0.6rem;
+    transition: transform 0.2s ease;
+    user-select: none;
+
+    &--expanded {
+      transform: rotate(0deg);
+    }
+
+    &--collapsed {
+      transform: rotate(-90deg);
+    }
+
+    &--empty {
+      visibility: hidden;
+    }
+  }
+
+  // 标签图标 <>
+  &__icon {
+    flex-shrink: 0;
+    color: var(--yellow);
+    margin-right: 4px;
+    opacity: 0.7;
+  }
+
+  // 标签名 (h1, h2, div, etc.)
+  &__tag {
+    flex-shrink: 0;
+    color: var(--blue);
+    margin-right: 6px;
+  }
+
+  // 标题文字
+  &__title {
+    color: var(--foreground);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    opacity: 0.8;
+    transition: color 0.15s ease, opacity 0.15s ease;
+  }
+
+  // 活跃状态
+  &--active {
+    background-color: color-mix(in srgb, var(--brightBlue) 15%, transparent);
+
+    .toc-item__title {
+      color: var(--brightBlue);
+      opacity: 1;
+    }
+
+    .toc-item__tag {
+      color: var(--brightBlue);
+    }
+
+    // 左侧激活指示线
+    &::before {
+      content: '' !important;
+      position: absolute;
+      left: -10px !important;
+      top: 4px;
+      bottom: 4px;
+      width: 2px;
+      background-color: var(--brightBlue);
+      border-radius: 1px;
+    }
+  }
+}
+
+// 子级列表
+.toc-children {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  padding-left: 16px;
+
+  &--collapsed {
+    display: none;
+  }
+}
+
+// 目录头部
+.toc-header {
+  display: flex;
+  align-items: center;
+  padding: 4px 0 8px 0;
+  margin-bottom: 4px;
+  border-bottom: 1px solid color-mix(in srgb, var(--foreground) 15%, transparent);
+  color: var(--foreground);
+  opacity: 0.6;
+  font-size: 0.75rem;
+
+  &__icon {
+    margin-right: 6px;
+    color: var(--yellow);
+  }
+
+  &__title {
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+  }
+}
@@ -24,6 +24,7 @@
 }

 .post {
+  position: relative;
  width: 100%;
  text-align: left;
  margin: 20px auto;
@@ -133,59 +134,6 @@
    margin-top: 30px;
  }

-  &-line-gutter {
-    position: absolute;
-    left: -80px;
-    top: 0;
-    width: 60px;
-    user-select: none;
-    opacity: 0.5;
-    border-right: 1px solid color-mix(in srgb, var(--foreground) 15%, transparent);
-
-    @media (max-width: $tablet-max-width) {
-      display: none;
-    }
-
-    .line-number {
-      position: absolute;
-      right: 8px;
-      display: flex;
-      align-items: center;
-      justify-content: flex-end;
-      padding-right: 10px;
-      font-size: 0.85rem;
-      color: var(--foreground);
-      transition: opacity 0.15s ease;
-      opacity: 0.8;
-
-      &:hover {
-        opacity: 1;
-      }
-    }
-
-    .line-number--gap {
-      opacity: 0.5;
-    }
-
-    .line-number--breakpoint {
-      cursor: pointer;
-
-      .line-breakpoint {
-        position: absolute;
-        right: -3px;
-        color: var(--brightRed);
-        font-size: 0.875rem;
-        font-family: Hack, Monaco, Consolas, monospace;
-        transition: transform 0.15s ease, filter 0.15s ease;
-      }
-
-      &:hover .line-breakpoint {
-        transform: scale(1.2);
-        filter: brightness(1.2);
-      }
-    }
-  }
-
  &-content {
    font-family: Hack, Monaco, Consolas, 'Ubuntu Mono', PingHei, 'PingFang SC', 'Microsoft YaHei', monospace;
    line-height: 1.54;
@@ -7,6 +7,8 @@
@import 'logo';
@import 'main';
@import 'post';
+@import 'post-line-num';
+@import 'post-toc';
@import 'pagination';
@import 'footer';
@import 'typed-text';
@@ -4,7 +4,27 @@
  th:replace="~{modules/layout :: html(title = |${post.spec.title} - ${site.title}|, header = null, content = ~{::content}, footer = null)}"
 >
  <th:block th:fragment="content">
-    <div class="post" x-data="lineNumbers" x-init="init()">
+    <div class="post" x-data="postLineNum" x-init="init()">
+      <!-- 目录组件 -->
+      <div class="post-toc" x-data="postToc" x-init="init()">
+        <div class="toc-header">
+          <span class="toc-header__icon">&lt;&gt;</span>
+          <span class="toc-header__title">Outline</span>
+        </div>
+        <ul class="toc-tree">
+          <template x-for="(item, index) in items" :key="index">
+            <li class="toc-item"
+                :class="{'toc-item--active': activeId === item.id}"
+                :style="`padding-left: ${getIndent(item.level)}`"
+                @click="scrollTo(item.id)">
+              <span class="toc-item__toggle toc-item__toggle--empty">▼</span>
+              <span class="toc-item__icon">&lt;&gt;</span>
+              <span class="toc-item__tag" x-text="item.tagName"></span>
+              <span class="toc-item__title" x-text="item.title"></span>
+            </li>
+          </template>
+        </ul>
+      </div>
      <h1 class="post-title" th:text="'< ' + ${post.spec.title} + ' >'">Post Title</h1>
      <div class="post-meta">
        <span class="post-date" th:text="${#dates.format(post.spec.publishTime,'yyyy-MM-dd')}"> publishTime </span>
@@ -26,6 +46,7 @@
        >
      </span>
      <div class="post-body">
+        <!-- 行数组件 -->
        <div class="post-line-gutter"></div>
        <div class="post-content">
          <div th:utext="${post.content.content}">Post Content</div>
@@ -13,5 +13,5 @@ spec:
  repo: https://git.dev.cm/theme-terminal
  settingName: "theme-terminal-setting"
  configMapName: "theme-terminal-configMap"
-  version: 1.1.10c
+  version: 1.2.1
  require: ">=2.22.0"
@@ -16,5 +16,5 @@
    "noImplicitReturns": true,
    "skipLibCheck": true
  },
-  "include": ["src", "./env.d.ts"]
+  "include": ["types", "src", "./env.d.ts"]
 }