DOCSEARCHbyAlgolia
Submit Docs

vue3-seamless-scroll

repository·main·Indexed 18 days ago

https://github.com/xfy520/vue3-seamless-scroll

A high-performance seamless scrolling component for Vue 3 that utilizes virtual list rendering to support large datasets and infinite scrolling via pagination. It provides Vue3SeamlessScroll, VerticalScroll, and HorizontalScroll components with configurable props for direction, speed, and animation effects, as well as methods for dynamically updating list data.

Tokens
2.1K
Snippets
6
Records
9
Agent score
13%

What's inside vue3-seamless-scroll

  1. Register vue3-seamless-scroll

    main

    You can register the component globally in your main application file or locally within a specific .vue component.

    // Global registration in main.js
import { createApp } from 'vue';
import App from './App.vue';
import vue3SeamlessScroll from "vue3-seamless-scroll";
const app = createApp(App);
app.use(vue3SeamlessScroll);
app.mount('#app');
    <script>
// Local registration in a .vue file
import { defineComponent } from "vue";
import { Vue3SeamlessScroll, VerticalScroll, HorizontalScroll } from "vue3-seamless-scroll";

export default defineComponent({
   components: {
     Vue3SeamlessScroll, // Supports both vertical and horizontal
     VerticalScroll,     // Vertical only
     HorizontalScroll    // Horizontal only
   }
})
</script>

  2. Install vue3-seamless-scroll

    main

    You can install the package using npm, Yarn, or via a browser <script> tag.

    # npm
npm install vue3-seamless-scroll --save

# Yarn
yarn add vue3-seamless-scroll
    <!-- browser -->
<script src="https://unpkg.com/browse/vue3-seamless-scroll@3.0.0/dist/vue3-seamless-scroll.min.js"></script>

  3. Configure vue3-seamless-scroll props

    main

    The component accepts several configuration options to control scrolling behavior, direction, and animation.

    PropTypeDefaultDescription
    listArray(Required)The seamless scroll list data.
    visibleCountNumber-Number of items required to trigger scrolling. If item height/width is consistent, it calculates automatically; otherwise, specify manually.
    v-modelBooleantrueControls animation scrolling and stopping.
    directionString"up"Scroll direction: up, down, left, or right.
    hoverBooleanfalseWhether to enable mouse hover effects.
    stepNumber0.5Step speed.
    singleWaitTimeNumber1000Waiting time for single step stop (in ms).
    delayNumber0Animation delay time.
    easeString"cubic-bezier(0.03, 0.76, 1, 0.16)"Animation effect (can be a Bezier curve value).
    wheelbooleanfalseWhether to enable mouse wheel scrolling when hover is enabled.
    singleLinebooleanfalseEnable single line horizontal scrolling.

  4. Install vue3-seamless-scroll in a Vue application

    main

    To install the component globally in a Vue 3 application, import the default export and call it with your app instance. This uses the install function internally to register the Vue3SeamlessScroll component.

    import Vue3SeamlessScroll from 'vue3-seamless-scroll';

const app = createApp(App);
app.use(Vue3SeamlessScroll);
app.mount('#app');

  5. Use vue3-seamless-scroll components

    main

    The library provides three main components: Vue3SeamlessScroll (supports both directions), VerticalScroll, and HorizontalScroll. Use the v-slot directive to render your custom list items.

    Important: The container element wrapping the scroll component must have the CSS style overflow: hidden;.

    <template>
  <!-- Vertical Scroll Example -->
  <div class="vertical-scoll" style="overflow: hidden; height: 300px;">
    <vertical-scroll :list="list">
      <template v-slot="{ data }">
        <span style="width: 100%; display: block; line-height: 30px;">
          <div>{{ data.name }}</div>
        </span>
      </template>
    </vertical-scroll>
  </div>

  <!-- Horizontal Scroll Example -->
  <div class="horizonta-scoll" style="overflow: hidden; height: 300px;">
    <horizontal-scroll :list="list">
      <template v-slot="{ data }">
        <div class="vertical-text">
          {{ data.name }}
        </div>
      </template>
    </horizontal-scroll>
  </div>
</template>

<script>
import { defineComponent, ref } from "vue";
import { Vue3SeamlessScroll, VerticalScroll, HorizontalScroll } from "vue3-seamless-scroll";

export default defineComponent({
  components: {
    Vue3SeamlessScroll,
    VerticalScroll,
    HorizontalScroll
  },
  setup() {
    const listData = Array.from({ length: 10000 }, (_, i) => ({
      id: Date.now() + i + 1,
      name: `Data item ${i + 1}`,
    }));
    const list = ref(listData);
    return { list };
  },
});
</script>

  6. Use component methods: add, remove, update, and reset

    main

    The component exposes methods to manipulate the list data and component state dynamically.

    • add(index, values, cb): Adds multiple items at a specific index. values is an array of data. cb is a callback receiving the complete updated array.
    • remove(index, num, cb): Removes num items starting from index. cb is a callback receiving the complete updated array.
    • update(index, value, cb): Updates the element at index with value. cb is a callback receiving the complete updated array.
    • reset(): Resets the component state. Call this if the outer container's size changes.

  7. Handle component events: offset and count

    main

    The component emits events that allow for advanced data handling like infinite scrolling.

    • offset(bufferSize, targetList): Triggered when cached data is updated. Use this to implement paginated/infinite scrolling. bufferSize is the displayed cache count, and targetList is the original array.
    • count(count): Triggered when a full scrolling cycle is completed. count represents the number of completed cycles.

  8. Import specific scroll components

    main

    The package exports individual components if you want to use them directly without the wrapper or for specific layout needs:

    • VerticalScroll: The vertical scrolling component.
    • HorizontalScroll: The horizontal scrolling component.
    • Vue3SeamlessScroll: The main wrapper component.
    import { VerticalScroll, HorizontalScroll, Vue3SeamlessScroll } from 'vue3-seamless-scroll';

  9. Register Vue3SeamlessScroll component manually

    main

    If you prefer not to use app.use(), you can manually register the component using the install pattern or by accessing the component directly. The install function accepts an options object where you can specify a custom name for the component.

    import { Vue3SeamlessScroll } from 'vue3-seamless-scroll';

// Manual registration
app.component('MyScrollComponent', Vue3SeamlessScroll);