outline.js - 自动生成文章导读（Table of

outline.js

outline.js - 自动生成文章导读（Table of Contents）导航的 JavaScript 工具。

创作灵感

AnchorJS 是 outline.js 的创作灵感来源。既然 AnchorJS 可创建标题的链接，为什么不直接给文章生成一个文章导读（Table of Contents）导航呢？ 于是就有了 outline.js。

特点 原生 JavaScript 编写，无需任何依赖； 支持 UMD 规范； 支持 E6 模块，提供功能独立的 ES6 模块； Anchors 模块：类似 AnchorJS 基础功能模块，自动分析段落层级 Drawer 模块：独立的侧滑窗口模块 Chapters 模块：独立的导航菜单模块； Toolbar 模块：独立的固定定位的工具栏模块； 拥有 AnchorJS 基础功能； 支持中文和英文标题文字生成ID； 支持生成独立的侧边栏导航菜单； 支持直接在文章中生成文章导读导航(fixed 或者 sticky 布局)； 自动分析标题关系，生成段落层级索引值； 可以作为 jQuery 插件使用； 界面简洁大方； 配置灵活，丰富，让你随心所欲掌控 outline.js； 浏览器支持

IE / Edge	Firefox	Chrome	Safari	Opera
IE11, Edge	last 10 versions	last 10 versions	last 10 versions	last 10 versions

安装说明

outline.js 提供多种安装方式的支持： npm 安装、加载 CDN 资源、以及本地资源调用。

npm install

$ npm install -S @yaohaixiao/outline.js CDN 调用

<link href="https://cdn.jsdelivr.net/gh/yaohaixiao/outline.js/outline.min.css" rel="stylesheet" /> <script src="https://cdn.jsdelivr.net/gh/yaohaixiao/outline.js/outline.min.js"></script> 调用本地JS文件

<link href="path/to/outline.min.css" rel="stylesheet" /></script> <script src="path/to/outline.min.js"></script> 使用说明

outline.js 既支持在 node.js 环境中以 CommonJS 模块调用，也支持 ES6 模块方式加载。

// Node.js 环境中使用 const Outline = require('@yaohaixiao/outline.js') // 调用其他独立模块（如果需要） const Anchors = require('@yaohaixiao/outline.js/anchors.min.js') const Chapters = require('@yaohaixiao/outline.js/chapters.min.js') const Drawer = require('@yaohaixiao/outline.js/drawer.min.js') const Toolbar = require('@yaohaixiao/outline.js/toolbar.min.js') // 作为 ES6 模块使用 import Outline from '@yaohaixiao/outline.js/src/outline' // 调用其他独立模块（如果需要） import Anchors from '@yaohaixiao/outline.js/src/anchors' import Chapters from '@yaohaixiao/outline.js/src/chapters' import Drawer from '@yaohaixiao/outline.js/src/drawer' import Toolbar from '@yaohaixiao/outline.js/src/toolbar' // 创建 Outline 实例 // 2.0.0 调整了配置参数，配置更加简单 // 当然，可以直接使用 DEFAULTS 静态属性， // Outline.DEFAULTS 就是一下的默认配置 const outline = new Outline({ // 文章显示区域的 DOM 元素或者选择器字符串 articleElement: '#article', // 要收集的标题选择器 selector: 'h2,h3,h4,h5,h6', // 指定文章导读导航菜单的标题文字。 title: '目录', // 负责文章区域滚动的元素 // String 类型 - 选择器字符串，默认值：html,body（window窗口） // HTMLElement 类型 - DOM 元素 scrollElement: 'html,body', // 文章导读菜单的位置 // relative - （默认值）创建独立的侧滑菜单 // sticky - 导航菜单将以 sticky 模式布局（需要确保菜单插入位置支持 sticky 模式布局） // fixed - 导航菜单将以 fixed 模式布局，会自动监听滚动位置，模拟 sticky 布局 // sticky 和 fixed 布局时，需要设置 parentElement // 2.0.0 暂时不支持之前版本那种 inside 模式，不会自动在文章开始位置插入 chapters 导航菜单 position: 'sticky', // 导航菜单将要插入的位置（DOM 元素） // String 类型 - 选择器字符串 // HTMLElement 类型 - 插入的 DOM 元素 // 仅在 position 设置为 sticky 和 fixed 布局时有效 parentElement: '#aside', // 设置 position: relative 时，placment 定义侧滑菜单和 toolbar 导航位置： // rtl - 菜单位置在窗口右侧，滑动动画为：right to left // ltr - 菜单位置在窗口左侧，滑动动画为：left to right // ttb - 菜单位置在窗口上方，滑动动画为：top to bottom // btt - 菜单位置在窗口下方，滑动动画为：bottom to top placement: '', // 是否显示段落章节编号 showCode: true, // 标题图标链接的 URL 地址 // （默认）没有设置定制，点击链接页面滚动到标题位置 // 设置了链接地址，则不会滚动定位 anchorURL: '', // DIYer的福利 // 独立侧滑菜单时，customClass 会追加到 drawer 侧滑窗口组件 // 在文章中显示导航菜单时，customClass 会追加到 chapters 导航菜单 customClass }); // 可以在创建导航后，重置配置信息，重新生成新的导航 Outline.reload({ // 调整位直接在文章内生成导航 position: 'sticky', articleElement: '#article' }) Example

Example 地址：https://yaohaixiao.github.io/outline.js/example.html

API Documentation

完整 API 文档地址：https://yaohaixiao.github.io/outline.js/

Options

outline.js 提供了较为丰富的配置项，以便适应不同的展示方式。

articleElement

Type: String|Element

Default: '#article'

String： 选择器字符串，默认值：html,body（即 window 窗口）; HTMLElement： DOM 元素;

可选，用来指定页面中显示文章正文的 DOM 节点或者选择器字符串。

selector

Type: String

Default: 'h1,h2,h3,h4,h5,h6'

可选，用来指定 article 节点下，要生成导航的标题标签的选择器。

title

Type: String

Default: '目录'

可选，用来指定文章导读导航菜单的标题文字。

scrollElement

Type: String|HTMLElement

Default: html,body

String： 选择器字符串，默认值：html,body（即 window 窗口）; HTMLElement： DOM 元素;

可选，负责文章区域滚动的元素：

position

Type: String

Default: 'relative'

可选，用来指定文章导读导航菜单的显示位置：

relative: （默认值）创建独立的侧滑菜单； sticky: 导航菜单将以 sticky 模式布局（需要确保菜单插入位置(DOM 节点)支持 sticky 模式布局）； fixed: 导航菜单将模拟 sticky 布局，起初是普通定位，会自动监听滚动位置，但滚动到导航菜单顶部时，以 fixed 模式布局，模拟 sticky 布局效果；

当设置为 sticky 和 fixed 布局时，需要设置 parentElement。

注意：2.0.0 暂时不支持之前版本那种 inside 模式，不会自动在文章开始位置插入 chapters 导航菜单

parentElement

Type: String|HTMLElement

Default: #aside

String： 选择器字符串，默认值：html,body（即 window 窗口）; HTMLElement： DOM 元素;

可选，导航菜单将要插入的位置（DOM 元素）。仅在 position 设置为 sticky 和 fixed 布局时有效。

placement

Type: String

Default: rtl

可选，设置 position: relative 时，placement 定义侧滑菜单和 toolbar 导航位置：

rtl - 菜单位置在窗口右侧，滑动动画为：right to left（默认值）； ltr - 菜单位置在窗口左侧，滑动动画为：left to right； ttb - 菜单位置在窗口上方，滑动动画为：top to bottom； btt - 菜单位置在窗口下方，滑动动画为：bottom to top； showCode

Type: Boolean

Default: true

可选，是否显示段落章节编号：

true - 显示编号（默认值）； false - 不显示编号； anchorURL

Type: String

Default: ''

可选，用来指定文章标题锚点链接图标的链接地址：

'' - 点击链接页面滚动到标题位置（默认值）； 其它 URL 值 - 就直接跳转到指定页面了； customClass

Type: String

Default: ''

可选，(DIYer福利)设置自定义样式的 class 名称：

'' - 采用默认 outline.js 的 UI 界面（默认值）； 设置自定义样式 - 自己根据需求设置个性化的 UI 界面； Properties

outline.js 重构后，对外放 4 个重要的属性：anchors、drawer、chapters 和 toolbar。它们都是独立的对象实例，提供了 outline.js 所有的属性和方法。

DEFAULTS

Type: Objects

静态属性，存储的是 Outline 对象默认配置信息。

Outline.DEFAULTS = { articleElement: '#article', selector: 'h2,h3,h4,h5,h6', title: '目录', scrollElement: 'html,body', position: 'relative', parentElement: '#aside', placement: 'rtl', showCode: true, anchorURL: '', customClass: '' } attrs

Type: Objects

存储的是 Outline 对象当前使用中的配置选项。

anchors

Type: Objects

Anchors 模块：类似 AnchorJS 基础功能模块，自动分析段落层级。

chapters

Type: Objects

Chapters 模块：独立的导航菜单模块。

drawer

Type: Objects

Drawer 模块：独立的侧滑窗口模块。

toolbar

Type: Objects

Toolbar 模块：独立的固定定位的工具栏模块；

Methods

outline.js 的提供的方法如下：

attr([prop, value])

设置或者获取初始化时配置的 attrs 信息的。

Parameters prop

Type: String|Object

（可选）attrs 中的属性名称或者要配置的 attrs 信息。

value

Type: Any

（可选）要设置的 prop 属性的值。

不传递任何参数：返回完整的 attrs 配置信息； 仅传递 prop： String: 返回 attrs 配型信息中与 prop 对应的值； Object: 用来设置 attrs 配置信息； 同时传递 prop 和 value 参数：设置 attrs 配置信息中的某个属性值； Returns

Type: Any

Outline 对象，以便实现链式调用。

getChapters()

返回 outline.js 分析后的文章段落信息数据。

Returns

Type: Outline对象

Outline 对象，以便实现链式调用。

toTop()

页面（scrollElement）滚动到顶部。

Returns

Type: Outline对象

Outline 对象，以便实现链式调用。

toBottom()

页面（scrollElement）滚动到底部。

Returns

Type: Outline对象

Outline 对象，以便实现链式调用。

scrollTo(top[, afterScroll])

页面滚动到指定 top 位置。

Returns

Type: Outline对象

Outline 对象，以便实现链式调用。

Parameters top

Type: Number

（必须）指定滚动位置的 top 数值。

afterScroll

Type: Function

（可选）滚动结束后的回调行数。

Returns

Type: Outline对象

Outline 对象，以便实现链式调用。

toggle()

隐藏或者显示导航菜单。

Returns

Type: Outline对象

Outline 对象，以便实现链式调用。

destroy()

销毁 outline.js 创建的所有 anchors 链接和导航菜单，已经对应的事件绑定。

Returns

Type: Outline对象

Outline 对象，以便实现链式调用。

reload(options)

程序重启，先执行 destroy() 方法执行程序销毁逻辑，然后重新初始化并重新绘制界面。

Parameters options

Type: Object

（必须）指定重启程序的新的配置信息（参考 DEFAULT 属性）。

Returns

Type: Outline对象

Outline 对象，以便实现链式调用。

License

JavaScript Code Licensed under MIT License.

API Documentation Licensed under CC BY 3.0