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