API文档

API 文档

本文档主要面向开发者,介绍了项目中的核心类型定义和工具函数。虽然这是一个浏览器扩展,没有公开的 API 供外部调用,但这些内部 API 对于理解和贡献代码非常有帮助。

📦 类型定义 (Types)

Heading

表示从页面中提取的一个标题元素。

interface Heading {
  /**
   * 标题的唯一标识符,通常来自 HTML id 属性
   */
  id: string;

  /**
   * 标题的纯文本内容
   */
  text: string;

  /**
   * 标题层级 (1-6)
   */
  level: number;

  /**
   * 对应的 DOM 元素引用
   */
  element: HTMLElement;
}

TOCProps

TOC 组件的属性。

interface TOCProps {
  /**
   * 从页面提取的标题列表
   */
  headings: Heading[];

  /**
   * 当前高亮的标题 ID
   */
  activeId: string;

  /**
   * 点击标题时的回调函数
   */
  onHeadingClick: (id: string) => void;
}

🛠️ 工具函数 (Utils)

位于 src/utils.ts。

getHeadings()

扫描页面并返回标题列表。

/**
 * 扫描当前页面,提取所有符合条件的标题
 * @param container 搜索范围的容器元素,默认为 document
 * @returns Heading[] 标题对象数组
 */
function getHeadings(container?: HTMLElement): Heading[];

scrollToHeading()

平滑滚动到指定标题。

/**
 * 滚动页面以显示指定 ID 的标题
 * @param id 目标标题的 ID
 * @param offset 顶部偏移量(用于避开固定导航栏)
 */
function scrollToHeading(id: string, offset?: number): void;

generateId()

为没有 ID 的标题生成唯一 ID。

/**
 * 根据标题文本生成 URL 安全的 ID
 * @param text 标题文本
 * @returns string 生成的 ID
 */
function generateId(text: string): string;

🧩 React Hooks

useScrollSpy

用于监听滚动并确定当前活动的标题。

/**
 * @param headings 标题列表
 * @param options 配置选项
 * @returns string 当前活动标题的 ID
 */
function useScrollSpy(headings: Heading[], options?: ScrollSpyOptions): string;

useMutationObserver

封装 MutationObserver 以监听 DOM 变化。

/**
 * @param ref 要观察的 DOM 元素引用
 * @param callback DOM 变化时的回调
 * @param options MutationObserverInit 选项
 */
function useMutationObserver(
  ref: React.RefObject<HTMLElement>,
  callback: MutationCallback,
  options?: MutationObserverInit
): void;

constants.ts

项目中使用的常量。

export const HEADER_OFFSET = 60; // 顶部导航栏高度
export const THROTTLE_DELAY = 100; // 滚动事件节流延迟(ms)
export const TOC_CONTAINER_ID = 'github-issue-toc-container'; // TOC 容器 ID

---

← 返回核心实现 | 贡献指南 →