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
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