@b-design/scroll

About

B-Design 是阿里云推出的一套面向企业应用领域的设计系统。在企业级软件服务逐渐走向云端化的趋势下，为阿里内部及合作伙伴的 SaaS 系统上云提供标准化的设计规范和指导。@b-design/scroll 是 B-Design System 的页面级组件，基于 Alibaba Cloud Design 自研原生 JavaScript 能力，提供自动化（CSS 样式）与定制化（JS 事件）的页面滚动视效管理，及丰富的 React 使用示例。可利用 @b-design/scroll 提供的锚点样式挂钩、函数接口、滚动比例(Ratio)，设计与开发丰富的滚动视效。

Live Example

Install

npm install @b-design/scroll --save

Usage

在 Javascript 中使用 @b-design/scroll

HTML

<!-- 指定锚点（必须） -->
<div anchor-scroll="anchor"></div>

<!--
  锚点 CSS 样式触发: anchor-trigger="repeat" | anchor-trigger="once"
  样式动画示例： @b-design/scroll 提供挂钩后 anchor-on 属性，e.g:

  .your-style{
    opacity: 0;
    transition: opacity 0.4s;
  }

  .your-style[anchor-on]{
    opacity: 1;
  }
-->
<div anchor-scroll="anchor" anchor-trigger="repeat" class="your-style"></div>

<!-- 锚点名字（可选） -->
<div anchor-scroll="anchor" anchor-trigger="repeat" anchor-name="your-name"></div>

Javascript

import { drone } from '@b-design/scroll';

// 查找、更新页面中 anchor-scroll 属性的元素
drone.update();

// 挂钩页面滚动时的函数回调事件，用于进阶特效
drone.hook(domElement, 'update', ({ name, isVisible, ratio }) => {
    if (isVisible && name === 'your-name') {
        // do something...
    }
});

// 清除所有锚点，不查找更新
drone.clear();

在 React 中使用 @b-design/scroll

import { drone } from '@b-design/scroll';

const MyComponent = (props) => {
    const elRef = React.useRef(null);

    React.useEffect(() => {
        // 查找、更新页面中 anchor-scroll 属性的元素
        drone.update();

        // 挂钩页面滚动时的函数回调事件，用于进阶特效
        // 注：事件与样式没有直接关系，若仅用事件可以无 anchor-trigger 属性
        drone.hook(elRef.current, 'update', ({ name, isVisible, ratio }) => {
            if (isVisible && name === 'your-name') {
                // ratio 为 0 - 1，元素进入页面可见时为 0，离开不可见时为 1
                // e.g: 利用滚动比例 ratio，横移 1000像素 示例
                elRef.current.style.transform = `translateX(${ratio * 1000}px)`;
            }
        });

        return () => {
            // 元素从页面移除时，查找更新锚点
            drone.update();
            // 清除所有锚点，不查找更新
            // drone.clear();
        };
    }, []);

    return;
    <div ref={elRef} anchor-scroll='anchor' anchor-name='your-name'></div>;
};

在 Vue3 中使用 @b-design/scroll

<template>
    <div class="page-home page">
        <h2 class="your-style"
            anchor-scroll="anchor"
            anchor-trigger="repeat"
            anchor-name="your-name"
            ref="elRef">
            {{ data.title }}
        </h2>
    </div>
</template>

/* scss */
.your-style {
    opacity: 0;
    transition: opacity 0.4s;

    &[anchor-on] {
        opacity: 1;
    }
}

import { ref, reactive, onBeforeUnmount, onMounted } from 'vue';
import { drone } from '@b-design/scroll';

export default {
    setup(props, context) {
        const elRef = ref(null);
        const data = reactive({
            title: 'Hey'
        });

        onMounted(() => {
            drone.update();
            drone.hook(elRef.value, 'update', ({ domElement, name, isVisible, ratio }) => {
                if (isVisible && name == 'your-name') {
                    // ratio 为 0 - 1，元素进入页面可见时为 0，离开不可见时为 1
                    domElement.style.transform = `scale(${ratio})`;
                }
            });
        });

        onBeforeUnmount(() => {
            // 元素从页面移除时，查找更新锚点
            drone.update();
            // 清除所有锚点，不查找更新
            // drone.clear();
        });

        return {
            elRef,
            data
        };
    }
};

在 React 中引用封装好滚动效果的 @b-design/scroll 页面级组件

import { drone } from '@b-design/scroll';
import { HorizontalMovement } from '@b-design/scroll/react';
// 手动引用组件样式，或者基于组件样式自行修改
import '@b-design/scroll/react/horizontal-movement/style.css';

const MyComponent = (props) => {
    React.useEffect(() => {
        drone.update();
        return () => {
            drone.update();
        };
    }, []);

    return <HorizontalMovement {...someConfigs} />;
};

API Reference

DOM 元素属性

anchor-scroll="anchor"

必须。带有此属性值的元素才会被指定锚点，用于 @b-design/scroll 查找、更新、计算

anchor-trigger="repeat|once"

非必须。注意 anchor-trigger 属性仅与 CSS 样式挂钩有关，与 hook 函数事件无关
当 anchor 元素进入页面时会被自动 trigger 样式，元素会增加 anchor-on attribute 属性，
用户可以在 CSS 中通过 [anchor-on] 选择器，自定义 trigger 后的样式
"once" 元素进入页面时，仅触发一次样式挂钩
"repeat" 元素进入页面时触发，离开页面时移除 anchor-on 属性，可反复触发样式挂钩

挂钩元素样式示例

.your-style {
    opacity: 0;
    transition: opacity 0.4s;
}
.your-style[anchor-on] {
    opacity: 1;
}

anchor-name="[your-name]"

非必须。其作用等同于标记一个字符串 ID，在 drone.hook 回调中会返回 name，用于更加定制化的事件和效果

Drone

drone

@b-design/scroll 的锚点控制与管理实例。用户侧无需创建，仅引用：

import { drone } from '@b-design/scroll';

drone.scrollTo({position, duration, ease})

页面滚动到 pageYOffset

drone.scrollToRatio({domElement, ratio, duration, ease})

页面滚动到相对于 domElement 元素在页面中的一定比例

drone.hook(domElement, type, cb)

挂钩 domElement 的 JS 函数事件，用于需要做 CSS 样式挂钩无法达到的进阶效果
注：@b-design/scroll 的事件机制与 CSS 样式的 anchor-trigger 为分离设计，
anchor-trigger 样式挂钩与 JS 事件的挂钩没有直接关系

/**
 * @param {HTMLElement} domElement - Dom Element
 * @param {'update' | 'trigger' | 'trigger:once' | 'after' | 'after:once'} hook event type
 * @param {(CallbackObject) => any} cb - Event callback，CallbackObject 定义如下：
 * @typedef {Object} CallbackObject
 * @prop {HTMLElement} domElement anchor元素
 * @prop {string} id 自动生成的 anchor uuid
 * @prop {string} name DOM元素anchor-name的值
 * @prop {'once'|'repeat'|undefined} triggerStyleType DOM元素anchor-trigger的值，触发css样式的方式
 * @prop {boolean} isVisible 是否进入可见区
 * @prop {boolean} isTriggered 是否已被触发
 * @prop {Object} rect DOM原色的getBoundingClientRect结果
 * @prop {number} ratio DOM元素在页面中的比例。刚进入页面时为0，离开页面时是1
 * @prop {number} viewportWidth window.innerWidth，避免反复计算
 * @prop {number} viewportHeight window.innerHeight，避免反复计算
 * @prop {number} pageRatio 整个页面的scroll比例
 * @prop {number} pagePosition  window.pageYOffset，避免反复计算
 * /

drone.unhook(domElement, item, cb)

移除 domElement 的挂钩回调事件
原则上如无需要不必调用此接口，JS 事件机制默认为自动回收清除与管理

/**
 * @param {HTMLElement} domElement - The Element which the hooked events are mounted on.
 * @param {HookEventType | HookEventType[]} item - Event types to be removed. Can be hook event type string or array.
 * @param {function} cb - Callback function.
 * /

drone.update()

查找并更新所有的锚点

drone.clear()

清除所有锚点, 不查找更新

drone.getPosition()

返回页面 Y Offset 值

drone.updateConfig(opts)

用于首次全局常规配置更新

opts: {
    /**
     * anchor-on
     * @default 'anchor-on'
     */
    triggerName?: string;
    /**
     * anchor-scroll="anchor"
     * @default 'anchor'
     */
    queryName?: string;
    /**
     * Offset of visibility.
     * @default 5
     */
    threshold?: number;
    /**
     * @default true
     */
    listener?: boolean;
}

Build Process

• npm i to install packages
• npm start to start development
• npm run lib to get @b-design/scroll library at 'esm' folder
• npm run live to build