• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

toc-helper: 为文章动态生成侧边栏目录以及静态侧边栏目录的滚动效果 ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称:

toc-helper

开源软件地址:

https://gitee.com/itlangz/toc-helper

开源软件介绍:

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

  1. 使用
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
默认值:
必须:可选

resetHeadings

无参

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

isEmpty

无参

实例方法,判断是否有 heading

四、配置

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), 所以需要正确配置 contentSelectorheadingSelector, 否则解析的目录将会为空

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;}
  1. 目录本身并有宽度限制,fixed后整个目录将会被内容撑开,所以需要限制停靠后的目录宽度,示例:
 .bitoc-fixed {    max-width: 27rem;  }

使其支持响应式,示例:

 @media screen and (min-width: 1024px) and (max-width: 1216px) {    #toc-box.bitoc-fixed {      max-width: 19rem;    }  }
  1. 目录本身没有高度限制,fixed后后目录可能会被内容撑开超出屏幕高度,需要添加高度限制,若目录达到该限制将自动滚动,无需添加其他样式,示例:
 .bitoc {   max-height: 20.5rem;}

六、开发

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

开发环境

yarn dev --open

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

构建生产版本

yarn build

鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
热门话题
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap