Awesome

any-scroll

模拟滚动插件,支持滚轮和手势, 手势识别基于any-touch.

概念(wrap/content)

any-scroll的滚动实际是通过2个"父子div"的相对位置变化模拟的, 默认使用translate3d, 外层div叫"wrap", 里面用来装载内容的div叫"content".

<div> <!-- warp --> 
    <div> <!-- content -->
        content
    </div>
</div>

⚡⚡⚡ 多个content

如果wrap下有多个元素, 那么any-scroll会把他们都构造成content实例, 但是只有一个"激活"状态的content实例, 只有他可以响应滚动, 当然你也可以切换任意content实例为激活.

<!-- warp --> 
<div> 
    <!-- content -->
    <div>content-1<div> 

    <!-- content -->
    <div style="position: absolute;z-index:1;top:0;left:0;">
        content-2
    <div> 
    
    <!-- content -->
    <div no-scroll>content-3<div> 
</div>

注意:

1. 多个content情况下, 请给第二个子元素做一个"初始定位", 比如style="position: absolute;z-index:1;top:0;left:0;", any-scroll内部没有默认定位, 这样你可以自定义"位置"和"层级".
2. 如果不想某个子元素(content)"可滚动", 使用"no-scroll"进行标记.

🚀返回目录

目录

• 概念
• 安装
• 使用
• API
  • 选项
  • 实例属性
    • el : wrap元素
    • size : wrap元素尺寸
    • at : any-touch实例
  • 实例方法
    • on : 监听事件
    • scrollTo : 动画滚动
    • moveTo : 瞬移
    • scrollToElement : 移动元素到wrap左上角
    • dampScroll : 衰减滚动
    • update : 更新"可滑动范围"
    • getContentRef : 获取content实例(其上有尺寸数据)
    • active : 激活content实例"
  • 事件
    • scroll : 滚动
    • scrollEnd : 滚动结束
    • tap : 单击
    • press : 按压
    • pressup : 按压释放
    • pan : 拖拽
    • swipe : 滑动
    • pinch : 缩放
    • rotate : 旋转
• 进阶使用
  • 支持更多手势(tap/press/pinch/rotate)
• 常见问题
  • no-scroll : 不滚动
  • ResizeObserver : 监视内容变化

安装

npm i any-scroll -S

🚀返回目录

使用

首先在页面构造如下html结构, 同时给wrap一个固定尺寸.

<div id="scroll-view" style="height:600px;width:360px;"><!-- wrap -->
    <div><!-- content -->
        <!-- 你的内容写在这里 -->
    <div>
</div>

初始化:

import AnyScroll from 'any-scroll';
const el = document.getElementById('scroll-view');
const as = new AnyScroll(el);

// 滚动到x=-100,y=-100的位置.
as.scrollTo([-100,-100]);

// 只控制Y轴,1s内滑动到目标位置
as.scrollTo({y:-100},1000);

🚀返回目录

API

• 选项
• 实例属性
• 实例方法
• 事件

选项

render

默认通过translate3d控制content的位移, 如有需要也可改为控制margin或 top(left) 属性.

// 默认
function render(el, [x, y]) {
    el.style.setProperty('transform',`translate3d(${x}px, ${y}px,0)`);
}

// 或者改为
function render(el, [x, y]) {
    el.style.setProperty('marginLeft', x+'px');
    el.style.setProperty('marginTop', y+'px');
}

const as = new AnyScroll({render});

🚀返回目录

实例方法

on

监听事件, 默认继承了any-touch的所有手势事件.

as.on('scroll-end',()=>{
    console.log('滚动停止了');
})

:rocket: 返回目录

scrollTo

滚动到指定位置, 支持时间动画

参数

// 3秒钟移动到x=-100,y=-500的位置.
as.scrollTo([-100,-500],3000);
// 等价写法
as.scrollTo({x:100,y:-500},3000);

:rocket: 返回目录

moveTo

瞬间移动到目标位置

as.moveTo([-100,-200]);

:rocket: 返回目录

scrollToElement

移动元素到wrap左上角.

参数

// 滚动到content中的子元素(child-1), 让其左上角和wrap的左上角重合.
const childEl = doucument.getElementById('child-1');
as.scrollToElement(childEl);
// 滚动到child-1下方100px的位置
as.scrollToElement(childEl,{y:100});
// 等价写法
as.scrollToElement(childEl,[,100]);

:rocket: 返回目录

dampScroll

作用同scrollTo,只是滚动效果不同, 其不能指定时间. 仅供插件开发者使用, 模拟快速划动scrollView产生的滚动.

参数

as.dampScroll([-100,-200]);

:rocket: 返回目录

update

如果滚动范围出现异常, 可手动更新.

as.update();

:rocket: 返回目录

getContentRef

获取content实例, 其上有尺寸等数据.

参数

elOrIndex不同的值

1. 如是number, 那么会按照wrap下的子元素索引取对应的content实例.
2. 如是元素, 那么会递归向上找父元素, 直到找到对应的实例.
3. 如果不传默认找当前激活状态的content实例.

as.getContentRef(1);
as.getContentRef(childEl);
as.getContentRef();

返回值

content实例或null.

:rocket: 返回目录

active

如果有多个content实例, 激活指定content实例, 只有激活的content才会响应滚动.

参数

// 激活第二个content实例.
const contentRef = as.getContentRef(1);
as.active(contentRef);

:rocket: 返回目录

实例属性

el

wrap元素

as.el; // <div class="any-scroll"></div>

🚀返回目录

at

any-scroll内部使用了any-touch手势库, 通过as.at可以访问any-touch的实例,从而修改手势行为等, 详情参考any-touch

// 仅对表单元素阻止触发"默认事件"
// 这是any-touch参数的默认值, 在此仅做展示
as.at.set({
    preventDefault(e){
        if (event.target && 'tagName' in event.target) {
            const { tagName } = event.target;
            return !/^(?:INPUT|TEXTAREA|BUTTON|SELECT)$/.test(tagName);
        }
        return false;
    }
})

注意: 普通开发者谨慎使用, 修改不当会影响滚动效果, 如开发中遇到缺少功能, 大家尽量先提Issue

🚀返回目录

size

wrap元素尺寸.

console.log(as.size);

🚀返回目录

事件

as.on('scroll', context=>{
    // 当前位置信息
    // context === as
    console.log(context.xy);
});

除了"scroll"和"scroll-end", 其他事件都是any-touch实现的, 其事件对象上包含当前触点/距离/速度等信息, 更多请参考any-touch

as.on('tap', e=>{
    // 当前触点x坐标
    console.log(e.x)
})

🚀返回目录

进阶使用

支持更多手势

any-scroll基于any-touch开发, 所以也支持他的所有手势, 但是为了体积默认只加载了swipe/pan, 开启更多方法:

import AScroll from 'any-scroll';
import tap from '@any-touch/tap';
import swipe from '@any-touch/swipe';
import pinch from '@any-touch/pinch';
import rotate from '@any-touch/rotate';

const as = new AScroll();
// 加载单击手势
as.at.use(tap);
// 加载快划
as.at.use(swipe);
// 加载缩放
as.at.use(pinch);
// 加载旋转
as.at.use(rotate);

as.on('tap',e=>{

});

🚀返回目录

常见问题

no-scroll

如果wrap下的子元素, 有些你并不想让他"滚动", 可以给其加"no-scroll"标记.

<div>
    <div></div> <!-- 能滚动 -->
    <div no-scroll></div> <!-- 不能滚动 -->
</div>

🚀返回目录

监视内容变化

当content中的子元素发生变化(增/减去/尺寸), any-scroll需要重新计算"可滑动范围".

默认any-scroll内部使用ResizeObserver(caniuse)监视wrap/content尺寸变化, 实现自动更新可滑动范围.

但其兼容性较差, 所以在不支持ResizeObserver的浏览器会使用MutationObserver(caniuse)降级兼容, 其只能监视content的子元素的增/减, 从而更新滑动范围.

resize-observer-polyfill

如果不在意体积, 可以使用"resize-observer-polyfill", 其可让ResizeObserver兼容到最低IE9.

import ResizeObserver from 'resize-observer-polyfill';
// ⭐注入到全局
window.ResizeObserver = ResizeObserver;

import AnyScroll from 'any-scroll';
const as = new AnyScroll(el);

手动更新

使用实例上的"update"方法更新"可滑动范围".

🚀返回目录