文章自動生成目錄及側邊欄目錄滾動特效的插件toc-helper

toc-helper

一、 簡介

TocHelper 是一款給文章自動生成目錄及側邊欄目錄滾動特效的插件
特點

• jQuery Free
• 方便、靈活、高度定製化
• 自動退級
• Hash 定位
• 目錄跟隨 Body / div 滾動

二、 使用

2.1 瀏覽器

2.1.1 引入css和js

<link href="css/toc-helper.min.css" rel="stylesheet" />
<script src="js/toc-helper.min.js"></script>

2.1.2 文章內容添加 data 屬性，值指向目錄元素： data-toc="#toc"

<div data-toc="#toc"> </div>

注意： #toc 選擇器對應的目錄元素必須存在

<div id="toc"> </div>

2.1.3 目錄已經存在, 調用 reload() 方法

new TocHelper().reload();

2.1.4 目錄若不存在, 調用 reset() 方法，自動創建目錄

new TocHelper().reset();

2.2 使用 Webpack, Browserify, Gulp, Rollup 等構建工具

2.2.1 使用 npm 安裝 TocHelper
npm install toc-helper --save OR yarn add toc-helper
2.2.2 使用 require 引入

require('toc-helper/css/toc-helper.min.css')
const TocHelper = require('toc-helper')

2.2.3 使用 import 引入

import 'toc-helper/css/toc-helper.min.css'
import TocHelper from 'toc-helper'

2.2.4 簡單應用

new TocHelper().reload()

三、API

TocHelper([selector,options])

構造器方法, 只能通過 new 創建實例

selector
類型：string | HTMLElement | Object
默認值： 無

selector 若爲字符串，則必須是選擇器，切可以通過該選擇器獲取相應的元素，否則無效
selector 若爲 Object ，則 options = selector 第二個參數無效

options
類型：Object
默認值： {}

合併初始的 options 參數，並重新 load; 比如 class 樣式發生改變; megre 之後需要調用 reload 方法

reload()

無參

實例化以及重新 megre 之後需要調用該方法

實例化後若目錄已經存在則調用該方法，若不存在則調用 reset 方法，生成目錄會自動調用該方法

reset()

無參

目錄不存在或需要重新生成目錄使用該方法

四、配置

options

1. dom

文章內容 Dom 元素， 選擇器或 HTMLElement 類型的 Dom 元素

類型：string | HTMLElement
默認值：*[data-toc]

2. classNames

class 選擇器名稱

2.1 toc

目錄元素的 class 選擇器名稱

類型：string
默認值：toc

2.2 fxied

目錄元素 position=fixed 的 class 選擇器名稱

類型：string
默認值：toc-fixed

2.3 brand

目錄 字的 class 選擇器名稱

類型：string
默認值：toc-brand

2.4 navbar

目錄菜單 class 選擇器名稱

類型：string
默認值：toc-navbar

2.5 hightlight

激活高亮/鼠標懸停高亮的 class 選擇器名稱

類型：string
默認值：toc-hightlight

2.6 nav

菜單父級節點class選擇器名稱

類型：string
默認值：toc-nav

2.7 link

菜單項class選擇器名稱

類型：string
默認值：toc-link

2.8 active

菜單項激活後的class選擇器名稱

類型：string
默認值：active

2.9 marginLeft1

二級標題偏移的class選擇器名稱

類型：string
默認值：ml-1

2.10 marginLeft1

二級標題偏移的class選擇器名稱

類型：string
默認值：ml-1

2.11 marginLeft2

三級標題偏移的class選擇器名稱

類型：string
默認值：ml-2

2.12 marginLeft3

四級標題偏移的class選擇器名稱

類型：string
默認值：ml-3

2.13 marginLeft4

五級標題偏移的class選擇器名稱

類型：string
默認值：ml-4

2.14 marginLeft5

六級標題偏移的class選擇器名稱

類型：string
默認值：ml-5

2.15 marginLeft6

暫無使用

3. hightlight

是否高亮顯示

類型：Boolean
默認值：true

4. brand

目錄文本

類型：string
默認值：目錄

5. shadow

目錄陰影

類型：string | false
默認值：shadow

若爲string ，則提供陰影的樣式class選擇器名稱,false表示禁用陰影

6. idPrefix

生成ID選擇器的前綴

類型：string
默認值：toc-heading-

後綴由數字組成

7. offsetBody

內容父級定位元素，該元素必須存在position屬性，切position的值不等於static, 否則此值等於body

類型：string | HTMLElement
默認值：document.body

爲string類型時，必須是選擇器；無論是string類型，還是HTMLElement類型，都必須有position屬性，切position的值不等於static，否則此值等於body

8. topFixed

不使用或設置目錄fixed定位

類型：false | Object
默認值：如下

false表示不使用fixed定位；Object如下：

8.1 top

目錄距離文檔頂部的偏移量

類型： Number
默認值：24

8.2 left

目錄距離文檔左側的偏移量

類型： Number
默認值：無

9 maxDepth

目錄最大層級

類型： Number
默認值：6

層級最大爲6 ，最小爲1，其他值無效

五、示例options全部配置信息

{
   dom: '*[data-toc]', // 文章內容元素 選擇器 或 HTMLElement
   classNames: {       // class選擇器
       toc: 'toc',
       fxied: 'toc-fixed',
       brand: 'toc-brand',
       navbar: 'toc-navbar',
       hightlight: 'toc-hightlight',
       nav: 'toc-nav',
       link: 'toc-link',
       active: 'active',
       marginLeft1: 'ml-1',
       marginLeft2: 'ml-2',
       marginLeft3: 'ml-3',
       marginLeft4: 'ml-4',
       marginLeft5: 'ml-5',
       marginLeft6: 'ml-6'
   },
   hightlight: true,
   brand: '目錄',
   shadow: 'shadow',
   idPrefix: 'toc-heading-',
   offsetBody: document.body,
   topFixed: {
       top: 24,
       left: 0
   },
   maxDepth: 6
}

注意：

使用錨點 / Hash定位時，若存在頭部使用了fixed或absolute定位，會出現定位沒達到預期效果; 可將所有的標題padding-top等於頭部的高, margin-top等於頭部高的相反值，這樣可以解決定位不準切不會影響佈局；

示例代碼如下:

*[data-toc] h1,
*[data-toc] h2,
*[data-toc] h3,
*[data-toc] h4,
*[data-toc] h5,
*[data-toc] h6 {
    margin-top: -83px;
    padding-top: 83px;
}

即將支持的功能

• 目錄自動添加滾動條
• 實現雙向滾動
• 自動摺疊/展開
• 支持橫向目錄
• 同步高亮文章中的標題

gitee地址：toc-helper
github地址：toc-helper
npm地址： toc-helper