Julian Blog

Article Outline 插件设计与代码实现

作者：

Julian

在

一、插件框架设计

1. 设计理念

Article Outline插件的设计理念是为WordPress文章提供自动生成的大纲，帮助读者快速浏览和导航长文章。

2. 需求分析

Article Outline插件的需求分析：

  • 自动生成文章大纲
  • 在文章页面显示大纲
  • 支持平滑滚动到对应章节
  • 响应式设计

3. 模块架构

插件采用面向对象的设计方法，主要包含以下模块：

  • 主模块：插件的初始化和入口文件，负责启动整个插件
  • 功能模块：该模块承载了插件的主要业务逻辑，专门负责文章大纲的生成与处理工作
  • 样式模块：此模块专注于前端界面的视觉设计，定义了插件在页面上的展示样式
  • 交互模块：该模块处理前端的用户交互逻辑，主要实现平滑滚动及其他动态交互效果
  • 语言模块：此模块提供国际化支持，包含翻译模板文件，以便插件适配多种语言环境

4. 技术架构

  • 后端：基于WordPress Hooks API和PHP面向对象编程
  • 前端：纯JavaScript实现，无jQuery依赖
  • 样式：CSS3实现响应式设计和自定义滚动条
  • 数据处理：正则表达式解析文章内容，生成标题列表

二、核心功能实现

1. 大纲生成机制

1.1 标题检测

使用正则表达式匹配文章中的所有标题标签（H1-H6）：

preg_match_all( '/<h([1-6])([^>]*)>(.*?)<\/h\1>/si', $content, $matches, PREG_SET_ORDER );

1.2 标题ID生成

为每个标题生成唯一的ID，用于锚点链接：

$base_id = sanitize_title( $heading_text );
$heading_id = $base_id;
$counter = 1;

// Ensure unique ID
while ( in_array( $heading_id, $used_ids ) ) {
    $heading_id = $base_id . '-' . $counter;
    $counter++;
}
$used_ids[] = $heading_id;

1.3 大纲HTML生成

根据标题层级生成嵌套的HTML列表：

// Generate nested list based on heading levels
if ( $level > $previous_level ) {
    // Increase indentation level
    for ( $i = $previous_level; $i < $level; $i++ ) {
        $outline .= '<ul class="article-outline-sublist">';
    }
} elseif ( $level < $previous_level ) {
    // Decrease indentation level
    for ( $i = $level; $i < $previous_level; $i++ ) {
        $outline .= '</li></ul>';
    }
    $outline .= '</li>';
} elseif ( $current_level > 1 ) {
    // Same level, close previous item
    $outline .= '</li>';
}

$outline .= '<li class="article-outline-item">';
$outline .= '<a href="#' . $heading_id . '" class="article-outline-link">' . $heading_text . '</a>';

2. 内容处理流程

2.1 内容过滤

通过WordPress的the_content过滤器，在文章内容前添加大纲：

add_filter( 'the_content', array( $this, 'add_outline_to_content' ) );

2.2 短代码支持

添加短代码支持，允许用户手动放置大纲：

add_shortcode( 'article_outline', array( $this, 'outline_shortcode' ) );

2.3 标题ID注入

将生成的标题ID注入到原始文章内容中：

// Create new heading tag with ID
$new_heading = '<h' . $level . ' id="' . $heading_id . '"' . $match[2] . '>' . $heading_content . '</h' . $level . '>';

// Update content with new heading tag
$content = str_replace( $match[0], $new_heading, $content );

3. 前端交互实现

3.1 平滑滚动

使用原生JavaScript实现平滑滚动：

// Smooth scroll to target
if ('scrollBehavior' in document.documentElement.style) {
    // Modern browsers support smooth scrolling natively
    window.scrollTo({
        top: offsetTop,
        behavior: 'smooth'
    });
} else {
    // Fallback for older browsers
    // Custom smooth scroll animation using requestAnimationFrame
}

3.2 大纲定位

大纲采用sticky定位，在桌面设备上右浮动显示：

@media (min-width: 1024px) {
    .article-outline {
        position: sticky;
        top: 20px;
        width: 280px;
        max-width: 280px;
        float: right;
        margin-left: 30px;
    }
}

3.3 自定义滚动条

为大纲添加自定义滚动条，提升用户体验：

/* Custom scrollbar styling */
.article-outline::-webkit-scrollbar {
    width: 6px;
}

.article-outline::-webkit-scrollbar-track {
    background: #f1f1f1;
    border-radius: 3px;
}

.article-outline::-webkit-scrollbar-thumb {
    background: #c1c1c1;
    border-radius: 3px;
}

三、功能模块详细说明

1. 大纲显示模块

1.1 响应式设计

  • 桌面设备：右浮动显示，固定宽度280px
  • 平板设备：自适应宽度，居中显示
  • 移动设备：默认隐藏，优化阅读体验

1.2 视觉设计

  • 浅色背景，与大多数主题兼容
  • 清晰的标题层级，使用缩进区分
  • 悬停效果：绿色高亮+字体加粗
  • 自定义滚动条，提升美观度

2. 交互模块

2.1 点击交互

  • 点击大纲链接，平滑滚动到对应章节

2.2 悬停效果

  • 鼠标悬停时，标题变为绿色并加粗
  • 平滑过渡效果，提升交互体验

更多文章