toc-helper

toc-helper 是一款给文章自动生成目录的插件

v1 入口
v2 在线预览 Demo

一、 v2 特性

• 用法精简，减少了大量的配置，去除不必要的API，仅需要引入一个js文件
• 性能优化，联动滚动更加流畅，自动停靠顶部更加精准
• 目录支持自动展开、折叠
• 自动定位，初始目录高亮位置自动识别
• 支持显示、隐藏、自适应宽度变化
• 支持非标题标签, 但需要提供 data-level 属性
• 支持局部滚动（非body, 内容div滚动）
• 支持 React、Vue、Svelte

二、 使用

浏览器

1. 引入JS

<script src="lib/umd/index.js"></script>

esmodule 引入 lib/es/index.js

2. 使用

new TocHelper(el [, options])

npm方式

1. 安装

npm install toc-helper --save 
# 或者
yarn add toc-helper

2. 使用

2.1 require

const TocHelper = require('toc-helper')
new TocHelper(el [, options])

2.2 import

import TocHelper from 'toc-helper'
new TocHelper(el [, options])

2.3 React 示例

2.3.1 普通模式

import TocHelper from 'toc-helper'
class App extends React.PureComponent{
  constructor(props){
    super(props)
    this.ref = null
  }
  componentDidMount(){
    new TocHelper(this.ref [, options])
  }
  render(){
    return <div ref={ref => this.ref = ref} />
  }
} 

2.3.2 Hook 模式

import TocHelper from 'toc-helper'
export default App(){
 const ref = useRef()
 useEffect(()=>{
   new TocHelper(ref [, options])
 })
 return <div ref={ref} />
}

2.4 vue 示例 v3

<script>
  import TocHelper from 'toc-helper'
  setup(props, { emit }) {
    const toc = ref(null);
    let helper = null;
    onMounted(function () {
      helper = new TocHelper(toc [, options]);
    });

    return { toc };
  },
</script>
<template>
  <div ref="toc"></div>
</template>

2.5 svelte 示例

<script>
  import TocHelper from 'toc-helper'
  let toc = null
  let helper = null
  onMount(function(){
    helper = new TocHelper(toc [, options])
  })
</script>
<div bind:this={toc}/>

三、API

TocHelper(selector [, options])

构造器方法, 只能通过 new 创建实例

selector
类型：string | HTMLElement
默认值：无
必须：是

selector 若为字符串，则必须是选择器，切可以通过ducument.querySelector获取相应的元素，否则将报错

options
类型：object | undefined
默认值：无
必须：可选

reset

无参

实例方法，调用后将重新解析 heading, 若数据是异步获取，该方法会有用

isEmpty

无参

实例方法，判断是否有 heading

syncScroll

无参

实例方法，同步滚动，隐藏到显示可调用该方法进行同步

四、配置

options

1. contentSelector

类型: string | HTMLElement
默认值: document.body

若为字符串，则必须是选择器，切可以通过ducument.querySelector获取相应的元素

通过该选择器解析内容中的目录元素

2. scrollSelector

类型: string | HTMLElement
默认值: document.body

若为字符串，则必须是选择器，切可以通过ducument.querySelector获取相应的元素

滚动元素的选择器; 若内容不是整个文档，且滚动也不是整个文档，是文档内的某个容器滚动则需要指定该值，否则目录无法同步滚动

3. fixedSelector

类型: string | HTMLElement
默认值: 目录本身

若为字符串，则必须是选择器，切可以通过ducument.querySelector获取相应的元素

文档滚动到该选择器元素的位置就fixed在顶部

4. headingSelector

类型: string
默认值: h1, h2, h3, h4, h5, h6

内容元素通过该选择器解析出所有的目录

1. 可以不是h标签，但是标签要提供属性 data-level 已指定当前目录的层级
2. 具体用法是[contentSelector].querySelectorAll(headingSelector), 所以需要正确配置 contentSelector和headingSelector, 否则解析的目录将会为空

5. collapsedLevel

类型: number
默认值: 3

该层级以上的目录将默认折叠(隐藏)，当内容滚动该位置对应的目录或点击后都将自动展开，之后又将折叠

6. idPrefix

类型: string
默认值: bitoc-heading-

目录ID的前缀

仅影响目录本身，对文档内容不产生副作用

7. levelClassPrefix

类型: string
默认值: bitoc-ml-

层级偏移样式前缀，默认二级目录(bitoc-ml-2)偏移1rem, 三级目录(bitoc-ml-3)偏移2rem, 以此累加；可用样式更改，默认样式名

• 一级目录: bitoc-ml-1
• 二级目录: bitoc-ml-2
• 三级目录: bitoc-ml-3
• 四级目录: bitoc-ml-4
• 五级目录: bitoc-ml-5
• 六级目录: bitoc-ml-6

8. scrollDuration

类型: number
默认值: 200

默认支持滚动动画，动画的持续时间由该值控制

9. scrollOffset

类型: number
默认值: 0

滚动偏移量

该值只针对内容，点击目录后内容会自动滚动到对应的位置；若内容顶部有fixed或absolute定位，滚动的位置将会有偏差，解决的方案有两种: 假设fixed定位元素的高度为 64px:

• 方案一: 使用css将所有的标题padding-top等于头部的高, margin-top等于头部高的相反值; 示例css代码如下

  [contentSelector] h1,
  [contentSelector] h2,
  [contentSelector] h3,
  [contentSelector] h4,
  [contentSelector] h5,
  [contentSelector] h6{
    margin-top: -64px;
    padding-top: 64px;
  }
• 方案二: 配置scrollOffset值为 64, 不要加单位
• 注意: 以上两种方案只能二选其一

10. fixedOffset

类型: number | false
默认值: 动态计算

目录滚动到该位置将自动停靠在顶部

1. 该值默认通过目录元素[fixedSelector]计算获取，若初始目录处于隐藏且整个文档有滚动的话，自动计算的值将会有很大的偏差，所以尽量要精确指定该值
2. 若顶部有fixed布局的元素，则需要减去fixed布局元素的高度，否则可能会有较大的抖动
3. 若该值为false, 将禁用停靠功能

11. fixedClassName

类型: string
默认值: .bitoc-fixed

目录停靠顶部样式，默认样式

.bitoc-fixed{
  position: fixed !important;
}

12. beforeFixed

类型: Function(isFixed: boolean) => false|void
默认值: null
目录 Fixed 前的钩子函数

isFixed = true,表示将要Fixed
isFixed = false, 表示将要取消Fixed
若返回false将取消fixed操作, 同时afterFixed也不会调用

13. afterFixed

类型: Function(isFixed: boolean) => void
默认值: null
目录Fixed后的钩子函数

isFixed = true,表示已经成功 Fixed
isFixed = false, 表示已经成功取消 Fixed

五、其他注意

1. 目录停靠默认没有指定top的偏移量，需要添加相应的样式；比如：假如顶部有fixed布局元素，且高度为64px,则需要添加样式

.bitoc-fixed{
  top: 3.875rem;
}

2. 目录本身并有宽度限制，fixed后整个目录将会被内容撑开，所以需要限制停靠后的目录宽度，示例:

 .bitoc-fixed {
    max-width: 27rem;
  }

使其支持响应式，示例:

 @media screen and (min-width: 1024px) and (max-width: 1216px) {
    #toc-box.bitoc-fixed {
      max-width: 19rem;
    }
  }

3. 目录本身没有高度限制，fixed后后目录可能会被内容撑开超出屏幕高度，需要添加高度限制，若目录达到该限制将自动滚动，无需添加其他样式，示例:

 .bitoc {
   max-height: 20.5rem;
}

六、开发

git clone https://github.com/itlangzi/toc-helper
cd toc-helper

开发环境

yarn dev --open

在浏览访问 http://localhost:3000/demo

构建生产版本

yarn build