vue-waterfall-easy

repository·master·Indexed 21 days ago

https://github.com/lfyfly/vue-waterfall-easy

A Vue.js component for creating responsive waterfall flow layouts with built-in infinite scroll loading. It automatically determines image dimensions via preloading, removing the need for manual width/height data. Features include customizable gaps, column limits, router-link support, and slots for custom loading and head/footer content. Version 2.4.4.

Tokens: 4.4K
Snippets: 16
Records: 19
Agent score: 70%

What's inside vue-waterfall-easy

Customize the waterfall using slots

master

The component provides several slots for customization:

default: Custom picture description element. Provides props.index and props.value (the item from imgsArr).
loading: Custom loading element. Provides { isFirstLoad }.
waterfall-head: Content to be placed at the top of the waterfall container.
waterfall-over: Content to be shown when the waterfallOver method is called.

<!-- Default Slot Example -->
<vue-waterfall-easy :imgsArr="imgsArr" @scrollReachBottom="getData">
  <div class="img-info" slot-scope="props">
    <p class="some-info">picture index: {{props.index}}</p>
    <p class="some-info">{{props.value.info}}</p>
  </div>
</vue-waterfall-easy

<!-- Loading Slot Example -->
<div slot="loading" slot-scope="{isFirstLoad}">
  <div v-if="isFirstLoad">first-loading...</div>
  <div v-else>loading...</div>
</div>

<!-- Waterfall Over Slot Example -->
<div slot="waterfall-over">No more data</div>

Import vue-waterfall-easy using ES6 modules
master
For modern build systems, import the component and register it in your Vue instance:
```
import vueWaterfallEasy from 'vue-waterfall-easy'

export default {
  name: 'app',
  components: {
    vueWaterfallEasy
  }
}
```
https://github.com/lfyfly/vue-waterfall-easy/blob/master/README.md
Import vue-waterfall-easy via script tags
master
For non-module environments, include Vue and the vueWaterfallEasy.js script in your HTML. Then register the component in your Vue instance.
```
<script src="path/to/vue/vue.js"></script>
<script src="path/to/vueWaterfallEasy.js"></script>

<script>
new Vue({
  el: '#app',
  components: {
    vueWaterfallEasy
  }
})
</script>
```
https://github.com/lfyfly/vue-waterfall-easy/blob/master/README-CN.md
Ensure correct CSS for container height
master
Because the component is responsive and relies on parent dimensions, ensure that the ancestor elements (including html, body, and #app) have defined heights. If the component is not set to a fixed width, its parent must be 100% of the viewport width.
```
html, body, #app {
  height: 100%;
  width: 100%;
}
```
https://github.com/lfyfly/vue-waterfall-easy/blob/master/README-CN.md
Install vue-waterfall-easy via npm
master
To use the component in your Vue project, install it as a dev dependency using npm.
```
npm install vue-waterfall-easy --save-dev
```
https://github.com/lfyfly/vue-waterfall-easy/blob/master/README-CN.md
Build and run the vue_origin project
master
This project uses standard Vue.js build scripts. You can install dependencies, start a development server with hot reloading, or build the project for production using the following commands.
```
# install dependencies
npm install

# serve with hot reload at localhost:8080
npm run dev

# build for production with minification
npm run build

# build for production and view the bundle analyzer report
npm run build --report
```
https://github.com/lfyfly/vue-waterfall-easy/blob/master/VUE-CLI-README.md
Import vue-waterfall-easy via scripts
master
If you are not using a module bundler, download vueWaterfallEasy.js and include it via script tags after Vue.js:
```
<script src="path/to/vue/vue.js"></script>
<script src="path/to/vueWaterfallEasy.js"></script>

<script>
new Vue({
  el: '#app',
  components: {
    vueWaterfallEasy
  }
})
</script>
```
https://github.com/lfyfly/vue-waterfall-easy/blob/master/README.md
Import vue-waterfall-easy using ES6
master
Import the component in your Vue file and register it in the components option.
```
import vueWaterfallEasy from 'vue-waterfall-easy'

export default {
  name: 'app',
  components: {
    vueWaterfallEasy
  }
}
```
https://github.com/lfyfly/vue-waterfall-easy/blob/master/README-CN.md
Implement infinite scroll with vue-waterfall-easy
master
The component supports infinite scrolling via the @scrollReachBottom event.
Important Data Handling Patterns:
- Incremental Update (Recommended): When fetching new data, use .concat() to merge the new items with the existing imgsArr. This is more performant.
- Replacement Update: Overwriting the entire imgsArr with new data is possible but less efficient for continuous scrolling.
To ensure mobile responsiveness, add this meta tag to your index.html <head>: <meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no">
```
<vue-waterfall-easy :imgsArr="imgsArr" @scrollReachBottom="getData"></vue-waterfall-easy>
```
```
export default {
  data() {
    return {
      imgsArr: [],
      group: 0,
    }
  },
  methods: {
    getData() {
      axios.get('./static/mock/data.json?group=' + this.group)
        .then(res => {
          // Incremental update pattern
          this.imgsArr = this.imgsArr.concat(res.data)
          this.group++
        })
    },
  },
  created() {
    this.getData()
  }
}
```
https://github.com/lfyfly/vue-waterfall-easy/blob/master/README.md
Configure viewport for mobile compatibility
master
To ensure proper mobile responsiveness, add the following meta tag to your index.html <head>:
```
<meta name="viewport" content="width=device-width, initial-scale=1,maximum-scale=1, user-scalable=no">
```
https://github.com/lfyfly/vue-waterfall-easy/blob/master/README-CN.md

Configure vue-waterfall-easy component props

master

The following props are available to customize the waterfall layout:

Prop	Type	Default	Description
`imgsArr`	Array	`[]`	Required. Array of objects. Each object must have `src` and `href` properties.
`srcKey`	String	`'src'`	Key name for the image source if not `'src'`.
`hrefKey`	String	`'href'`	Key name for the link if not `'href'`.
`width`	Number	-	Container width (px). If fixed, this must be set. If not set, defaults to 100% of parent.
`height`	Number/String	-	Container height. If not set, defaults to 100% of parent (parent must have height).
`gap`	Number	`20`	Spacing between images on PC (px).
`mobileGap`	Number	`8`	Spacing between images on mobile (px).
`imgWidth`	Number	`240`	Image width (px).
`maxCols`	Number	`5`	Maximum number of columns.
`linkRange`	String	`'card'`	Clickable area: `'card'` (whole card), `'img'` (image only), or `'custom'` (via slot).
`isRouterLink`	Boolean	`false`	If `true`, uses `router-link` instead of `<a>` tags.
`reachBottomDistance`	Number	`0`	Distance from bottom (px) to trigger `scrollReachBottom` event.
`loadingDotCount`	Number	`3`	Number of dots in loading animation.
`loadingDotStyle`	Object	`null`	Custom style for loading dots.
`loadingTimeOut`	Number	`500`	If preload < this value (ms), loading animation is hidden.
`cardAnimationClass`	String	`'default-card-animation'`	CSS class for entry animation. Set to `""` to disable.
`enablePullDownEvent`	Boolean	`false`	Enables pull-down events.

Configure vue-waterfall-easy props

master

Use the following props to customize the waterfall layout and behavior:

Prop	Type	Default	Description
`imgsArr`	Array	`[]`	Required. Array of objects. Each must have `src` and `href`.
`srcKey`	String	`'src'`	Key name for the image source if not `src`.
`hrefKey`	String	`'href'`	Key name for the link if not `href`.
`width`	Number	`-`	Container width (px). If using responsive layout, parent must be 100% width. If fixed, you must set this prop.
`height`	Number\|String	`-`	Container height. If not specified, defaults to 100% of parent height.
`gap`	Number	`20`	Space between pictures on PC (px).
`mobileGap`	Number	`8`	Space between pictures on Mobile (px).
`imgWidth`	Number	`240`	Width of the picture (px).
`maxCols`	Number	`5`	Maximum number of columns.
`linkRange`	String	`'card'`	Click trigger range: `'card'` (whole card), `'img'` (image only), or `'custom'` (via slots).
`isRouterLink`	Boolean	`false`	If `true`, renders `router-link` instead of `<a>` tag.
`reachBottomDistance`	Number	`0`	Distance (px) from bottom to trigger `@scrollReachBottom`.
`loadingDotCount`	Number	`3`	Number of dots in loading animation.
`loadingDotStyle`	Object	`null`	Style object for loading dots.
`loadingTimeOut`	Number	`500`	If preloading < this ms, don't show loading animation.
`cardAnimationClass`	String	`'default-card-animation'`	Animation class name for the card.
`enablePullDownEvent`	Boolean	`false`	Enable drop-down events.