intersection.js
intersection.js - 通用的 IntersectionObserver 观察者处理器功能函数。
项目初衷
intersection.js 是作为 outline.js 项目的一个工具 intersection() 函数开发出来的。由于很多场景都适合使用 IntersectionObserver API,所以就整理干脆将之独立通用的工具。
Features
- 原生 JavaScript 编写,无任何依赖;
- 支持 UMD 模块规范;
- 支持 ES6 模块调用;
- 文件体积小(GZip:1KB),加载速度快;
Browsers support
Edge | Firefox | Chrome | Safari | Opera |
---|---|---|---|---|
Edge | last 10 versions | last 10 versions | last 10 versions | last 10 versions |
Install
intersection.js 支持 AMD 和 CommonJS 规范的模块调用方式,可以直接使用 npm 安装,也可以使用 script 标签引入到页面。
npm install
npm i -S @yaohaixiao/intersection.js
script
可以根据项目的实际情况,选择调用 CDN 文件或者本地文件。
CDN
<script src="https://cdn.jsdelivr.net/gh/yaohaixiao/intersection.js/intersection.min.js"></script>
Local
<script src="path/to/intersection.min.js"></script>
API Documentation
intersection.js 提供了一个核心方法 intersection().
intersection(fn[, props])
Parameters
fn
Type: Function
Default: ``
(必须)IntersectionObserver 观察者符合触发规则时的回调函数;
props
Type: Object
Default: {}
(可选)表示基准 URL 的字符串。在 url 是相对 URL 时,它才会起效。如果未指定,则默认为 ”;
Name | Type | Default | Description |
---|---|---|---|
selector |
String |
'.outline-heading' | 可选,用来指定要观察的 DOM 元素的选择器。 |
context |
Object |
null | 可选,fn 回调函数的 this 执行上下文。 |
root |
String, HTMLElement |
null | 可选,指定根 (root) 元素,用于检查目标的可见性。必须是目标元素的父级元素。如果未指定或者为null,则默认为浏览器视窗。 |
threshold |
Number, Array |
0 | 可以是单一的 number 也可以是 number 数组,target 元素和 root 元素相交程度达到该值的时候 IntersectionObserver 注册的回调函数将会被执行。 |
rootMargin |
String |
'0px 0px -90% 0px' | 可选,根 (root) 元素的外边距。类似于 CSS 中的 margin 属性,比如 "10px 20px 30px 40px" (top、right、bottom、left)。如果有指定 root 参数,则 rootMargin 也可以使用百分比来取值。该属性值是用作 root 元素和 target 发生交集时候的计算交集的区域范围,使用该属性可以控制 root 元素每一边的收缩或者扩张。默认值为四个边距全是 0。 |
Returns
Type: IntersectionObserver
IntersectionObserver 对象实例,以便调用 disconnect()、observe()、takeRecords() 等方法。
Usage
import intersection from '@yaohaixiao/intersection.js/intersection'
const Chapters = {
// 省略其它逻辑
onObserver() {
const selector = this.attr('selector')
let timer = null
intersection(
($heading) => {
// fn 回调函数的参数有一个,就是当前触发 Observer 的被观察 DOM 元素
const id = $heading.getAttribute('data-id')
if (this.playing) {
return false
}
if (timer) {
clearTimeout(timer)
}
timer = later(() => {
this.highlight(id)
}, 100)
},
// 指定 fn() 的 this 为当前对象,其余都使用默认值
// 因为当时就是为 outline.js 开发的,所有默认值即可
{
selector,
context: this
}
)
return this
},
removeListeners() {
const selector = this.attr('selector')
// 省略其它逻辑...
if (this.Observer) {
document.querySelectorAll(selector).forEach((section) => {
this.Observer.unobserve(section)
})
}
return this
}
}
License
Licensed under MIT License.